Audience data — API integration — v2

About the audience data API integration

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 Audience data — user synchronization
  • API documentation on Swagger  
• Set up the user synchronization — synchronize user identifiers of data providers with Equativ and host a matching table (see Audience data — user synchronization)
• 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 Audience data — user synchronization.

Endpoints

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

Region	API	Environment	Endpoint
EU	Audience data	Production	https://datasync-eu.eqtv.io/v2
APAC	Audience data	Production	https://datasync-apac.eqtv.io/v2
Americas	Audience data	Production	https://datasync-us.eqtv.io/v2
All	Audience data	Sandbox*	https://datasync.eqtv.st/v2
All	OAuth	Production	https://login.eqtv.io
All	OAuth	Sandbox*	https://login.eqtv.io (sandbox authentication endpoint identical to production; only credentials (client_id, client_secret) and requested API target (target-entity) are different)

* 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

Parameter	Description
client_id	the authorization ID you receive from Equativ; it is the equivalent of a user name; its value differs depending on the environment (sandbox vs. production)
client_secret	the client secret you receive from Equativ; it is the equivalent of a password; its value differs depending on the environment (sandbox vs. production)
grant_type	needs to be provided as is, i. e. client_credentials; it tells Equativ’s authentication provider (FusionAuth) which method of authentication to use

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

 

Example response

Token in authorization header

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 Equativ Buyer Connect curator account. If you need to access the segments/profiles of multiple Equativ publisher accounts (networks) or of multiple Equativ Buyer Connect curator accounts, you will get a dedicated, unique segmentProviderId for each of them.

Segment API

Segment API — fields

Field____________	Type____	Description
segmentProviderId	string	the audience data provider (partner) that synchronizes segments with Equativ publishers; more details in section “Segment provider Id” above
segmentId	string max 100 characters	the segment Id, defined by the data provider
name	string max 250 characters	the segment name (label); campaign managers will see this name in Equativ's platform; UTF-8 encoded; max. 100 characters
ttl	integer	the default time to live of a profile/segment relation (in minutes); value must be between 1 and 2147483647; any values outside of this range will result in the transaction being rejected; default: 43200
creationDate	integer	the creation date of the segment
price	number	the CPM price in the currency that was agreed upon during the setup of the audience data provider; this price will be invoiced to the data provider for transactions using the segment
description	string max 1000 characters	a human readable description of the segment that is displayed to end users in Equativ's platform
active	boolean	determines if the segment is active; used to disable a segment and thus remove it from targeting.
selectable	boolean	indicates if the segment is targetable or just declared as a parent segment to build the hierarchy 0: the segment is not targetable - it is only declared to build the hierarchy 1: the segment is targetable

Segment API — operations

Segment API — examples

Profile API

Profile API — fields

Fields____________	Type____	Description
segmentProviderId	string	the audience data provider (partner) that synchronizes segments with Equativ publishers; more details in section “Segment provider Id” above
id	string	the identifier of the user; ids are case sensitive and UTF-8 encoded; Equativ supports any id type, e. g.: Equativ's cookie ID (to initiate a cookie sync with Equativ, as explained in Audience data — user synchronization) mobile advertising ID (MAID) publisher provided ID alternative ID (extended ID); per folder, one alternative Id of one vendor can be set; if you need alternative IDs of multiple vendors, get back to Equativ’s partner integration team to get a dedicated folder for each of them IP address; frequently used to target Connected TVs or to match users with households; IP address formats must follow the standards; overlapping or truncated IPs will be ignored and not processed (e.g. IPv4 translated to IPv6 as ::ffff:202.124.87.3)
segments		the list of segments linked to the profile
segments.<id>	string	the segment Id linked to the profile; the expected segment Ids are the ones created by the data provider through the segment API
segments.<id>.expiration	string	the date when the link between segment and profile will expire

Profile API — operations

Profile API — examples

Profile API batch requests

Profile API batch requests — fields

Field________________	Description
profileId	the profile Id; profile Ids are case sensitive and UTF8 encoded
segmentIdsToAdd	the list of segments to add to the profile Id; Equativ will create the profile Id automatically if it is not yet known to Equativ
segmentIdsToSet	the list of segments to define for the profile Id (full refresh); Equativ will create the profile Id automatically if it is not yet known to Equativ
segmentIdsToRemove	the list of segments to remove from the profile Id. When removeAllSegments has a value TRUE in the request, Equativ will remove all segmentIds for the associated profile Id

Profile API batch requests — operations

Profile API batch requests — example

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

HTTP status code	Description
400 Bad Request	Returned if the requested payload was invalid.
401 Unauthorized	Returned for requests without any token or with an invalid token.
403 Forbidden	Returned if a token does not have the requested scope to execute the request.
404 Not Found	Returned in case of malformed URL, invalid format id or unknown resource.
429 Too Many Requests	Returned in case of the queue on Equativ's server being full; uploads must be slowed down or paced to mitigate the issue
500 Internal Server Error	Returned in the case of unexpected errors which might have occurred in the system.

API rate limits

• 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

• 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