---
schema_version: "1"
id: df9a50c5fff07f93b4b02d14803b449afe40f354f4b41db8b6486c601ef7d3e5
title: POST /contacts/v1/contacts
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/guides/mc-apis/createContacts.md
canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_contacts/createContacts.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: a29bf107df097fdd80b9af00ca08d3113c5fbc60958140f48a7265e71b1deade
products:
  - Marketing Cloud Engagement APIs and Programmatic Languages
  - Marketing Cloud
---
# POST /contacts/v1/contacts

## Overview

Creates a new contact with the specified information in the specified attribute groups.

### JSON Parameters

| Name                         | Type   | Description                                                                                                                                       |
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contactKey`                 | string | Primary address for the contact. You must provide either a value for contactKey or contactID.                                                     |
| `contactID`                  | string | Unique ID for the contact. You must provide either a value for contactKey or contactID.                                                           |
| `attributeSets`              | array  | Required. Array of information used to create a new contact                                                                                       |
| `attributeSets.name`         | string | Required. Name of attribute group to which to add the contact information                                                                         |
| `attributeSets.items`        | array  | Required. Array of items associated with the attribute group. Each item contains the values that define the contact's information for that group. |
| `attributeSets.items.values` | array  | Required. Name and value pairs indicating the attribute and its applicable value within the item.                                                 |

### Usage

To create a contact record, issue a POST request to the `/contacts/v1/contacts` endpoint.

**Example Request**

The request must include at least one of the attribute sets to create a new contact:

- Email Addresses (You must also include this attribute set if you include Email Demographics)
- MobileConnect Demographics (You must include a country code for the `Locale` value)
- MobilePush Demographics (You must include an `ApplicationID` value)
- LINE Addresses and LINE Subscriptions (You must also include these attribute sets if you include LINE Demographics)

Each request accepts only one instance of each attribute set.

You must also include values for `contactKey` and `HTML Enabled`.

Change `@example.com` to a valid domain.

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

{
    "contactKey": "acruz@example.com",
    "attributeSets": [{
        "name": "Email Addresses",
        "items": [{
            "values": [{
                "name": "Email Address",
                "value": "acruz@example.com"
            },
            {
                "name": "HTML Enabled",
                "value": true
            }]
        }]
    },
    {
        "name": "Email Demographics",
        "items": [{
            "values": [{
                "name": "Last Name",
                "value": "Cruz"
            },
            {
                "name": "First Name",
                "value": "Angela"
            },
            {
                "name": "Text Profile Attribute",
                "value": "value 1"
            },
            {
                "name": "Number Profile Attribute",
                "value": 12345
            }]
        }]
    },
    {
        "name": "MobileConnect Demographics",
        "items": [{
            "values": [{
                "name": "Mobile Number",
                "value": "317-531-5555"
            },
            {
                "name": "Locale",
                "value": "US"
            },
            {
                "name": "Status",
                "value": 1
            }]
        }]
    },
    {
        "name": "MobilePush Demographics",
        "items": [{
            "values": [{
                "name": "Device ID",
                "value": 958405948
            },
            {
                "name": "Application",
                "value": 958405948
            }]
        }]
    },
    {
        "name": "GroupConnect LINE Addresses",
        "items": [{
            "values": [{
                "name": "Address ID",
                "value": "addressId_from_api"
            }
           ]
        }]
    },
    {

        "name": "GroupConnect LINE Subscriptions",
        "items": [{
            "values": [{
                "name": "Address ID",
                "value": "addressId_from_api"
             },
             {
                "name": "Channel ID",
                "value": "1234567890"
            }]
        }]
    },
    {
        "name": "GroupConnect LINE Demographics",
        "items": [{
            "values": [{
                "name": "Address ID",
                "value": "addressId_from_api"
            },
            {
                "name": "Display Name",
                "value": "display_name"
            },
            {
                "name": "Picture Url",
                "value": "picture_url"
            },
            {
                "name": "Status Message",
                "value": "status_message"
            }]
        }]
    }
  ]
}
```

**Example Response**

After a successful request, the API returns a confirmation of the changes that were made.

```js
200 (OK)
Content-Type: application/json
{
    "operationStatus": "OK",
    "rowsAffected": 1,
    "contactKey": "acruz@example.com",
    "contactId": 12345678,
    "contactTypeID": 0,
    "isNewContactKey": false,
    "requestServiceMessageID": "8b51b524-28c1-46fc-9a44-02fca5b0a08c",
    "hasErrors": false,
    "resultMessages": [],
    "serviceMessageID": "80676c59-ceb9-48aa-ad35-81e150094a17"
}
```

If the create request fails, the API returns an error response that includes information about the failure.

```js
400 (Bad Request)
Content-Type: application/json
{
  "operationStatus": "FAIL",
  "rowsAffected": 0,
  "requestServiceMessageID": "c37cff97-8930-4124-9b9d-921b688056bd",
  "responseDateTime": "2026-07-15T12:54:33.4288209-06:00",
  "hasErrors": true,
  "resultMessages": [
    {
      "resultType": "Validation",
      "resultClass": "Error",
      "resultCode": "InvalidAttributeSet",
      "message": "The AttributeSet 'Email Addresses' must contain an 'items' array. The 'items' property cannot be null."
    }
  ],
  "serviceMessageID": "5bbb662a-1d88-42a6-8331-896e0acb4d3b"
}
```