Custom Audience API guide

Authentication & Authorization

Sanoma takes the security of its APIs seriously and as such provides tools to ensure your API calls are secure.

Look for this API request in the APIs page (select Sanoma Identity Manager API):
GET /identity/api/login/get-api-access

On-behalf-of Flow Walkthough

As a partner, you may work on behalf of your clients, as such, the On-behalf-of flow allows you to make API calls as if the client themselves were making the API call.

1. Redirect customer to Login page

2. Customer is asked to login with their own Sanoma Ad Manager user.

   • Look for this API request in the APIs page (select Sanoma Identity Manager API):
     POST /identity/api/login/renewToken?refreshToken=<refresh token>

3. If callbackUrl was given, a POST request callback is sent to the address

   • The callback enables the caller to programmatically store/cache the access token and refresh token. The echoed externalUserId can be used to match the token to the correct user.

   • If no callbackUrl was given, the caller can get the access token and refresh token from the query parameters in step 4.

4. If returnUrl was given, the customer is redirected to the address. The same query parameters listed in step 3 are also appended to the request.

5. To renew expired access token, send POST request to /identity/api/login/renewToken with query parameter:

   refreshToken = The refresh token received in step 3/4.

Ad Manager Custom Audiences API

Prior to the Ad Manager Custom Audiences API, the advertiser would need to send a message to Sanoma Services to add their audiences to the Data Marketplace. Now advertisers may upload their own list of contacts (Audience) in order to run advertising campaigns.

The Ad Manager Custom Audiences API Product comprises of three separate APIs, you need to work with all three APIs in order to complete the use case:

Identity Manager: In order to use this API you need to ensure that you have a valid access token. Please use the "On-behalf-of" flow in order to obtain a valid token.

Hashing Service: Before storing sensitive information, such as an email address or a phone number in Sanoma, it will first be hashed with a SHA-256 hashing algorithm. This is in accordance with the GDPR directive.

Ad Manager Custom Audiences API

Prerequisites:
In order to use the Ad Manager Custom Audiences API, the customer is required to have completed several steps beforehand. Failure to complete these steps will result in an error on the API Call.

The customer must:

• Be registered with Sanoma Media i.e. Have a valid AdManager Account and a designated contact person.

• Subscribe to an Ad Manager Custom Audiences Package.

• Have accepted the Sanoma Data Agreement.

More information may be found on the Sanoma Media site.

Ad Manager Custom Audiences API

Sanoma Ad Manager Audiences are comprised of the following objects:

Segments
A segment is a client specific collection based upon a set of characteristics that are required for this campaign e.g. Relationship status (Single, Couple, Family with kids), Age (15-17, 18-29, 30-34, 35-49, 50+), etc.

Campaigns
A campaign is a container for the marketing activities and runs for a set amount of time.

Audiences
An audience is a collection of customers to whom you wish to target your campaign. There are different types of audiences:

• CRM - These are audiences that come from an existing Customer Relationship Management system.

• Lookalike - Audiences that are similar to an existing audience.

The client with the advertiser account will work with Sanoma to define Segments and Campaigns. After the custom audience has been created with the API, Sanoma will attach the audience to the right campaigns.