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. For more information, see Sync segments and profiles (batch file).

Integration process

Here are the integration steps:

1. Sign contract: Sign contractual agreements with Equativ, if applicable.
2. Fill in form: Fill in Equativ’s onboarding form for audience data providers.
3. Consult documentation: this article, Sync users, API documentation (Swagger).
4. Set up user synchronization: Synchronize user identifiers of data providers with Equativ and host a matching table. For more information, see Sync user.
5. 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
6. Test on sandbox:
   1. Test the API and construct your data synchronization application using your sandbox credentials.
   2. Perform unit testing and low-volume streaming tests only. the sandbox environment is not provisioned for high, production-level volumes.
   3. Test token management, pushing and pulling low volumes of segments and profiles to confirm success.
   4. Perform short runs to test uploading long-running updates.
   5. Don't push more than 1 million unique profiles or exceed profile operation rate limits.
7. Validate sandbox: Sync with your account manager and technical contacts at Equativ to get support and validate your sandbox testing.
8. Obtain production account: Once validated, request your production credentials from your account manager.
9. 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.
10. 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. For more information, see Sync users.

Endpoints

Equativ provides dedicated endpoints by region (to enable data synchronization) and by environment (production/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 and 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):

• Read profiles: dmp_profile_read 
• Write/create profiles: dmp_profile 
• Read segments: dmp_segment_read
• Write/create segments: dmp_segment 

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 API documentation provides documentation of all operations as well as a composer to build requests.

Meta segments and relative price

The following behaviors apply when working with meta segments and relative price:

• Update without the relativePrice field: If you leave relativePrice out of a PUT request, the stored value stays as it is. On a POST request, it defaults to no relative price.
• Invalid values: A relativePrice outside the accepted range, or a metaSegmentIds entry with a forbidden character, returns 400 Bad Request. Nothing is saved.
• Mapping not applied: Your account must be enabled for the meta taxonomy by Equativ. If it is not enabled, or if a meta segment ID is unknown, the request still succeeds but the mapping is not applied.

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,
  "relativePrice": 0.15,
  "description": "This is my segment",
  "active": true,
  "metaSegmentIds": ["eumm_automotive"]
}

PUT Segment request 

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

PUT Segment response

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

PUT request that removes all meta segment mappings

{ "removeAllMetaSegments": true }

POST Segment request

/segmentproviders/{segmentProviderId}/segments
{
  "name": "Segment example",
  "ttl": 43200,
  "price": 2.5,
  "relativePrice": 0.15,
  "description": "This is my segment",
  "active": true,
  "metaSegmentIds": ["eumm_automotive"]
}

POST Segment response

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

Profile API

Profiles are end-users associated with segments.

Profile API fields

Encrypted alternative IDs (eids)

Equativ can process encrypted alternative IDs (eids) from the providers Utiq and ID5 without prior decryption. Equativ manages the decryption process internally using the respective provider's APIs.

To enable Equativ to perform this decryption, you must include the eidProvider field and set it to utiq.com (for encrypted Utiq AdTech IDs) or id5-sync.com (for ID5 IDs).

The following is a POST profile request using an encrypted Utiq profileId. Note the inclusion of the required eidProvider field.

[
 {
   "profileId": "profile_ID_encrypted_123",
   "eidProvider": "utiq.com",
   "segmentIdsToAdd": [
     "f1dgrd4e-ehdz-fkkd-383k-1jshwzduflau"
   ],
   "segmentIdsToRemove": [
     "dgeh8d4e-81ed-4cc7-aae6-80300b18e22d"
   ],
   "segmentIdsToSet": [
     "fsjexd4e-8sad-9ec8-kklw-827dhhg8e2zw"
   ]
 }
]

Profile API operations

The Swagger API documentation 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}

{
  "profileIdSource": "string",
  "segments": [
    {
      "id": "segmentId1"
    },
    {
      "id": "segmentId2"
    }
  ]
}

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 API documentation 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": "profileIdString",
    "profileIdSource": "profileIdSourceAsString",
    "segmentIdsToSet": [
      "mysegmentid1",
      "mysegmentid2"
    ]
  },
  {
    "profileId": "profileIdString",
    "profileIdSource": "profileIdSourceAsString",
    "segmentIdsToAdd": [
      "mysegmentid1",
      "mysegmentid2"
    ]
  },
  {
    "profileId": "profileIdString",
    "profileIdSource": "profileIdSourceAsString",
    "segmentIdsToRemove": [
      "mysegmentid6",
      "mysegmentid7"
    ]
  },
  {
    "profileId": "profileIdString",
    "profileIdSource": "profileIdSourceAsString",
    "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:

• Time left until the rate limit reset: X-RateLimit-Reset 
• Remaining calls before reaching the limit: X-RateLimit-Remaining 
• The maximum rate limit: X-RateLimit-Limit 

Payload limit

The maximum daily payload (data) a segment provider can push is 30 GB.

To prevent large bursts of usage, a pacing system distributes the daily limit evenly across 288 pacing windows (duration of one pacing window: 5 minutes). The pacing window limit equals 104 MB (30 GB divided by 288).

A minimum of 1 MB per pacing window is guaranteed to prevent zero limits.