Example RTI endpoint

An identity graph provider uses a Real Time Identity (RTI) endpoint to return identifiers to the IX Library™. These identifiers can be people-based or cookie-based, depending on the graph type.

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

Request

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

https://[partner_domain]/[endpoint]

For more information on RTI calls from the IX Library, including timeouts and caching, see How RTI works in the IX Library.

Request parameters

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.

Note: Index Exchange (IX) will continue to support TCF 1.1 along the IAB's timeline until Aug 15, 2020.

sonar_<user-attribute>_<encoding>_
<implementation>_
<provider>_<name>

String

Optional

The value of the Publisher Sonar™ string, where

  • user-attribute (integer): attribute of the user this data describes where
    • 1 is email
    • 2 is phone number (generic)
  • encoding (integer): encoding format or hashing algorithm, where
    • 1 is sha1
    • 2 is sha256
    • 3 is sha512
  • implementation (integer): origin of the entry point, where
    • 1 is freewall
  • provider (integer): entrypoint provider
  • name (integer): extra identifier to distinguish between multiple entrypoints of the same type

Example JSON request body

https://www.graphprovider.com/graph?tcf1=BOEFEAyOEFEAyAHABDENAI4AAAB9vABAASA&sonar_1_2_3_pvr_tag=01d9f895b5fd50b5b1f950a231b0371f

Response values

The RTI 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