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

{
  "data": {
    "createContacts": {
      "items": [
        {
          "contactKey": "TAO_93216421"
        },
        {
          "contactKey": "MAW_93676421"
        },
        {
          "contactKey": "MAW_93216476"
        }
      ]
    }
  }
}

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

Fields

Fields returned by the createContacts mutation

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.

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).