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.

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.

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.

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"
}