DealTrack Help

Articles in this section

Data structure

Avatar
David
  • Updated
Follow

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:

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

 

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:

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 Dimension Items which belong to a deal
v1/activity/{id}/attachments Return all the Attachments which belong to a Activity

Response Format

Structure of Entity Response

An endpoint will return up to 10 entities from DealTrack 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.

Related articles

Comments

0 comments

Please sign in to leave a comment.