Identity Service API guide

Adobe Experience Platform Identity Service manages the cross-device, cross-channel, and near real-time identification of your customers in what is known as an identity graph within Adobe Experience Platform.

Getting started

This guide requires a working understanding of the following components of Adobe Experience Platform:

The following sections provide additional information that you will need to know or have on-hand in order to successfully make calls to the Identity Service API.

Reading sample API calls

This guide provides example API calls to demonstrate how to format your requests. These include paths, required headers, and properly formatted request payloads. Sample JSON returned in API responses is also provided. For information on the conventions used in documentation for sample API calls, see the section on how to read example API calls in the Experience Platform troubleshooting guide.

Gather values for required headers

In order to make calls to Platform APIs, you must first complete the authentication tutorial. Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:

All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

All requests that contain a payload (POST, PUT, PATCH) require an additional header:

Region-based routing

The Identity Service API employs region-specific endpoints that require the inclusion of a {REGION} as part of the request path. During the provisioning of your organization, a region is determined and stored within your organization profile. Using the correct region with each endpoint ensures that all requests made using the Identity Service API are routed to the appropriate region.

There are two regions currently supported by Identity Service APIs: VA7 and NLD2.

The table below shows example paths using regions:

If you are unable to locate the region within your organization profile, please contact your system administrator for support.

Using the Identity Service API

Identity parameters used in these services can be expressed in one of two ways; composite or XID.

Composite identities are constructs including both the ID value and namespace. When using composite identities, the namespace can be supplied by either name (namespace.code) or ID (namespace.id).

When an identity is persisted, Identity Service generates and assigns an ID to that identity, called the native ID, or XID. All variations of Cluster and Mapping APIs support both composite identities and XID in their requests and response. One of the parameters is required - xid or combination of [ns or nsid] and id to use these APIs.

To limit the payload in responses, APIs adapt their responses to the type of identity construct used. That is, if you pass XID your responses will have XIDs, if you pass composite identities, the response will follow the structure used in the request.

The examples in this document do not cover the complete functionality of the Identity Service API. For the complete API, see the Swagger API Reference.

Next steps

Now that you have gathered the required credentials, you can now continue to read the rest of the developer guide. Each section provides important information regarding their endpoints and demonstrate example API calls for performing CRUD operations. Each call includes the general API format, a sample request showing required headers and properly formatted payloads, and a sample response for a successful call.