DataSubscriber Feed API

Overview

As with all things in serviceminder, there are settings controlled by the organization and higher levels of control at the brand-level. The distinction between organization (franchisee) and brand (franchisor) allows for separation of what can be done in the system and also how that data is reported. The same holds true with the Feed API.

The DataSubscriber Feed API is at the brand-level. The franchisor can set this up for the brand as a whole to pull in data from all organizations at once. Feed is one-way. A brand fetches events and clears them, but you can't push anything into the feed.

The DataSubscriber API allows one to collect events which they want serviceminder to capture. We support three types of events:

Appointment Complete
Invoice Generated
Entity Deleted

The payloads for these events contain minimal data. For a more exhaustive data feed, we recommend either a custom DataSubscriber that can send data to your endpoint(s), or using the download endpoints to request/retrieve download files.

How to Set Up the API

Only a System Admin can generate datasubscriber feed keys. Please reach out to support or your Account Manager at serviceminder to start this process.

Once that is done, Brand Admin users will be able to configure what payload types are in the feed. Go to Dashboard > Tools > Configure:

Once enabled at the brand level, specific organizations may be opted-in by going to Control Panel > Integrations > Marketing:

Once that is saved, events will start to be queued-up in the feed. Use the fetch and clear endpoints to retrieve the events and then to clear them. Clearing events is important to empty out the queue. If events are not cleared, we may periodically remove events, including events which have not yet been fetched. We recommend always issuing a clear action after your fetch completes successfully.

Event Payloads

The records returned from the fetch call return payloads based on the type of event. The following payloads can be returned based on the brand's configuration.

TransactionKind => 0: Invoice, 1: Appointment, 2: Proposal, 3: Delete

Appointment Complete

{
    "TransactionKind": 1,

    "PriPhone": "2145551212",
    "AltPhone": "",
    "Email": "bob.smith@serviceminder.co",
    "Name": "Bob Smith",
    "Address1": "123 Main St",
    "Address2": "",
    "City": "Addison",
    "State": "TX",
    "PostalCode": "75001"

    "TransactionDate": "2023-4-5",
    "Subtotal": 100.50,
    "LifetimeValue": 200.75,

    "CreatedAt": "2023-3-39 08:45:17",
    "CustomerSince": "2023-04-05",

    "DigitalTrackingId": "trk-45-3344",
    "ContactId": 4724524324,
    "Hash": "abc123456789",
    "Channel": "Direct Mail",
    "Campaign": "City Pubs 2023",
    "AccountingClass": "NWDALLAS",

    "Unsubscribed": false,

    "LocationId": "loc123",
    "OrganizationId": 5412
}

Invoice Generated

{
    "TransactionKind": 1,

    "PriPhone": "2145551212",
    "AltPhone": "",
    "Email": "bob.smith@serviceminder.co",
    "Name": "Bob Smith",
    "Address1": "123 Main St",
    "Address2": "",
    "City": "Addison",
    "State": "TX",
    "PostalCode": "75001"

    "TransactionDate": "2023-4-5",
    "Subtotal": 100.50,
    "LifetimeValue": 200.75,

    "CreatedAt": "2023-3-39 08:45:17",
    "CustomerSince": "2023-04-05",

    "DigitalTrackingId": "trk-45-3344",
    "ContactId": 4724524324,
    "Hash": "abc123456789",
    "Channel": "Direct Mail",
    "Campaign": "City Pubs 2023",
    "AccountingClass": "NWDALLAS",

    "Unsubscribed": false,

    "LocationId": "loc123",
    "OrganizationId": 5412
}

Entity Deleted

EntityType => 0: Contact, 1: Appointment, 2: Proposal, 3: Invoice, 4: Payment, 5: Deposit, 6: Tip, 7: Task };

{
    "TransactionKind": 2
    "EntityType": 2,
    "EntityId": 123456
}