Get Credentials

Get credentials

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

Data Prep API (1.0)

Download OpenAPI specification:Download

Data Prep allows data engineers to map, transform, and validate data to and from Experience Data Model (XDM). Use the Data Prep API to programmatically create mapping sets and functions, and transform your data between source and destination schemas.

Related documentation:
- Data Prep documentation
API paths:
- Platform Gateway URL: https://platform.adobe.io/
- Base path for this API: /data/foundation/conversation
- Example of a complete path: https://platform.adobe.io/data/foundation/conversion/languages/el/functions
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 Content-Type header with a value of application/json.
API error handling:
- Refer to the Experience Platform API troubleshooting guide for FAQs, API status codes, and request header errors.

(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.

Functions

Mapping-set functions allow you to transform your data between source and destination schemas. You can use these functions to validate your expressions and get a list of all the available mapping-set functions and operations.

Validate an expression

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.
Content-Type required	string The type of content being sent in the body of the request. This value generally is `application/json`.
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 IMS 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 required	string All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Request Body schema: application/json
required

The expression you are validating.

expression	string
mappingSetId	string
sampleData	string
sampleDataType	string

Responses

200

Validation status returned

400

Invalid expression error

401

Unauthorized request

500

Internal server error

503

Service unavailable

post/languages/el/validate

Request samples

Payload

application/json

{"expression": {"expression": "concat(\"Hi\", \",\", \"there\", \"!\")"
}
}

Response samples

application/json

false

List the available mapping set functions

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 IMS 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 required	string All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses

200

List of mapping-set functions retrieved

400

Invalid request error

401

Unauthorized access

500

Internal server error

503

Service unavailable

get/languages/el/functions

Response samples

application/json

[{"category": "Date / Time",
"function": "date",
"description": "Function that converts date string into a ZonedDateTime object.",
"syntax": "ZonedDateTime date(String, String, ZonedDateTime)",
"returns": "Returns the date object that is formatted in given format or a default date if the expression evaluates to a null date.",
"returnType": "java.time.ZonedDateTime",
"example": "",
"result": "",
"params": [ ],
"since": 1
},
{"category": "Hierarchies - Arrays",
"function": "first",
"description": "Function to retrieve the first element of the given array.",
"syntax": "T first(T...)",
"returns": "The first element or null if the array is null or empty.",
"returnType": "java.lang.Object",
"example": "first(\"1\", \"2\", \"3\")",
"result": "\"1\"",
"params": [{"name": "values",
"description": "Zero or more arguments",
"type": "object",
"dataType": "[Ljava.lang.Object;",
"position": 1
}
],
"since": 1
}
]

List the available mapping set operators

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 IMS 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 required	string All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses

200

List of valid operators retrieved

400

Invalid request error

401

Unauthorized access

500

Internal server error

503

Service unavailable

get/languages/el/operators

Response samples

application/json

[{"operatorSymbol": "+",
"methodName": "add",
"numberOfOperands": 2,
"description": "Simple arithmetic addition",
"example": "1 + 2"
},
{"operatorSymbol": "/",
"methodName": "divide",
"numberOfOperands": 2,
"description": "Simple arithmetic division",
"example": "1 / 2"
},
{"operatorSymbol": "~",
"methodName": "complement",
"numberOfOperands": 1,
"description": "The usual ~ operator is used, e.g., ~33, ~0010 0001 = 1101 1110 = -34.",
"example": "~44"
},
{"operatorSymbol": "-",
"methodName": "negate",
"numberOfOperands": 1,
"description": "The unary - operator is used. For example, -12",
"example": "-12"
},
{"operatorSymbol": "!",
"methodName": "not",
"numberOfOperands": 1,
"description": "The usual ! operator can be used as well as the word not, e.g., !cond1 and not cond1 are equivalent",
"example": "!cond1"
}
]

Mapping sets

Mapping sets can be used to define how data in a source schema maps to that of a destination schema.

List mapping sets

Request

query Parameters

limit required	integer <int32> Default: 10 The total number of records to fetch per page.
start required	integer <int32> Default: 0 Specifies the offset of the pages of results. To get the first page of results, set the value to `start=0`.
name	string Filter the mapping sets by name.
orderBy	string Default: "lastUpdateDate" Sorts the order of the results. Supported fields are: `createdDate` and `updatedDate`. Prepend the property name with `+` for ascending order and `-` for descending order.
expandSchema	boolean Determines whether the full output schema is returned as part of the response.

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 IMS 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 required	string All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses

200

List of mapping sets retrieved

400

Invalid request error

401

Unauthorized request

500

Internal server error

503

Service unavailable

get/mappingSets

Response samples

application/json

{"data": {"id": "428beb15b4864daaaa9dc3f005448005",
"version": 1,
"createdDate": 1582250953000,
"modifiedDate": 1582251156000,
"createdBy": "acp_xql_gateway",
"modifiedBy": "acp_ui_platform",
"supportVersion": "1.1",
"inputSchema": {"id": "e660142cab8e438382abc5691b364b30",
"version": 0,
"sampleId": "f9e83882e3e34c1f8b873a3b8113c01e"
},
"outputSchema": {"id": "1956affc28be468aa452e5e47c680c6b",
"version": 0,
"schemaRef": {"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "1.0"
}
},
"mappings": [{"id": "af809223484341009ce0db13d4b32a3a",
"version": 0,
"createdDate": 1582250953000,
"modifiedDate": 1582250953000,
"createdBy": "acp_xql_gateway",
"modifiedBy": "acp_xql_gateway",
"sourceType": "text/x.schema-path",
"source": "id",
"destination": "person.name.firstName",
"identity": false,
"primaryIdentity": false,
"matchScore": 0,
"functionVersion": 1,
"sourceAttribute": "id",
"destinationXdmPath": "person.name.firstName"
}
],
"status": "PUBLISHED",
"strictMapping": false,
"allowNullValues": false,
"xdmVersion": "1.0",
"schemaRef": {"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "1.0"
},
"xdmSchema": "https://ns.adobe.com/xdm/context/profile__union"
}
}

Create a mapping set

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.
Content-Type required	string The type of content being sent in the body of the request. This value generally is `application/json`.
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 IMS 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 required	string All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Request Body schema: application/json
required

The details of the mapping set you want to create.

allowNullValues	boolean
createdBy	string
createdDate	string <date-time>
id	string
	object (SchemaRepresentation)
	Array of objects (MappingOperation)
modifiedBy	string
modifiedDate	string <date-time>
name	string
	object (SchemaRepresentation)
supportVersion	string
version	integer <int32>
	Array of objects (Tags)

Responses

200

Mapping set created successfully

400

Invalid mapping set request

401

Unauthorized request

500

Internal server error

503

Service unavailable

post/mappingSets

Request samples

Payload

application/json

{"mappings": [{"sourceType": "ATTRIBUTE",
"source": "id",
"destination": "_id",
"name": "id",
"description": "Identifier field"
},
{"sourceType": "ATTRIBUTE",
"source": "firstName",
"destination": "person.name.firstName"
},
{"sourceType": "ATTRIBUTE",
"source": "lastName",
"destination": "person.name.lastName"
}
],
"outputSchema": {"schemaRef": {"id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
}
}

Response samples

application/json

{"id": "e7c80e4c0d8f4a98a7d400b4e178b635",
"version": 0,
"createdDate": 1614901254724,
"modifiedDate": 1614901254724,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}

Validate a mapping set

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.
Content-Type required	string The type of content being sent in the body of the request. This value generally is `application/json`.
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 IMS 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 required	string All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Request Body schema: application/json
required

The mapping set you want to validate.

allowNullValues	boolean
createdBy	string
createdDate	string <date-time>
id	string
	object (SchemaRepresentation)
	Array of objects (MappingOperation)
modifiedBy	string
modifiedDate	string <date-time>
name	string
	object (SchemaRepresentation)
supportVersion	string
version	integer <int32>
	Array of objects (Tags)

Responses

200

Mapping set validation successful

400

Invalid mapping set request

401

Unauthorized request

500

Internal server error

503

Service unavailable

post/mappingSets/validate

Request samples

Payload

application/json

{"mappings": [{"sourceType": "ATTRIBUTE",
"source": "id",
"destination": "_id",
"name": "id",
"description": "Identifier field"
},
{"sourceType": "ATTRIBUTE",
"source": "firstName",
"destination": "person.name.firstName"
},
{"sourceType": "ATTRIBUTE",
"source": "lastName",
"destination": "person.name.lastName"
}
],
"outputSchema": {"schemaRef": {"id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
}
}

Response samples

application/json

{"validationResponse": [{"status": "SUCCESS",
"errors": null
},
{"status": "SUCCESS",
"errors": null
},
{"status": "SUCCESS",
"errors": null
}
]
}

Preview mapping sets

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.
Content-Type required	string The type of content being sent in the body of the request. This value generally is `application/json`.
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 IMS 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 required	string All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Request Body schema: application/json
required

The data you want to run through as a preview, which will be transformed by the mapping sets within the body.

	Array of objects (JsonNode)
	object (MappingSet)

Responses

200

Mapped data preview successful

400

Invalid request error

401

Unauthorized request

500

Internal server error

503

Service unavailable

post/mappingSets/preview

Request samples

Payload

application/json

{"data": {"id": 1234,
"firstName": "Jim",
"lastName": "Seltzer"
},
"mappingSet": {"outputSchema": {"schemaRef": {"id": "https://ns.adobe.com/stardust/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"mappings": [{"sourceType": "ATTRIBUTE",
"source": "id",
"destination": "_id",
"name": "id",
"description": "Identifier field"
},
{"sourceType": "ATTRIBUTE",
"source": "firstName",
"destination": "person.name.firstName"
},
{"sourceType": "ATTRIBUTE",
"source": "lastName",
"destination": "person.name.lastName"
}
]
}
}

Response samples

application/json

{"data": {"person": {"name": {"firstName": "Jim",
"lastName": "Seltzer"
}
},
"_id": "1234"
}
}

Retrieve a mapping set

Request

path Parameters

MAPPING_SET_ID

required

string

The ID of the mapping set you are retrieving.

Example: 7c80e4c0d8f4a98a7d400b4e178b635

query Parameters

expandSchema	boolean Default: false Determines whether to return the output schema as part of the response.
version	integer <int32> Default: 0 Determines which version of the mapping set to retrieve.

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 IMS 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 required	string All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses

200

Mapping set details retrieved

400

Invalid request error

401

Unauthorized request

500

Internal server error

503

Service unavailable

get/mappingSets/{MAPPING_SET_ID}

Response samples

application/json

{"mappings": [{"sourceType": "ATTRIBUTE",
"source": "id",
"destination": "_id",
"name": "id",
"description": "Identifier field"
},
{"sourceType": "ATTRIBUTE",
"source": "firstName",
"destination": "person.name.firstName"
},
{"sourceType": "ATTRIBUTE",
"source": "lastName",
"destination": "person.name.lastName"
}
],
"outputSchema": {"schemaRef": {"id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
}
}

Update a mapping set

Request

path Parameters

MAPPING_SET_ID

required

string

The ID of the mapping set you want to update.

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.
Content-Type required	string The type of content being sent in the body of the request. This value generally is `application/json`.
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 IMS 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 required	string All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Request Body schema: application/json
required

The updated content of the mapping set.

allowNullValues	boolean
createdBy	string
createdDate	string <date-time>
id	string
	object (SchemaRepresentation)
	Array of objects (MappingOperation)
modifiedBy	string
modifiedDate	string <date-time>
name	string
	object (SchemaRepresentation)
supportVersion	string
version	integer <int32>
	Array of objects (Tags)

Responses

200

Mapping set updated successfully

400

Invalid request error

401

Unauthorized request

500

Internal server error

503

Service unavailable

put/mappingSets/{MAPPING_SET_ID}

Request samples

Payload

application/json

{"mappings": [{"sourceType": "ATTRIBUTE",
"source": "id",
"destination": "_id",
"name": "id",
"description": "Identifier field"
},
{"sourceType": "ATTRIBUTE",
"source": "firstName",
"destination": "person.name.firstName"
},
{"sourceType": "ATTRIBUTE",
"source": "lastName",
"destination": "person.name.lastName"
}
],
"outputSchema": {"schemaRef": {"id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
}
}

Response samples

application/json

{"mappings": [{"sourceType": "ATTRIBUTE",
"source": "id",
"destination": "_id",
"name": "id",
"description": "Identifier field"
},
{"sourceType": "ATTRIBUTE",
"source": "firstName",
"destination": "person.name.firstName"
},
{"sourceType": "ATTRIBUTE",
"source": "lastName",
"destination": "person.name.lastName"
}
],
"outputSchema": {"schemaRef": {"id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
}
}

Retrieve a list of mappings for a specified mapping set

Request

path Parameters

MAPPING_SET_ID

required

string

The ID of the mapping set you are retrieving mappings for.

Example: 7c80e4c0d8f4a98a7d400b4e178b635

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 IMS 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 required	string All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses

200

All mappings retrieved successfully

400

Invalid request error

401

Unauthorized request

500

Internal server error

503

Service unavailable

get/mappingSets/{MAPPING_SET_ID}/mappings

Response samples

application/json

{"id": "394bec970d54410b98e1d4c55a3843ca",
"version": 0,
"createdDate": 1614909614000,
"modifiedDate": 1614909614000,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}",
"sourceType": "text/x.schema-path",
"source": "firstName",
"destination": "person.name.firstName",
"identity": false,
"primaryIdentity": false,
"matchScore": 0,
"functionVersion": 1,
"sourceAttribute": "firstName",
"destinationXdmPath": "person.name.firstName"
}

Retrieve a mapping from a specified mapping set

Request

path Parameters

MAPPING_SET_ID required	string The ID of the mapping set you want to retrieve a specific mapping from. Example: 7c80e4c0d8f4a98a7d400b4e178b635
MAPPING_ID required	string The ID of the mapping you want to retrieve. Example: 394bec970d54410b98e1d4c55a3843ca

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 IMS 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 required	string All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the sandboxes overview for more information.

Responses

200

Specific mapping details retrieved

400

Invalid request error

401

Unauthorized request

500

Internal server error

503

Service unavailable

get/mappingSets/{MAPPING_SET_ID}/mappings/{MAPPING_ID}

Response samples

application/json

{"id": "394bec970d54410b98e1d4c55a3843ca",
"version": 0,
"createdDate": 1614909614000,
"modifiedDate": 1614909614000,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}",
"sourceType": "text/x.schema-path",
"source": "firstName",
"destination": "person.name.firstName",
"identity": false,
"primaryIdentity": false,
"matchScore": 0,
"functionVersion": 1,
"sourceAttribute": "firstName",
"destinationXdmPath": "person.name.firstName"
}

Get credentials

Data Prep API (1.0)

(NEW) Interactive API documentation

Functions

Validate an expression

header Parameters

Request Body schema: application/jsonrequired

List the available mapping set functions

header Parameters

List the available mapping set operators

header Parameters

Mapping sets

List mapping sets

query Parameters

header Parameters

Create a mapping set

header Parameters

Request Body schema: application/jsonrequired

Validate a mapping set

header Parameters

Request Body schema: application/jsonrequired

Preview mapping sets

header Parameters

Request Body schema: application/jsonrequired

Retrieve a mapping set

path Parameters

query Parameters

header Parameters

Update a mapping set

path Parameters

header Parameters

Request Body schema: application/jsonrequired

Retrieve a list of mappings for a specified mapping set

path Parameters

header Parameters

Retrieve a mapping from a specified mapping set

path Parameters

header Parameters

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required