DMP Integration API

This article is for developers/technical account managers on the DMP side. It does not describe workflows in Smart AdServer's User interface.

Smart AdServer's DMP Integration API can be used to integrate (push, update etc.) segments and profiles from DMPs to Smart AdServer. Smart AdServer's publisher customers can then target to these profiles using keyword targeting (for more about keyword targeting, read here).

About DMP integration

About DMP integration

DMP integration with Smart AdServer consists of the following steps:

  • The publisher (Smart AdServer's customer) signs up with the DMP
  • The publisher implements the DMP's script (tag) on the websites
  • The DMP collects data through the integrated script: environment data (cookieID, timestamp, user agent etc.) and behavioral data (page name, site version, gender etc.)
  • In the DMP's UI, the publisher defines segments using logical operators (AND, OR, EXCLUDE); each segment is saved with a label and a segment ID
  • Segments are pushed to Smart AdServer (using the DMP Integration API described in this article)
  • The segments are displayed in Smart AdServer's UI as keywords
  • The publisher can target insertions to the profiles in the segments using keyword targeting

Endpoints

Europe endpoint:

https://dmp.smartadserverapis.com/

North America endpoint:

https://dmp-us.smartadserverapis.com/

Europe sandbox:

https://dmpsandbox.smartadserverapis.com/

Note 1: The sandbox runs on a development database. Smart AdServer may erase these data once integration tests are completed.
Note 2: You must use https. The API is not available through http.

Authorization

DMP integration is based on OAuth 2.0 RFC. It uses the Client Credential Grant flow as specified in OAuth 2.0 RFC.

You need to be declared in Smart AdServer's system as a new DMP in order to

  • be allowed to retrieve a valid authorization token
  • receive the ClientId
  • receive the ClientSecret

Segment provider ID

Once the authorization token has been granted, the new DMP needs to be authorized to access the publisher's network (account) at Smart AdServer with the segmentProviderId.

This segmentProviderId is a unique ID which must be passed in the URL for all API calls.

Example (with segmentProviderId  8A254C22-0213-4059-A9BE-05D76DF01C47):

GET http://dmpsandbox.smartadserverapis.com/segmentproviders/8A254C22-0213-4059-A9BE-05D76DF01C47/profiles/<end-user-id>

Segments

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.

A segment consists of:

  • a label
  • an identifier
  • a TTL (time to live)

Data

Property Description
id the segment ID
label the segment label; will be visible in Smart AdServer's interface (http://manage.smartadserver.com/) to target insertions
segmentProviderId Represents the DMP (partner), which synchronizes segments with Smart AdServer networks (publishers). For more details see above (Segment provider ID)
ttl Defines the default time to live of a profile/segment relation (in minutes)

Commands

Action Verb Request Response
Create POST segmentproviders/{id}/segments

{
    "name": "my segment",
    "ttl": 1440
}
201 Created
Location: /segments/10
Retrieve GET segmentproviders/{id}/segments/{id} 200 OK

{
    "name": "segment-test",
    "segmentId": 123456,
    "segmentProviderId": "1234-abcd-ff99aa",
    "ttl": 1440
}

Profiles

Profiles are end-users associated with segments.

Data

Property Description
id the profile id
segments the list of segments linked to the profile
segments.<id> the segment id linked to the profile
segments.<id>.expiration date when link between segment and profile will expire

Commands

The profile resources support the following creational methods:

  • PUT to replace the entire profile
  • PATCH to do a partial update

Note 1: To use the the PATCH method, the profile does not need to exist.
Note 2: Removing a non-existing segment to the profile has no effect.

Action Verb Request Response
Get GET segmentproviders/{id}/
profiles/{id}
200 OK

{
  "segmentProviderId": "<segmentProviderId>",
  "id": "<profileId>",
  "segments": {
    "<segmentId 1>": {
        "expiration": "2016-03-08T15:37:46.662Z"
    },
    "<segmentId 2>": {
        "expiration": "2016-03-10T11:18:45.483Z"
    }
  }
}
Create/Replace

When updating a profile, the provided list will replace the previous list. All previously declared segments will be lost. The TTL of all segments will be reset.
PUT segmentproviders/{id}/
profiles/{id}

{
    "segments": [{
        "id": 2963
    }, {
        "id": 1425
    }]
}
200 OK
Partial Update

Patch is following the JavaScript Object Notation (JSON) Patch.
Currently supported operations are:
- add segment
- remove segment
PATCH segmentproviders/{id}/
profiles/{id}

[{"op": "add", "path": "/segments/6789"},
 {"op": "remove", "path": "/segments/2963"}]
204 No Content

Batch requests

You can batch requests to limit bandwidth usage and accelerate treatment time using the API requests mentioned above.

Creating a batch request

To create a batch request, create an HTTP request message as MIME multipart.

To send batched requests, use a POST on the batch URL:

POST https://dmpsandbox.smartadserverapis.com/batch HTTP/1.1

To separate the messages, you need to generate a unique ID which will be used as a boundary between each part of the request:

Content-Type: multipart/mixed; boundary="3bc5bd67-3517-4cd0-bcdd-9d23f3850402"

Then, all messages are prefixed as follows:

--3bc5bd67-3517-4cd0-bcdd-9d23f3850402
Content-Type: application/http; msgtype=request

As a result, you receive the message. You can pass any request.

Example GET

GET /segmentproviders/8A254C22-0213-4059-A9BE-05D76DF01C47/profiles/5245635414057967687 HTTP/1.1
Host: dmpsandbox.smartadserverapis.com

Example PATCH

PATCH /segmentproviders/8A254C22-0213-4059-A9BE-05D76DF01C47/profiles/5245635414057967687 HTTP/1.1
Content-Type: application/json
Host: dmpsandbox.smartadserverapis.com
 
{
  "operations": [
    {
      "operationType": "add",
      "path": "/segments/15"
    },
{
      "operationType": "add",
      "path": "/segments/16"
    },
  ]
}

The final message ends with the closing boundary (two hyphens at the end):

--3bc5bd67-3517-4cd0-bcdd-9d23f3850402--

Batch request full example

The example below sends a PUT, a PATCH and a GET.

Note 1: One empty line is mandatory to separate the header from the rest of the request.

Note 2: Within the message boundary the following is mandatory:
- One empty line to separate the prefix from the message header
- One empty line to separate the message header from the body
- One empty line to replace the body if the method GET is used

Copy/Paste the example below from this GIST:

Request:

POST http://dmpsandbox.smartadserverapis.com/batch HTTP/1.1
Host: dmpsandbox.smartadserverapis.com
Cache-Control: no-cache
Content-Type: multipart/mixed; boundary="3bc5bd67-3517-4cd0-bcdd-9d23f3850402"
Authorization: Bearer token
Accept: */*
Accept-Encoding: gzip, deflate
 
--3bc5bd67-3517-4cd0-bcdd-9d23f3850402
Content-Type: application/http; msgtype=request
 
PUT /segmentproviders/8A254C22-0213-4059-A9BE-05D76DF01C47/profiles/5245635414057967687 HTTP/1.1
Content-Type: application/json
Host: dmpsandbox.smartadserverapis.com
 
{
    "segments": [{
        "id": 16
    }]
}
 
--3bc5bd67-3517-4cd0-bcdd-9d23f3850402
Content-Type: application/http; msgtype=request
 
PATCH /segmentproviders/8A254C22-0213-4059-A9BE-05D76DF01C47/profiles/5245635414057967687 HTTP/1.1
Content-Type: application/json
Host: dmpsandbox.smartadserverapis.com
 
[
  {
    "op": "add",
    "path": "/segments/15"
  }
]
--3bc5bd67-3517-4cd0-bcdd-9d23f3850402
Content-Type: application/http; msgtype=request
 
GET /segmentproviders/8A254C22-0213-4059-A9BE-05D76DF01C47/profiles/5245635414057967687 HTTP/1.1
Host: dmpsandbox.smartadserverapis.com
 
 
--3bc5bd67-3517-4cd0-bcdd-9d23f3850402--

 

Associated response:

HTTP/1.1 200 OK
Cache-Control: private
Content-Length: 888
Content-Type: multipart/mixed; boundary="b4971ab4-ec25-4ee7-877a-6b4725386ba6"
Date: Fri, 01 Apr 2016 10:30:33 GMT
 
--b4971ab4-ec25-4ee7-877a-6b4725386ba6
Content-Type: application/http; msgtype=response
 
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 991
X-RateLimit-Reset: 1459506632
 
 
--b4971ab4-ec25-4ee7-877a-6b4725386ba6
Content-Type: application/http; msgtype=response
 
HTTP/1.1 204 No Content
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 993
X-RateLimit-Reset: 1459506634
 
 
--b4971ab4-ec25-4ee7-877a-6b4725386ba6
Content-Type: application/http; msgtype=response
 
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 991
X-RateLimit-Reset: 1459506634
Content-Type: application/json; charset=utf-8
 
{"segmentProviderId":"8a254c22-0213-4059-a9be-05d76df01c47","id":"5245635414057967687","segments":[{"id":16,"expiration":"2016-04-01T10:45:33.391Z"},{"id":15,"expiration":"2016-04-01T10:48:33.427Z"}]}
--b4971ab4-ec25-4ee7-877a-6b4725386ba6--

Error response codes

HTTP status code Description
401 Unauthorized Returned for requests without any 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.
500 Internal Server Error Returned in case of any unexpected error which could be raised in the system.

API rate limit

API calls are limited in time. The rate limit refers to calls per time unit per segmentProviderId:

  • Segments API: 1000 requests per day
  • Profiles API: 1000 requests per second

In the response header of each API call, you will find specific headers which indicate the state of the current rate limit.

Provided headers:

Header Description
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
Was this article helpful?
0 out of 0 found this helpful
Powered by Zendesk