To create new contacts in your audience, use the createContacts mutation.

You must submit at least one addressable attribute for each new contact (email or phone number).

For the emails, you need a contact attribute identified as the EMAIL channel.
For the phone numbers, you need a contact attribute identified as the SMS channel.

We recommend additionally identifying contacts using contact keys (unique IDs).

mutation createMultipleContacts {
  createContacts(
    contactsInput: [
      { attributes: [
          { name: "First Name", value: "Frank" }
          { name: "Email Address", value: "[email protected]" }
      ] }
    ]
  ) {
    items {
      contactKey
      message
      identifyingField {
        value
      }
    }
  }
}

mutation createMultipleContacts {
  createContacts(
    contactsInput: [
      {
        attributes: [
          { name: "First Name", value: "Frank" }
          { name: "Contact key", value: "TAO_93216421" }
          { name: "Email Address", value: "[email protected]" }
          { name: "Existing Customer", value: true }
        ]
      }
      {
        attributes: [
          { name: "First Name", value: "Taio" }
          { name: "Contact key", value: "MAW_93676421" }
          { name: "Phone Number", value: "+5845047557000" }
          { name: "Email Address", value: "[email protected]" }
        ]
      }
      {
        attributes: [
          { name: "First Name", value: "Anna" }
          { name: "Contact key", value: "MAW_93216476" }
          { name: "Email Address", value: "[email protected]" }
          { name: "Existing Customer", value: false }
        ]
      }
    ]
  ) {
    items {
      contactKey
      message
      identifyingField {
        value
      }
    }
  }
}

{
  "data": {
    "createContacts": {
      "items": [
        {
          "contactKey": "TAO_93216421",
          "message": "Contact was created.",
          "identifyingField": {
            "value": "[email protected]"
          }
        },
        {
          "contactKey": "MAW_93676421",
          "message": "Contact was created.",
          "identifyingField": {
            "value": "[email protected]"
          }
        },
        {
          "contactKey": "MAW_93216476",
          "message": "Contact was created.",
          "identifyingField": {
            "value": "[email protected]"
          }
        }
      ]
    }
  }
}

Running the mutation

If you haven't used our API before, see Using the Connect API for instructions. It explains how to authenticate your calls and suggests some tools for testing.

Mutation structure

Arguments

The createContacts mutation contains the contactsInput argument at the top level. It's an array of objects. Each contact requires its own object.

Here are the input fields supported by objects within the contactsInput array.

Field Nested field Values Required? Definition

Field	Nested field	Values	Required?	Definition
`attributes`	`name`	String (case-sensitive)	Required	The name of the attribute to populate for the contact. ⚠️ Check the names of available attributes using the Get all attributes query.
	`value`	Depends on the type of attribute	Optional	The value of the contact attribute
`consent`		Array	Optional	To create contacts with consent statuses, see Create a contact with consent.

attributes

name

String (case-sensitive)

Required

The name of the attribute to populate for the contact.

⚠️ Check the names of available attributes using the Get all attributes query.

value Depends on the type of attribute Optional The value of the contact attribute

consent Array Optional To create contacts with consent statuses, see Create a contact with consent.

Parameter	GraphQL type	Description
`value`	`JSON`	Accepts string, number, boolean, array, or object
`contactsInput`	`[ContactCreateInput!]!`	One entry per contact to create
`consent`	`ConsentInput`	Optional consent preferences for this contact

📘
The JSON scalar
The value field accepts any JSON value — string, number, boolean, array, or object. Declare variables as JSON!, not String!:

query FindContact($emailValue: JSON!) {
  contacts(filter: [{ field: "Email Address", eq: $emailValue }]) {
    items { contactKey }
  }
}

Declaring String! causes the error: Variable "$emailValue" of type "String!" used in position expecting type "JSON". The value itself does not change — a JSON string is already valid JSON.

Fields

Fields returned by the createContacts mutation

Field Nested field Required? Definition

Field	Nested field	Required?	Definition
`items`	`contactKey`	Required	The list of contact keys identifying the new contacts. ⚠️ If you don't provide a key for a contact, the mutation will return the `null` value for this contact.
	`message`	Required	The outcome for this contact. Returns `Contact was created.` for a new contact, or `Contact was updated.` when a matching contact already existed.
	`identifyingField`	Required	The addressable attribute used to identify this contact. Contains `value`, the attribute value, and `attributeData`, the attribute definition.

items

contactKey

Required

The list of contact keys identifying the new contacts.

⚠️ If you don't provide a key for a contact, the mutation will return the null value for this contact.

message Required The outcome for this contact. Returns Contact was created. for a new contact, or Contact was updated. when a matching contact already existed.

identifyingField Required The addressable attribute used to identify this contact. Contains value, the attribute value, and attributeData, the attribute definition.

Possible error messages

Error code	Definition
ATTRIBUTE_NOT_DEFINED	The mutation contains an attribute that is not available in the audience. Check the names of available attributes using the dataSets query.
FAILED_CREATE_CONTACT	The contact hasn't been added to the audience.
IDENTIFIABLE_ATTRIBUTE_NOT_PROVIDED	You must provide at least one addressable attribute for each contact (email or phone number).

Error code

Definition

ATTRIBUTE_NOT_DEFINED

The mutation contains an attribute that is not available in the audience.

Check the names of available attributes using the dataSets query.

FAILED_CREATE_CONTACT

The contact hasn't been added to the audience.

IDENTIFIABLE_ATTRIBUTE_NOT_PROVIDED

You must provide at least one addressable attribute for each contact (email or phone number).