POST /contacts/v1/establish

Overview

Creates or returns a contact using the Contact Key and Contact Type provided in the payload.

JSON Parameters

Name	Type	Description
`contactKeys`	array	Required. String array of one or more contact keys.
`contactType`	number	The default contact type is `Default` or `0`. Most users do not modify the default value.
`returnResults`	boolean	Indicates if the call returns results. The default value is `true`.
`correlateResponseItem`	boolean	Indicates if the result items' return order matches the request order. The default value is `true`.
`includeNewContactAwareness`	boolean	Indicates that the contact has never been included in the results before. The default value is `false`.

Responses

Status	Name	Type	Description
200			Successfully Established Contact
	items	array	An array of contact result objects for the requested contacts to be established.
	items.value	object	The Contact result returned
	items.value.requestedContactKey	string	The requested Contact Key
	items.value.isNewContact	boolean	Returns if the Contact was newly created. Only is returned when includeNewContactAwareness=true
	items.value.contactReference	object	The Contact reference returned
	items.value.contactReference.contactID	long	The established Contact's ID
	items.value.contactReference.contactType	string	The established Contact's Type
	items.value.contactReference.contactKey	string	The established Contact's Type
	items.value.contactReference.contactStatus	string	The established Contact's Status
	items.value.requestItemIndex	int	The Contact reference's index in the Request
	items.value.resultMessages	array	An array of result messages related to this Contact
	requestServiceMessageID	guid	Service message ID for the request
	responseDateTime	datetime	The time the Response was created
	resultMessages	array	An array of result messages
	serviceMessageID	guid	Service message ID for the Response

Usage

This action requires these permissions.

Contact Builder, Administer Contact Data Model
Contact Builder, Access

Example Request

1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /contacts/v1/establish
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "ContactKeys": ["Key1", "Key2"],
8}

Example Response

1HTTP/1.1 200 Success
2[
3      {
4        "items": [
5            {
6                "value": {
7                    "requestedContactKey": "key1",
8                    "isNewContact": false,
9                    "contactReference": {
10                        "contactID": 295863490,
11                        "contactType": "Default",
12                        "contactKey": "key1",
13                        "contactStatus": "Active"
14                    }
15                },
16                "requestItemIndex": 0,
17                "resultMessages": []
18            },
19            {
20                "value": {
21                    "requestedContactKey": "key2",
22                    "isNewContact": false,
23                    "contactReference": {
24                        "contactID": 304574890,
25                        "contactType": "Default",
26                        "contactKey": "key2",
27                        "contactStatus": "Active"
28                    }
29                },
30                "requestItemIndex": 1,
31                "resultMessages": []
32            }
33        ],
34        "requestServiceMessageID": "53e4cbf8-b9b4-43d4-ba17-eedbfb0ffd90",
35        "responseDateTime": "2018-02-26T15:06:45.4009365-06:00",
36        "resultMessages": [],
37        "serviceMessageID": "70082431-9a48-4e3e-8dc5-f318ec5c3665"
38    }
39]

Example Fast Fire and Forget Request

1Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
2POST /contacts/v1/establish
3Content-Type: application/json
4Authorization: Bearer YOUR_ACCESS_TOKEN
5
6{
7    "ContactKeys": ["Key1", "Key2"],
8    "ReturnResults": "false",
9    "CorrelateResponseItem": "false",
10    "IncludeNewContactAwareness": "false"
11}

Example Fast Fire and Forget Response

1HTTP/1.1 200 Success
2[
3      {
4    "items": [],
5    "requestServiceMessageID": "3e3e76bc-e824-44ff-8e16-463cb446c837",
6    "responseDateTime": "2018-02-27T09:03:37.9793969-06:00",
7    "resultMessages": [
8        {
9            "resultType": "Operational",
10            "resultClass": "Information",
11            "resultCode": "ResponseReturnsNotRequested",
12            "message": "ServiceCommand.ResultsProcessing.Information",
13            "data": "The data operation returned successfully but no results were requested to be returned. "
14        }
15    ],
16    "serviceMessageID": "c76a245d-73b4-4150-9782-fd1d6769495d"
17}
18]