---
schema_version: "1"
id: 5013dbd84aa905e3625d3ec73ec325560d5641ca48f880ce9dfef20b92b19198
title: POST /contacts/v1/establish
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/guides/mc-apis/establish-contacts-detail.md
canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_contacts/establish-contacts-detail.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: deb263376a7c0b07147d2134f6c9f7bf89c37747f02bf903b051be60c6e3dbe6
products:
  - Marketing Cloud Engagement APIs and Programmatic Languages
  - Marketing Cloud
---
# 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

<!--complex table-->

| 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** | &nbsp;                                     | &nbsp;   | **Successfully Established Contact**                                                            |
| &nbsp;  | items                                      | array    | An array of contact result objects for the requested contacts to be established.                |
| &nbsp;  | items.value                                | object   | The Contact result returned                                                                     |
| &nbsp;  | items.value.requestedContactKey            | string   | The requested Contact Key                                                                       |
| &nbsp;  | items.value.isNewContact                   | boolean  | Returns if the Contact was newly created. Only is returned when includeNewContactAwareness=true |
| &nbsp;  | items.value.contactReference               | object   | The Contact reference returned                                                                  |
| &nbsp;  | items.value.contactReference.contactID     | long     | The established Contact’s ID                                                                    |
| &nbsp;  | items.value.contactReference.contactType   | string   | The established Contact’s Type                                                                  |
| &nbsp;  | items.value.contactReference.contactKey    | string   | The established Contact’s Type                                                                  |
| &nbsp;  | items.value.contactReference.contactStatus | string   | The established Contact’s Status                                                                |
| &nbsp;  | items.value.requestItemIndex               | int      | The Contact reference’s index in the Request                                                    |
| &nbsp;  | items.value.resultMessages                 | array    | An array of result messages related to this Contact                                             |
| &nbsp;  | requestServiceMessageID                    | guid     | Service message ID for the request                                                              |
| &nbsp;  | responseDateTime                           | datetime | The time the Response was created                                                               |
| &nbsp;  | resultMessages                             | array    | An array of result messages                                                                     |
| &nbsp;  | 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.

```js
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.

```json
[
  {
    "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"
  }
]
```