Profile API

This document will outline the integration steps with audiens Profile API.


Sync your user with Audiens

The user must already be mapped in the Audiens system. This is a requirement before proceeding with the actual synchronization.

User mapping steps:

  1. Partner's client: The user visit a page where the Audiens pixel is present and a call is made to the endpoint.
  2. Audiens user mapping: Audiens receive the call identify the user.
  3. Audiens reply: Audiens will conclude the redirect flow with an empty 1x1 pixel.

Add the Audiens pixel

To map the user with Audiens, the partner will call the endpoint and initiate the sync procedure.

The URL must respect the following format:

http(s)://data.audiens.com/v1/cookie/match/?audiens_partner={an_id}&audiens_partner_uuid={an_id}

Mandatory parameters:

audiens_partner:
The id of the Partner provided by Audiens during the integration kick-off.
audiens_partner_uuid
The user identification parameter used by the Partner, it will be required to store the matching table on Audiens side.

Examples:

https://data.audiens.com/v1/cookie/match/?audiens_partner=7&audiens_partner_uuid=234
https://data.audiens.com/v1/cookie/match/?audiens_partner=44&audiens_partner_uuid=4578bb95aa2a4

The simplest way to implement the Audiens Mapping Service to an html page is to add an img tag with the correct formatted URL

<img src='//data.audiens.com/v1/cookie/match/?audiens_partner=7&audiens_partner_uuid=23' />

Audiens identify the user

Audiens will match the audiens_partner_uuid with the internal profiled user.

From this point forward the audiens_partner_uuid can be used to send user data.


Get the user profile:

Endpoint:

User Profile endpoints begin with https://api.audiens.com/v1/. Any future updates that introduce breaking changes will be published with a new version number in the URL.

Authentication

To access the API, you will need to create a dedicated API user, with a valid email address, under your audiens Organization. Contact your Account Manager or email support@audiens.com to arrange API access for that user.

Once your API user is set up, you will receive your clientId and client secret keys. Using them you can authenticate by issuing a POST request to https://api.audiens.com/auth.

Sample Raw HTTP Request:

POST /auth HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials

Using your Bearer Token

A successful POST request to /auth will result in a JSON response as follows:

{
    "token_type": "bearer",
    "access_token": "YWIxMjdi883GHBBDnjsdKAJQxNjdjYUUJABbg6hdI.8V6HhxW-"
}

Subsequent requests to the API can now be authorized by setting the Authorization header as follows:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczov

Batch enrichment:

Data Location

The data will exported weekly into your dedicated S3 bucket, the scaffolding will look like:

s3://audiens.export/{partner_id}/{year}/{month}/{day}/{filename}.json.gz

The partner id will be provided to you during th early stage of the integration and is usually a 3 or 4 digit number example: 987

The export will always provide you wil a full userbase dump even if there are no new information concerning the user.

We also support a daily export for frequently updated user profiles

AWS CLI examples

Check all the files in you export folder:

$ aws s3 ls --recursive s3://audiens.export/{partner_id}/

Download a single file:

$ aws s3 cp s3://audiens.export/{partner_id}/2019/03/01/export.json.gz .

User schema:

Following a json schema of the user, draft 06:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Audiens Profile API Schema",
  "required": [
    "identifiers",
    "audiences"
  ],
  "properties": {
    "identifiers": {
      "$id": "#/properties/identifiers",
      "type": "object",
      "title": "The Identifiers Schema",
      "items": {
        "$id": "#/properties/identifiers/items",
        "type": "object",
        "properties": {
          "email_sha256": {
            "$id": "#/properties/identifiers/items/properties/email_sha256",
            "type": "array",
            "items": {
              "$id": "#/properties/identifiers/items/properties/email_sha256/items",
              "type": "string",
              "default": "-",
              "examples": [
                "a_sha26_string"
              ],
              "pattern": "^(.*)$"
            }
          },
          "email_md5": {
            "$id": "#/properties/identifiers/items/properties/email_md5",
            "type": "array",
            "items": {
              "$id": "#/properties/identifiers/items/properties/email_md5/items",
              "type": "string",
              "default": "-",
              "examples": [
                "a_md5_string"
              ],
              "pattern": "^(.*)$"
            }
          },
          "mobile_phone_sha256": {
            "$id": "#/properties/identifiers/items/properties/mobile_phone_sha256",
            "type": "array",
            "items": {
              "$id": "#/properties/identifiers/items/properties/mobile_phone_sha256/items",
              "type": "string",
              "default": "-",
              "examples": [
                "a_sha26_string"
              ],
              "pattern": "^(.*)$"
            }
          },
          "mobile_device": {
            "$id": "#/properties/identifiers/items/properties/mobile_device",
            "type": "array",
            "items": {
              "$id": "#/properties/identifiers/items/properties/mobile_device/items",
              "type": "string",
              "default": "-",
              "examples": [
                "a_sha26_string"
              ],
              "pattern": "^(.*)$"
            },
            "first_party_cookies": {
              "$id": "#/properties/identifiers/items/properties/first_party_cookies",
              "type": "array",
              "items": {
                "$id": "#/properties/identifiers/items/properties/first_party_cookies/items",
                "type": "string",
                "default": "-",
                "examples": [
                  "a_sha26_string"
                ],
                "pattern": "^(.*)$"
              }
            }
          }
        }
      }
    },
    "audiences": {
      "$id": "#/properties/audiences",
      "type": "array",
      "title": "The Audiences Schema",
      "items": {
        "$id": "#/properties/audiences/items",
        "type": "object",
        "title": "The Items Schema",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "$id": "#/properties/audiences/items/properties/id",
            "type": "integer",
            "title": "The Id Schema",
            "default": "",
            "examples": [
              123
            ],
            "pattern": "^(.*)$"
          },
          "name": {
            "$id": "#/properties/audiences/items/properties/name",
            "type": "string",
            "title": "The Name Schema",
            "default": "",
            "examples": [
              "segment name"
            ],
            "pattern": "^(.*)$"
          }
        }
      }
    }
  }
}