Data structure

The DealTrack 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

As the DealTrack API changes overtime, Enable will utilise 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, it will be available in a different version of the API.

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

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

Endpoints

Following the version will be 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

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.

curl --request GET "https://api.deal-track.com/v1/deals?filter[startDate]=2017-01-01T00:00:00Z" --header "Authorization: Bearer eyJhbGciOiJIUzI1...."

Multiple types of filtering are supported:

Accessing Related Entities

In the DealTrack 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...."

DealTrack API supports multiple relationships like this:

Response Format

Structure of Entity Response

Every endpoint will return a JSON object, typically containing three top-level members:data, links, and meta. data consists of an array of the JSON objects returned by the endpoint (or a single object, for example if requesting a specific scheme by ID). links and meta are primarily used for information relating to paging when a large number of entities are being returned.

The example below shows the data property of a response from the v1/deals/{id} endpoint, which returns information about a specific deal. For readability, some of the data has been hidden; for example the attributes property contains a large number of details about the deal. The relationships property describes the other entities which are related to this particular data object, and includes links allowing you to query the API for more information about them (see "Accessing related entities" above). Again, some relationship fields have been hidden for readability here.

{
    data: {
            "id": "0DeQ",
            "type": "deals",
            "attributes": {
                "schemeReference": "1",
                "dealType": "Guaranteed rebate",
                "startDate": "2019-08-12T00:00:00",
                "endDate": "2019-08-17T00:00:00",
                ...
            },
            "relationships": {
                "deductions": {
                    "links": {
                       "self": "/v1/deals/0DeQ/relationships/deductions",
                        "related": "/v1/deals/0DeQ/deductions"
                    }
             },
                "items": {
                   "links": {
                      "self": "/v1/deals/0DeQ/relationships/items",
                      "related": "/v1/deals/0DeQ/items"
                   }
              },
              ...
          }
}

Paging of responses

Responses from endpoints which return a number of entities allow for paging in the query, as described in the [JSON API specification](https://jsonapi.org/format/#fetching-pagination). DealTrack API makes use of the "page-based" strategy, allowing queries to specify the size of the pages using the page[size] query parameter, and the page number to return, using page[number]. The following example will query all deals by pages of size 5, and return the 3rd page (results 11 - 15).

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

If not specified, page[size] will default to 10 and page[number] to 1. It is possible to set an arbitrarily large page size, for example if you wish to see all entities of a given type in a single response.

The response will include a data property as described above with an array containing 5 entities. The links property will contain links to query the current page (self), first and last pages, and possibly the previous or next page - if the current page is not already the first or last page, respectively. Finally, the meta property will contain the total number of records. The response for this example can be seen below (for a tenant with 126 total deals).

{
    "data": [
      ...
    ],
    "links": {
          "self": "/v1/deals?page%5Bsize%5D=5&page%5Bnumber%5D=3",
          "first": "/v1/deals?page%5Bsize%5D=5&page%5Bnumber%5D=1",
          "last": "/v1/deals?page%5Bsize%5D=5&page%5Bnumber%5D=26",
          "next": "/v1/deals?page%5Bsize%5D=5&page%5Bnumber%5D=4",
          "prev": "/v1/deals?page%5Bsize%5D=5&page%5Bnumber%5D=2"
    },
    "meta": {
          "total-records": 126
    }
}