POST /contacts/v1/establish

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

JSON Parameters

NameTypeDescription
contactKeysarrayRequiredString array of one or more contact keys.
contactTypenumberThe default contact type is "Default" or 0. Most users do not modify the default value.
returnResultsbooleanIndicates if the call returns results. The default value is true.
correlateResponseItembooleanIndicates if the result items' return order matches the request order. The default value is true.
includeNewContactAwarenessbooleanIndicates that the contact has never been included in the results before. The default value is true.

Responses

StatusNameTypeDescription
200  Successfully Established Contact
 itemsarrayAn array of contact result objects for the requested contacts to be established.
 items.valueobjectThe Contact result returned
 items.value.requestedContactKeystringThe requested Contact Key
 items.value.isNewContactbooleanReturns if the Contact was newly created. Only is returned when includeNewContactAwareness=true
 items.value.contactReferenceobjectThe Contact reference returned
 items.value.contactReference.contactIDlongThe established Contact's ID
 items.value.contactReference.contactTypestringThe established Contact's Type
 items.value.contactReference.contactKeystringThe established Contact's Type
 items.value.contactReference.contactStatusstringThe established Contact's Status
 items.value.requestItemIndexintThe Contact reference's index in the Request
 items.value.resultMessagesarrayAn array of result messages related to this Contact
 requestServiceMessageIDguidService message ID for the request
 responseDateTimedatetimeThe time the Response was created
 resultMessagesarrayAn array of result messages
 serviceMessageIDguidService message ID for the Response

Required Marketing Cloud Permissions

  • Contact Builder, Administer Contact Data Model
  • Contact Builder, Access

Example Request

Example Response

Example Fast Fire and Forget Request

Example Fast Fire and Forget Response