Delta - Consumed & Mapped

Purpose

After querying the Delta List and then looping over each Delta record, requesting that changed object and then updating it on your internal system --> you can then POST to this endpoint to:

• SCENARIO 1: If the object exists in your internal system --> then after updating the object in your database you can set the "consumed at" timestamp on that changed object on Incentify to serve as a "feedback loop" into the Incenitfy to confirm that the data you injested into your internal system is the latest data
• SCENARIO 2: If the object originated from the Incentify platform and it is NOT yet in your database --> then after creating the object in your database in addition to setting the "consumed at" timestap you can also include the new internal ID for that object for Incentify to save for future mappings/requests

Request

Endpoint

POST /delta/consumed

Authentication

Include your API Key within the x-api-key header as described here.

Request Body Parameters

NOTE: The resource_type, resource_internal_id, and account_internal_id in the request is always required. You can additionally supply resource_id in the Request Body when you ingest resources that originate from Incentify to get your internal ID back into the Incentify system.

The following table lists the parameters supported in the JSON POST payload.

Required Request Parameters

• * are required.
• Marked with NO asterisk are optional parameters. If you do not include them in an update request then the current value will be preserved.

Parameter	Type	Definition
resource_type *	ENUM("activity", "comment", "document")	The type of the Resource which has changed.
resource_id	integer	The ID of the Resource on Incentify. You only need to include this in the request in SCENARIO 2 (above)when you are wanting to update the mapping of the Incentify object to the Internal ID on your system.
resource_internal_id *	string	The ID of the Resource on your internal system.
timestamp *	stirng	Set this to the current value of the "timestamp" from the Delta resource you are posting, which you received from the Delta List GET. Important: This is necessary (rather than submitting the "now" timestamp) to allow us to inform you when additional changes have occured on the resource since you consumed it (for example, the resource was updated during the brief time your script is running) then it will set the "consumed_at" timestamp to the timestamp you submitted. This leaves the resource in a "pending change" status so that it continues to be returned on the Delta List GET. From here you have two paths to sync the Delta: (1) you wait until your next scheduled scan of the Delta List GET or (2) you process this in "realtime" --> if the response is a 200 code with a non empty body instead of a status code 204 with an empty response body, then you could refetch the object, update your data and then re-submit this post.
internal_account_id *	string	The ID of the Account on your internal system.

Request Body Example: For SCENARIO 1 (above)

This sets the "Consumed At" timestamp, but does not update the Internal Object ID mapping on the object in Incentify.

{
    "resource_type": "activty",
    "resource_internal_id": "a2134453",
    "internal_account_id": "a2354242",
    "timestamp": "2022-05-03T17:13:44.123Z"
}

Request Body Example: For SCENARIO 2 (above)

This both sets the "Consumed At" timestamp AND updates the Internal Object ID mapping on the object in Incentify.

{
    "resource_type": "activty",
    "resource_id": "123454",
    "resource_internal_id": "a2134453",
    "internal_account_id": "a2354242",
    "timestamp": "2022-05-03T17:13:44.123Z"
}

Successful Response

If successful, this method returns an http code of 204 and an empty response body with the following structure:

Response Body

{
}

If successful, but the underlying resource has an updated_at timestamp > the provided consumed timestamp, this method returns an http code of 200 and a response body with the following structure:

Response Body

{
    "resource_type": ENUM("activity", "comment", "document"),
    "resource_id": integer,
    "resource_internal_id": string,
    "action": ENUM("create", "update", "delete"),
    "timestamp": string (RFC 3339 Nano Format (to micro precision) - 2022-05-03T17:13:44.123Z),
    "consumed_at": string (RFC 3339 Nano Format (to micro precision) - 2022-05-03T17:13:44.123Z)
}

You can choose if you'd rather re-consume this resoruce in place in this scenario, or let the additional changes be picked up by the next tick on the delta list endpoint.

Error Response

If the request has invalid fields/values, this method returns an http code of 400 and response body with the following structure:

Error Response Body

{
    "code":400,
    "success":false,
    "data": {},
    "errors": [
        "text describing error here"
    ]
}

Properties

The following table defines the properties that appear in this resource:

Key	Type	Definition
code	integer	HTTP Status Code (ie; 200, 403, etc).
success	boolean	Either true (success) or false (fail).
data.consumed_at	string	The timestamp for when this change was consumed by your internal system.
errors	object	If the request fails, this will contain information about the error.