Overview

With the API described in this article, audience data providers can synch segments and profiles with Equativ.

About the audience data batch file integration

As an alternative to the API integration described in this article, data providers can also use Equativ's batch file integration method to sync audience data – more details here).

Integration process

The integration process consists in the following steps:

• sign contractual agreements with Equativ, if applicable
• Fill in Equativ’s onboarding form for audience data providers
• Consult documentation
  • this article
  • the article Sync users 
  • API documentation on Swagger
• Set up the user synchronization — synchronize user identifiers of data providers with Equativ and host a matching table (see Sync users)
• Get sandbox account — your account manager at Equativ will ask you for account parameters and provide you with credentials for developing and testing your implementation of this API on Equativ’s sandbox environment
• Test on sandbox
  • test out the API and construct your data synchronization application using your sandbox credentials
  • perform unit testing and low-volume streaming tests only (the sandbox environment is not provisioned for high, production-level volumes)
  • test token management, pushing and pulling low volumes of segments and profiles to confirm success
  • perform short runs to test uploading long-running updates
  • Do not push more than 1 million unique profiles or exceed profile operation rate limits!
• Validate sandbox — sync with your account manager and technical contacts at Equativ to get support and validate your sandbox testing
• Obtain production account — once validated, request your production credentials from your account manager
• Test in production
  • notify your Equativ contacts about your testing strategy and volumes
  • when authorized by Equativ's infrastructure team, proceed with pushing samples of your production data to production endpoints and check with your Equativ contacts on volumes and results
• Activate the integration
  • notify your Equativ contacts about your sync strategy and volumes
  • when authorized by Equativ's infrastructure team, proceed with moving to full production mode and pushing/activating the segments you plan to use

User synchronization

Audience data providers must synchronize their user identifiers with Equativ and host a matching table which contains the data provider's user Ids and the matching Equativ user Ids. The process is explained in Sync users.

Endpoints

Equativ provides dedicated endpoints by region (to enable data synchronization) and by environment (production vs. sandbox).

* The sandbox runs on a development database. Equativ may erase sandbox data once integration tests are completed.

Authorization

The audience data integration uses the Client Credential Grant flow with the authorization provider FusionAuth (see documentation).

Equativ will provide you with the client_id and client_secret once you are declared as a new data provider in Equativ’s system.

Parameters

Scope

You need to explicitly state the scope you require for your requests. The scope consists of:

• the target-entity
• the permissions.

Target-entity UUIDs:

• for test/sandbox: 232d959c-7786-4d47-8418-48a847c52cfa
• for production: 99d73062-ff3e-4b23-a283-ab98cdd57c22

Permissions (provided as a comma separated string with the following possible values):

• dmp_profile_read - read profiles
• dmp_profile - write/create profiles
• dmp_segment_read - read segments
• dmp_segment - write/create segments

Example request

POST /oauth2/token HTTP/2
Host: login.eqtv.io
content-type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_id=11111111-2222-3333-4444-555555555555&client_secret=abc_123_def&scope=target-entity:232d959c-7786-4d47-8418-48a847c52cfa:dmp_profile_read,dmp_profile,dmp_segment_read,dmp_segment

Example response

200 OK

{
    "access_token": "YOUR_TOKEN",
    "token_type": "bearer",
    "expires_in": 3599
}

The "expires_in": 3599 property in the response indicates the token’s time to live in seconds (3599 seconds = 1 hour). Once a token expires, a new token must be created. To avoid any issues due to expiry, make sure you refresh the token with a refresh interval of less than 1 hour.

Token in authorization header

Include the token in the Authorization header as follows:

GET /segmentproviders/PROVIDER_ID/segments/SEGMENT_ID HTTP/1.1
Host: datasync.eqtv.st
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

Segment provider Id

Your Equativ account manager will provide you with the segmentProviderId, which is a unique ID to be included in each API call. With the authorization token, the segmentProviderId grants access to the segments/profiles of a specific Equativ publisher account (network) or of a specific Maestro curator account. If you need to access the segments/profiles of multiple Equativ publisher accounts (networks) or of multiple Maestro curator accounts, you will get a dedicated, unique segmentProviderId for each of them.

Example Segment API call with segmentProviderId:

GET http://datasync.eqtv.st/segmentproviders/8A254C22-0213-4059-A9BE-05D76DF01C47/segments/{id}

Example Profile API call with segmentProviderId:

GET http://datasync.eqtv.st/segmentproviders/8A254C22-0213-4059-A9BE-05D76DF01C47/profiles/{profileId}

Segment API

A segment represents an audience. An audience is a defined group of end-users. An end-user can be associated to one or multiple segments.

Segment API — fields

Segment API — operations

The Swagger UI provides documentation of all operations as well as a composer to build requests.

Segment API — examples

GET Segment request

/segmentproviders/{segmentProviderId}/segments/{id}

GET Segment response 

 200 OK
    {
    "segmentProviderId": "8A254C22-0213-4059-A9BE-05D76DF01C47",
    "segmentId": "segmentexample",
    "name": "Segment example",
    "ttl": 43200,
    "creationDate": 1542639922787,
    "price": 2.5,
    "description": "This is my segment",
    "active": true
  }

PUT Segment request 

/segmentproviders/{segmentProviderId}/segments/{id}
    {
    "name": "Segment example",
    "ttl": 43200,
    "price": 2.5,
    "description": "This is my segment",
    "active": true
  } 

PUT Segment response

 200 OK
    {
    "segmentProviderId": "11704d0c-48c6-4b53-b552-6e99265159d0",
    "segmentId": "segmentexample",
    "name": "Segment example",
    "ttl": 43200,
    "creationDate": 1639142515220,
    "price": 0.0025,
    "description": "This is my segment",
    "active": true
}

POST Segment request

/segmentproviders/{segmentProviderId}/segments
    {
    "name": "Segment example",
    "ttl": 43200,
    "price": 2.5,
    "description": "This is my segment",
    "active": true
  }

POST Segment response 

 
200 Created
{
    "segmentProviderId": "11704d0c-48c6-4b53-b552-6e99265159d0",
    "segmentId": "segmentexample",
    "name": "Segment example",
    "ttl": 43200,
    "creationDate": 1639142515220,
    "price": 0.0025,
    "description": "This is my segment",
    "active": true
}

Profile API

Profiles are end-users associated with segments.

Profile API — fields

Profile API — operations

The Swagger UI provides documentation of all operations as well as a composer to build requests.

Profile API — examples

PUT Profile request

The PUT operation creates/updates the entire profile; in case of updating, the provided list will replace the previous list: all previously declared segments will be lost and the ttl of all segments will be reset to the values previously set as default for each segment. 

/segmentproviders/{segmentProviderId}/profiles/{profileId}
{
    "segments": [{
        "id": "mysegment1"
    }, {
        "id": "mysegment2"
    }]
}

PUT Profile response

200 OK

POST Profile request

See section “Profile API batch requests — example" below

POST Profile response

See section “Profile API batch requests — example" below

GET Profile request

The GET operation retrieves the segments associated with a given profile.

/segmentproviders/brc95dfd-c5xa-4c48-bz64-b0aqc7esb7c/profiles/profile123

GET Profile response

The GET Profile response contains the segments associated with the given profile, including the expiration, indicating the date/time when the association between the segment and the profile expires.

200 OK 

{
  "id": "profile123",
  "segmentProviderId": "brc95dfd-c5xa-4c48-bz64-b0aqc7esb7c",
  "segments": [
    {
      "expiration": ""2024-01-11T08:21:05Z",
      "id": "12345"
    }
  ]
}

Profile API batch requests

You can batch requests to limit bandwidth usage and accelerate treatment time using the API requests described below.

Profile API batch requests — fields

Profile API batch requests — operations

The Swagger UI provides documentation of all operations as well as a composer to build requests (see: POST /segmentproviders/{segmentProviderId}/profiles)

Profile API batch requests — example

POST Profile request

POST https://datasync.eqtv.st/segmentproviders/8A254C22-0213-4059-A9BE-05D76DF01C47/profiles

[
  {
    "profileId": “123456789”,
    "segmentIdsToSet": [mysegmentid1,mysegmentid2]
  },

{
    "profileId": “987654321”,
    "segmentIdsToAdd": [mysegmentid1,mysegmentid3]
  },

{
    "profileId": “13579753”,
    "segmentIdsToRemove": [mysegmentid1,mysegmentid2]
  },

{
    "profileId": “264846264”,
    "segmentIdsToAdd": [mysegmentid1,mysegmentid2],
    "segmentIdsToRemove": [mysegmentid4]
  },

]

POST Profile response

200 OK

Error response codes

API rate limits

Per segmentProviderId, the following rate limits apply for any read or write API operation (GET, PUT, PATCH, POST).

• Segment API: 1000 requests per day
• Profile API: 1000 requests per second; in the case of batched requests, one batch is counted as one request
• One batch request is limited to 1MB

Specific headers in the response header of each API call indicate the state of the current rate limit. Provided headers:

• X-RateLimit-Reset — the time left until the rate limit reset
• X-RateLimit-Remaining — the remaining calls before reaching the limit
• X-RateLimit-Limit — the maximum rate limit