Get Credentials

Get credentials

After signing in, you can create credentials that can be used to call the Platform APIs.

Identity Service API (1.0.0)

Download OpenAPI specification:Download

Delivering relevant digital experiences requires having a complete understanding of your customer. This is made more difficult when your customer data is fragmented across disparate systems, causing each individual customer to appear to have multiple "identities". Adobe Experience Platform Identity Service provides a RESTful API to help you to gain a better view of your customers and their behavior. By bridging identities across devices and systems, you are better able to deliver impactful, personal digital experiences in real-time.

Use the Identity Service API to manage identities, namespaces, and clusters linked to the Identity Graph.

Related documentation:

Visualize API calls with Postman (a free, third-party software):

API paths:

  • PLATFORM Gateway URL: https://platform-{REGION}.adobe.io
  • Base path for this API: /data/core/
  • Example of a complete path: https://platform-va7.adobe.io/data/core/identity/cluster/members

Required headers:

  • All calls require the headers Authorization, x-gw-ims-org-id, and x-api-key. For more information on how to obtain these values, see the authentication tutorial.
  • All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header x-sandbox-name whose value is the all-lowercase name of the sandbox the operation will take place in (for example, "prod"). See the sandboxes overview for more information.
  • All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the header Content-Type with a value of application/json.

(NEW) Interactive API documentation

You can now interact with the Experience Platform API endpoints directly from this API reference page. Get your authentication credentials and use the Try it functionality in the right rail. Note that by using this functionality, you are making real API calls. Keep this in mind when you interact with production sandboxes.

Identity

Identity services provide access to a profile identity in XID form.

Retrieve an identity

You can retrieve an identity (in the form of an XID string) by performing a GET request, given the identity namespace and an ID in that identity namespace.

Request
query Parameters
namespace
string

namespace code. One of namespace or nsid is required.

Example: namespace=adcloud
nsid
integer

namespace id. One of namespace or nsid is required. nsid will only be used if namespace was not provided.

id
required
string

Id in given namespace

Example: id=2521328045094711779817
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
string

The the all-lowercase name of the sandbox the operation will take place in. If unspecified, falls back to the default production sandbox (usually "prod"). See the sandboxes overview for more information.

Example: prod
x-uis-cst-ctx
string

Customer context to be used for stub response.

Example: stub
x-request-id
string

Request id to be used for tracing this request.

Accept
string
Default: application/json

The version of the resource's representation.

Responses
200

Success - Data Retrieved

400

Bad Request - Invalid Input

401

Unauthorized - Missing or Invalid Scope

403

Unauthorized - Missing Permissions

429

Too Many Requests - Rate Limit Exceeded

500

Server Error - Internal Error

get/identity/identity
Response samples
application/json
{
  • "xid": "HHDAHDKYYD"
}

Graph API

Graph API provides access to groupings of identities as linked in the identity graph.

List linked identities

Given set of identities, returns all linked identities in the graph corresponding to each identity.

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
string

The the all-lowercase name of the sandbox the operation will take place in. If unspecified, falls back to the default production sandbox (usually "prod"). See the sandboxes overview for more information.

Example: prod
x-request-id
string

Request id to be used for tracing this request.

Content-Type
required
string
Default: application/json

The type of content being sent in the request. Use 'application/json'.

Request Body schema: application/json
required

JSON object containing the list of xids/composite_xids identities for which to retrieved linked identities in the same format and additional filters.

Linked identities can be returned as a set or graph projection by setting projection_type.

The projection_type: graph option can be used alongside require_edge_meta_data: true to provide information about the datasets and batches which have contributed to each edge.

One of:
Array of objects (GraphResponseCompositeXid) [ 1 .. 1000 ] items
projection_type
string

This is a required field dictating the format of the returned graph: a set of members or a graph with vertices and edges.

Enum: "set" "graph"
graph_type
string
Array of objects (GraphRequestTraverse)
Array of objects (GraphRequestFilter)
object

This filter cannot be used with projection_type: graph.

require_edge_meta_data
boolean

This is and optional field that is used to add edge meta data in the response, such as dataset_ids and batch_ids. It will only apply if the requested projection_type is graph.

Responses
200

Success - Data Retrieved

400

Bad Request - Invalid Input

401

Unauthorized - Missing or Invalid Scope

403

Unauthorized - Missing Permissions

429

Too Many Requests - Rate Limit Exceeded

500

Server Error - Internal Error

post/identity/v2/graph
Request samples
application/json
{
  • "composite_xids": [
    ],
  • "projection_type": "set"
}
Response samples
application/json;version=2.2.1;charset=utf-8
{
  • "version": "2.0",
  • "graphs": [
    ],
  • "unprocessed_composite_xids": [ ],
  • "algo_type": "STITCH_ALL"
}

Identity Namespace

Identity namespaces provide context to identity data. Experience Platform provides standard namespaces as well as allowing organizations to create and manage custom namespaces.

Lists all identity namespaces available for the IMS Organization

The https://platform.adobe.io/data/core/idnamespace/orgs/{ORG}/identities endpoint has been deprecated. You may use the /idnamespace/identities endpoint to accomplish the same task and list all namespaces owned by a given organization.

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
string

The the all-lowercase name of the sandbox the operation will take place in. If unspecified, falls back to the default production sandbox (usually "prod"). See the sandboxes overview for more information.

Example: prod
x-request-id
string

Request id to be used for tracing this request.

Responses
200

Success - Namespaces List Retrieved

401

Unauthorized - Invalid IMS Token

500

Internal Server Error

get/idnamespace/identities
Response samples
application/json
[
  • {
    }
]

Create a new identity namespace

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
string

The the all-lowercase name of the sandbox the operation will take place in. If unspecified, falls back to the default production sandbox (usually "prod"). See the sandboxes overview for more information.

Example: prod
x-request-id
string

Request id to be used for tracing this request.

Content-Type
required
string
Default: application/json

The type of content being sent in the request. Use 'application/json'.

Request Body schema: application/json
required

JSON object containing the details of the namespace to be created.

  • name: (Required) A friendly name (or "Display Name") for the namespace.

  • code: (Required) Known as the "Identity symbol" in the user interface, the "code" is a single word descriptor for the namespace being created. Must be unique. May contain only letters and numbers.

  • idType: (Required) The "type" of namespace being created. Must be one of the following values: Cookie, Cross_device, Device, Email, Mobile, Non_people, or Phone.

  • description: (Optional) A description for the namespace. This is especially useful when multiple namespaces have been defined for your organization.

name
required
string
code
required
string
idType
required
string
Enum: "Cookie" "Cross_device" "Device" "Email" "Mobile" "Non_people" "Phone"
description
string
Responses
200

Identity namespace created

400

Invalid request data

401

Invalid authentication token

409

Namespace code conflict

500

Internal server error

post/idnamespace/identities
Request samples
application/json
{
  • "name": "Loyalty Member ID",
  • "code": "Loyalty",
  • "idType": "Email",
  • "description": "The email address associated with loyalty program membership."
}
Response samples
application/json
{
  • "updateTime": 1572918753626,
  • "code": "Loyalty",
  • "status": "ACTIVE",
  • "createTime": 1572918753626,
  • "description": "The email address associated with loyalty program membership.",
  • "idType": "Email",
  • "name": "Loyalty Member ID",
  • "id": 10018776,
  • "custom": true
}

Retrieve details of a specific identity namespace by its ID

The https://platform.adobe.io/data/core/idnamespace/orgs/{ORG}/identities/{ID} endpoint has been deprecated. You may use the /idnamespace/identities/{ID} endpoint to accomplish the same task and retrieve a specific namespace owned by a given organization.

Request
path Parameters
ID
required
integer

The numeric value of the "id" field.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
string

The the all-lowercase name of the sandbox the operation will take place in. If unspecified, falls back to the default production sandbox (usually "prod"). See the sandboxes overview for more information.

Example: prod
x-request-id
string

Request id to be used for tracing this request.

Responses
200

Namespace retrieved successfully

401

Invalid authentication token

404

Namespace not found

500

Internal server error

get/idnamespace/identities/{ID}
Response samples
application/json
{
  • "updateTime": 1572918753626,
  • "code": "Loyalty",
  • "status": "ACTIVE",
  • "createTime": 1572918753626,
  • "description": "The email address associated with loyalty program membership.",
  • "idType": "Email",
  • "name": "Loyalty Member ID",
  • "id": 10018776,
  • "custom": true
}

Update specific identity namespace

Request
path Parameters
ID
required
integer

The numeric value of the "id" field.

header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
string

The the all-lowercase name of the sandbox the operation will take place in. If unspecified, falls back to the default production sandbox (usually "prod"). See the sandboxes overview for more information.

Example: prod
Content-Type
required
string
Default: application/json

The type of content being sent in the request. Use 'application/json'.

Request Body schema: application/json
required

A JSON object containing the updated information for the namespace. This operation is essentially replacing the existing namespace, therefore all fields required to define the namespace must be sent in the request (with updated values for those attributes being changed).

name
required
string
code
required
string
idType
required
string
Enum: "COOKIE" "CROSS_DEVICE" "Device" "Email" "MOBILE" "Non_people" "Phone"
description
string
Responses
200

Namespace updated successfully

400

Invalid request

401

Invalid authentication token

404

Namespace not found

500

Internal server error

put/idnamespace/identities/{ID}
Request samples
application/json
{
  • "name": "New namespace name",
  • "code": "New namespace code",
  • "idType": "COOKIE",
  • "description": "New description."
}
Response samples
application/json
[
  • {
    }
]

Cluster

Cluster services provide access to groupings of identities as linked in the identity graph. These endpoints have been deprecated. Use Graph API to access groupings of identities as linked in the identity graph.

List linked identities for a given identityDeprecated

This endpoint has been deprecated. Use /identity/v2/graph to retrieve the related XIDs for a given XID.

Given an XID return all XIDs, in the same or other namespaces, that are linked to it by the device graph type. The related XIDs are considered to be part of the same cluster. It is required to pass either xid or (namespace/nsid & id) pair to get cluster members.

Request
query Parameters
xid
string

Identity string as returned by /identity GET api

Example: xid=2521328045094711779817
nsid
integer

namespace id

Example: nsid=411
namespace
string

namespace code

Example: namespace=adcloud
id
string

Id in given namespace

Example: id=2521328045094711779817
graph-type
string

Graph type (output type) you want to get the cluster from

Enum: "pdg" "coop" "psr"
Example: graph-type=pdg
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
string

The the all-lowercase name of the sandbox the operation will take place in. If unspecified, falls back to the default production sandbox (usually "prod"). See the sandboxes overview for more information.

Example: prod
x-uis-cst-ctx
string

Customer context to be used for stub response.

Example: stub
x-request-id
string

Request id to be used for tracing this request.

Accept
string
Default: application/json

The version of the resource's representation.

Responses
200

OK

400

Bad Request - Invalid Input Provided

401

Unauthorized - required scope missing

403

Unauthorized - Missing Permissions

429

Too Many Requests - Rate Limit Exceeded

500

Server Error - Unexpected Internal Error

get/identity/cluster/members
Response samples
application/json
{
  • "version": "1.1.0",
  • "clusters": [
    ],
  • "unprocessedRecords": [ ],
  • "algo_type": "STITCH_ALL"
}

List linked identities for a list of identitiesDeprecated

This endpoint has been deprecated. Use /identity/v2/graph to retrieve the related XIDs for a given list of XIDs.

Given set of identities, returns all linked identities in cluster corresponding to each identity

Request
header Parameters
Authorization
required
string

The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the authentication tutorial.

x-api-key
required
string

The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-gw-ims-org-id
required
string

The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the authentication tutorial.

x-sandbox-name
string

The the all-lowercase name of the sandbox the operation will take place in. If unspecified, falls back to the default production sandbox (usually "prod"). See the sandboxes overview for more information.

Example: prod
x-uis-cst-ctx
string

Customer context to be used for stub response.

Example: stub
x-request-id
string

Request id to be used for tracing this request.

Accept
string
Default: application/json

The version of the resource's representation.

Content-Type
required
string
Default: application/json

The type of content being sent in the request. Use 'application/json'.

Request Body schema: application/json
required

List of ID's for which we need to find related IDs

Array
xids
Array of strings (Id)

Primary parameter for the list of IDs to query.

Array of objects

Secondary parameter for the list of IDs to query. Is ignored if xids is also present in the request.

Array of objects

Tertiary parameter for the list of IDs to query. Is ignored if either xids or compositeXids are also present in the request.

graph-type
string
version
string
Responses
200

Successful response

400

Bad request

401

Unauthorized access

403

Unauthorized - Missing Permissions

429

Too many requests

500

Internal server error

post/identity/clusters/members
Request samples
application/json
{
  • "xids": [
    ]
}
Response samples
application/json
{
  • "version": "1.1.0",
  • "clusters": [
    ],
  • "unprocessedRecords": [ ],
  • "algo_type": "STITCH_ALL"
}