Understanding Responses

All successful responses are in JSON and contain a complete data set for records that were added, updated, or deleted. Responses do not indicate which fields within a record have changed; instead we provide the record's full data set. For example, if a client had one of their three phone numbers deleted from their profile, then the client's full profile data (including the two remaining phone numbers) would appear in the response. So when importing deltas into your system, make sure you perform a REPLACE of the records, not an UPDATE.

Also note if an entity's field does not contain any data (a NULL Address, for example), then it will not appear in the response.

Interpreting responses

The fields in the JSON response, the fields in the Full Starter Export files, and the fields in the corresponding reference tables all follow the same column order. However, in the DDS response the data from all tables is combined.

Responses are not designed to be read line-by-line. However, you can determine the definition for each field by reviewing the corresponding reference table (in this case, the Client_YYYYMMDD.csv table in Client Fields Reference Tables topic). Enum values can be found here.

There are several clues in the responses that can give you an idea about which records are new, which were deleted, and which were updated.

• Each response will have the lastChangeDateIncludedInPage field, which indicates the date and time of the most recent change captured on that page. This field is useful; if you are making several calls for deltas in the same day, you can use this value as your StartDate in the next call to prevent the same records that appeared in an earlier call from being returned.
• New records will have the same DateCreated and DateUpdated date.
• Updated records will have a DateUpdated date that is:
  • Within the StartDate parameter set in the call
  • Different from its DateCreated date
• Deleted client records will have ObjectStateEnum: 2028.
• Deleted employee records will have ObjectStateEnum: 2028 and a TerminatedDate that is within the StartDate parameter set in the call.
• Deleted appointments will have AppointFinalStateEnum: 2052.
• A full list of all Enum values can be found here.

Null data sets in responses

Regarding missing data points or null data sets:

• If there is no information to return for a certain data point (for example, if a client does not have a Middle Name), that data point will not appear in the response.
• If there were no changes to any of the records in an entity since your entered StartDate, you will receive a JSON response with an empty data array (shown below).

{
    "request": {
        "entityType": "Client",
        "startDate": "2021-05-04T00:00:00.0000000+00:00",
        "pageNumber": 0,
        "itemsPerPage": 50,
        "tenantId": 11, 
        "locationId": 9
    },
     "pageNumber": 0,
     "itemsPerPage": 50,
     "tenantId": 11,
     "locationId": 9,
     "referenceId": "209e6ed1-7aea-48dd-b190-35cd81ec290d",
     "data": []
}