Example endpoint for Universal ID providers

A Universal ID provider returns Universal IDs to the IX Library™ using an endpoint. Universal IDs can be people-based or cookie-based, depending on the graph type.

This example endpoint is provided as a guide for Universal ID providers. Individual endpoints may differ slightly from this example, depending on security or graph requirements.

Request

On page load, the IX Library calls the endpoint with a GET request from the publisher page. The URL structure of the endpoint should resemble the following example:

https://[partner_domain]/[endpoint]

For more information on addressability calls from the IX Library, including timeouts and caching, see Matching users using a Universal ID provider.

Request parameters

Parameter Data Type Description

Parameter	Data Type	Description
`tcf1`	String Optional (Required in the European Union)	The base64-encoded TCF1 consent string that specifies whether the user has consented to share their personal data in exchange for personalized advertising.

tcf1

String

Optional (Required in the European Union)

The base64-encoded TCF1 consent string that specifies whether the user has consented to share their personal data in exchange for personalized advertising.

Example JSON request body

https://www.graphprovider.com/graph?tcf1=BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA

Response values

The endpoint must directly respond with a JSON object containing the following information. Redirects that are used in legacy cookie-syncing solutions are not supported.

Parameter	Data Type	description
People-based graph
`p_id[]`	Array of objects Optional	A list of people-based identifiers.
`p_id[].id`	String Required	The people-based identifier value.
`p_id[].keyID`	Integer Optional	The key version used for encryption.
`p_id[].name`	String Optional	A tag that uniquely identifies the ID in the list.
Cookie-based graph
`c_id[]`	Array of objects Optional	A list of cookie-based identifiers.
`c_id[].id`	String Required	The cookie-based identifier value.
`c_id[].created_at`	Integer Optional	The date in UNIX timestamp format when the `c_id` was created.
`c_id[].is_new`	Integer Optional	Specifies whether this identifier is a new ID or an existing ID, where `0` is an existing ID `1` is a new ID
`c_id[].name`	String Optional	A tag that uniquely identifies the ID in the list.

Status codes

Response status will be determined partially by the HTTP code in the request response.

Parameter	description
`200`	IDs are available and successfully returned in the response.
`204`	No IDs are available for the request.
`4xx`	Any client errors.

Example JSON responses

Example response with a cookie-based ID

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 324
						
{ 
	"c_id": [{
		"created_at": 1574204491226,
		"is_new": 0,
		"id": "8304e715-1f13-4c31-bc31-39f873b9c447"
		"name": "existing_id",
	},{
		"created_at": 1574204491226,
		"is_new": 1,
		"id": "b37e4669-3933-41f5-a398-555dd8344839"
		"name": "new_id",		
		...
	}]
}

Example response with a people-based ID

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 83

{
	"p_id": [{
		"id": "ec8f0d10-604e-4c19-b312-22808d477832"
	}]
}

It is also possible to provide both people-based and cookie-based IDs. In this case, both the p_id and c_id keys would exist in the same response object.

Example Response Without IDs

HTTP/1.1 204 No Content

Example Error Response

HTTP/1.1 404 Not Found