Create contacts

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.

FieldNested fieldValuesRequired?Definition
attributesnameString (case-sensitive)RequiredThe name of the attribute to populate for the contact.

⚠️ Check the names of available attributes using the Get all attributes query.
valueDepends on the type of attributeOptionalThe value of the contact attribute
consentArrayOptionalTo create contacts with consent statuses, see Create a contact with consent.

Fields

Fields returned by the createContacts mutation

FieldNested fieldRequired?Definition
itemscontactKeyRequiredThe 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 codeDefinition
ATTRIBUTE_NOT_DEFINEDThe mutation contains an attribute that is not available in the audience.

Check the names of available attributes using the dataSets query.
FAILED_CREATE_CONTACTThe contact hasn't been added to the audience.
IDENTIFIABLE_ATTRIBUTE_NOT_PROVIDEDYou must provide at least one addressable attribute for each contact (email or phone number).