Overview

With the API documented in this article, semantic contextual data providers can sync semantic data with Equativ. For the integration, the data provider must:  

• sign contractual agreements with Equativ, if applicable
• fill in Equativ’s onboarding form for semantic contextual data providers 
• consult the documentation:
  • this article
  • the article Sync contextual segments (batch file integration) 
• get a 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
• perform tests on the sandbox
• validate the sandbox implementation
• perform tests in production
• activate the integration

Alternative 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 contextual segments – more details here. 

Managing the segment taxonomy

Semantic contextual data providers must sync their segment taxonomy with Equativ, following the instructions in chapter “Managing the segment taxonomy” in the Sync contextual segments (batch file integration) article.

Provider endpoint 

The GET requests Equativ sends to data providers for categorization of URLs/BundleIDs have the following format:

• https://<ProviderEndpoint>?url=<URLToCategorize> for URLs to be categorized
• https://<ProviderEndpoint>?bundle=<BundleToCategorize> for BundleIDs to be categorized

The data provider must supply Equativ with a <ProviderEndpoint> which supports GET requests and is accessible without any authentication.

Request rules

The following rules apply when Equativ calls the data provider’s endpoint:

• Equativ requests the categorization of a URL/BundleID only if the URL/BundleID generated more than 1,000 ad opportunities over the past 24 hours
• Equativ refreshes the categorization every 24 hours, i.e. each URL/BundleID is requested again after 24 hours, if the URL/BundleID has generated more than 1,000 ad opportunities over the past 24 hours
• Depending on the HTTP status code returned by the data provider for a requested URL/BundleID, Equativ behaves as explained in column “Resulting behavior in Equativ’s side” in the table below 
• Equativ caches the association of segments with URLs/BundleIDs for 7 days, i. e. the association remains active for 7 days after the initial synchronization if:
  • the previously categorized URL/BundleID is not requested because it did not reach the threshold of 1,000 ad opportunities over the past 24 hours
  • the data provider does not want the URL/BundleID to be requested again (HTTP 204 response, see table below)

Data provider responses by status

When Equativ requests the categorization of a URL/BundleID, the data provider must adapt the response, depending on the status of the URL/BundleID.   For each status, the table below explains the:

• HTTP status code the data provider must return
• Payload the data provider must return
• Resulting behavior on Equativ’s side