POST /contacts/v1/establish

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

This action requires these permissions.

Contact Builder | Administer Contact Data Model
Contact Builder | Access

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 don’t modify the default value.
`returnResults`	boolean	Indicates if the call returns results. The default value is `true`.
`correlateResponseItem`	boolean	Indicates if the return order of the result items matches the order in the request. 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 sample code sends a POST request to the Marketing Cloud Contacts API to create or return contact records based on provided contact keys.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/establish
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
    "ContactKeys": ["Key1", "Key2"],
}

The response contains information about the contacts that correspond to the specified keys.

[
  {
    "items": [
      {
        "value": {
          "requestedContactKey": "key1",
          "isNewContact": false,
          "contactReference": {
            "contactID": 295863490,
            "contactType": "Default",
            "contactKey": "key1",
            "contactStatus": "Active"
          }
        },
        "requestItemIndex": 0,
        "resultMessages": []
      },
      {
        "value": {
          "requestedContactKey": "key2",
          "isNewContact": false,
          "contactReference": {
            "contactID": 304574890,
            "contactType": "Default",
            "contactKey": "key2",
            "contactStatus": "Active"
          }
        },
        "requestItemIndex": 1,
        "resultMessages": []
      }
    ],
    "requestServiceMessageID": "53e4cbf8-b9b4-43d4-ba17-eedbfb0ffd90",
    "responseDateTime": "2026-02-26T15:06:45.4009365-06:00",
    "resultMessages": [],
    "serviceMessageID": "70082431-9a48-4e3e-8dc5-f318ec5c3665"
  }
]