Data structure

The Enable API has been designed to be JSON:API compliant. The data structure and request format follow the patterns described in the specification.

Request Format

Requests to the API follow a standardised structure.

Versioning

Enable utilizes versioning to ensure that client applications which rely on the API are not impacted by breaking changes to the API or its structure. If a breaking change is introduced, you can specify which version of the API to use.

Different versions of the API are accessible by modifying the version identifier (v1, v2, etc.) which can be found at the start of Enable API endpoint URLs. The following example shows how to send a request to view deals using the first version (v1) of the API.

curl --request GET "https://api.deal-track.com/v1/deals" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

Endpoints

Following the version is the endpoint’s name itself. Currently, Enable supports the following top level endpoints:

v1/trading-partners v1/schemes v1/deals v1/items v1/earnings v1/turnover v1/activity v1/attachments v1/users v1/collaborators v1/collection-items v1/collections v1/granular-earnings

Filtering by Identifier

To select just a single entity from an endpoint you can add /{entity-id} to the end of the request URL. The following example shows how to send a request to view a single deal with the ID of “Hg7f”, if one exists.

curl --request GET "https://api.deal-track.com/v1/deals/Hg7f" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

Filtering by Entity Values

It is possible to query the API for entities with specific values. The structure of a filter request is: {entity-name}?filter[{attribute-name}]={target-value}. The following example shows how to send a request to filter deals by their start date.

Conjunction of multiple filters is supported. In the case of two filters, for example, syntactically this uses the ampersand character (&)and takes the form shown below.

More than two filters are handled similarly.

Certain characters in {target-value} need to be URL encoded, such as spaces. For example, to search for deals whose descriptions contain the words "bulk buy", we would use the following filter.

curl --request GET "https://api.deal-track.com/v1/deals?filter[description]=like:bulk%20buy" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

Multiple types of filtering are supported:

Filter Structure	Description
`?filter[attribute]=eq:value`	Return elements which equal a value
`?filter[attribute]=ne:value`	Return elements which are not equal to a value
`?filter[attribute]=gt:value`	Return elements which are greater than a value
`?filter[attribute]=lt:value`	Return elements which are less than a value
`?filter[attribute]=in:value`	Return elements which are present in a given comma-separated list of values
`?filter[attribute]=like:value`	Return elements which contain the given string
`?filter[attribute]=isNull:value`	Return elements which are null if value is `true` , or not null if value is `false`

The table below illustrates the available filters for each data type. Some entity types do not currently support all available filters. Where this is the case, a suitable error will be returned.

Data Type	Filter
	eq	ne	gt	lt	in	like	isnull
Boolean	✓	✓	X	X	X	X	✓
Date	✓	✓	✓	✓	X	X	✓
Decimal	✓	✓	✓	✓	X	X	✓
Integer	✓	✓	✓	✓	✓	X	✓
Long	✓	✓	✓	✓	✓	X	✓
String	✓	✓	X	X	X	✓	✓
Enum	✓	✓	X	X	X	X	✓

Sorting by Entity Values

Enable API also supports sorting by entity values/attributes. In order to sort the results in an ascending order this structure is used:

{entity-name}?sort={attribute-name}

To sort the response in a descending order a "-" is appended onto the start of {attribute-name} like this:

{entity-name}?sort=-{attribute-name}

The following example shows how to send a request to sort deals so that the most recent start dates appear first.

curl --request GET "https://api.deal-track.com/v1/deals?sort=-startDate" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

Combining parameters

Parameters can be combined using Enable API. This is done by inserting the & symbol between parameters. The following example uses this to request a page containing the 5 deals with the earliest "startDate", but only deals where "contraEarnings" is set to false.

curl --request GET "https://api.deal-track.com/v1/deals?sort=startDate&page[size]=5&filter[contraEarnings]=eq:false" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

Pagination

Enable API supports pagination. In order to request a specific page number, using the default page size of 10, the following syntax is used:

{entity-name}?page[number]={page-number}

The page size can also be specified using {entity-name}?page[size]={page-size}, and both can be used simultaneously with this syntax:

{entity-name}?page[size]={page-size}&page[number]={page-number}

The following example shows how to send a request to for deals where the response shows the second page, and has a page size of 5.

curl --request GET "https://api.deal-track.com/v1/deals?page[size]=5&page[number]=2" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

Accessing Related Entities

In the Enable API it is possible to retrieve entity data which is related to a top level Entity. The structure of this request is:

{entity-name}/{entity-id}/{related-entity-name}

The following example shows how to send a request to view all schemes that belong to a trading partner with the ID of “pL9f”.

curl --request GET "https://api.deal-track.com/v1/trading-partners/pL9f/schemes" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

Enable API supports multiple relationships like this:

Relationship	Description
`v1/trading-partners/{id}/schemes`	Return all the Schemes which belong to a Trading Partner
`v1/trading-partners/{id}/items`	Return all the Dimension Items which belong to a Trading Partner
`v1/schemes/{id}/deals`	Return all the Deals which belong to a Scheme
`v1/schemes/{id}/items`	Return all the Dimension Items which belong to a Scheme
`v1/deals/{id}/items`	Return all the Dimension Items which belong to a Deal
`v1/activity/{id}/attachments`	Return all the Attachments which belong to a Activity

Sparse Fieldsets

Enable API supports sparse fieldsets, this means that a query can be written so that the response returns only specified fields. The structure required is:

{entity-name}?fields[{entity-name}]={attribute-name}

The following example will return a list of items, but only the specified attributes ("name" and "reference") will be included in the response.

curl --request GET "https://api.deal-track.com/v1/items?fields[items]=name,reference" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

Compound Documents

Some endpoints currently support compound documents, allowing data belonging to related entities to be provided along with the usual response. The structure of this request is:

{entity-name}?include={related-entity-name}

The following example shows how to send a request to get the deal with the ID "2Bk3" along with its related items.

curl --request GET "https://api.deal-track.com/v1/deals/2Bk3?include=items" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

If an endpoint does not support the ?include parameter, the Enable API will respond with 400 Bad Request.

Asynchronous Processing

Certain requests for data can take a a long time to complete, so returning that data in a single request is infeasible. Instead, Enable API uses an asynchronous processing technique. With this, an initial request is sent to trigger processing in the background, and then polling requests can be made until the processing is complete. At this point the results of the request are returned.

Requests to endpoints utilising asynchronous processing are initialised in the same way as a regular request, for example:

curl --request GET "https://api.deal-track.com/v1/granular-earnings/aF3v" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

This will queue up the request to be processed, and will immediately return a response containing the URL for the polling endpoint in the Content-Location header. Requests can then be made to the polling endpoint as follows:

curl --request GET "https://api.deal-track.com/v1/granular-earnings/queue-jobs/p0fS" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

Whilst the initial request is still being processed, the polling endpoint will return a queue-jobs entity, which will contain a status attribute, detailing the progress of the request. Once the processing is complete, the polling endpoint will respond with 303 See Other, and will provide the location of the results in the Location header.

curl --request GET "https://api.deal-track.com/v1/granular-earnings/results/p0fS" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

Response Format

Structure of Entity Response

An endpoint will return up to 10 entities from Enable in the following structure:


{
    data: [
        {
            attributes: {
                property1: "value",
                property2: "value"
            },
            relationships: {
                related-entity: {
                    links: {
                        self: "/v1/entity-type/fdb8/relationships/related-entity-type",
                        related: "/v1/entity-type/fdb8/related-entity-type"
                    }
                }
            },
            type: "entity-type",
            id: "fdb8"
        },
        {
            attributes: {
                property1: "value",
                property2: "value"
            },
            relationships: {
                related-entity: {
                    links: {
                        self: "/v1/entity-type/k9Ls/relationships/related-entity-type",
                        related: "/v1/entity-type/k9Ls/related-entity-type"
                    }
                }
            },
            type: "entity-type",
            id: "k9Ls"
        }
    ],
    meta: {
        total-records: 2
    }
}

In the structure above, the entity-type would be the name of the entity e.g. “deals”. The values of that entity are found within the attributes section. Links to related entities are stored within the relationship sections.

Thank you! Your submission has been received!

Oops! Something went wrong while submitting the form.

Data structure

Request Format

Versioning

Endpoints

Filtering by Identifier

Filtering by Entity Values

Sorting by Entity Values

Combining parameters

Pagination

Accessing Related Entities

Sparse Fieldsets

Compound Documents

Asynchronous Processing

Response Format

Structure of Entity Response

Still have questions?
Raise a ticket or contact our support team.

Customer Rebates

Related articles

Articles in this section

Data structure

Request Format

Versioning

Endpoints

Filtering by Identifier

Filtering by Entity Values

Sorting by Entity Values

Combining parameters

Pagination

Accessing Related Entities

Sparse Fieldsets

Compound Documents

Asynchronous Processing

Response Format

Structure of Entity Response

Still have questions?Raise a ticket or contact our support team.

Still have questions?
Raise a ticket or contact our support team.