API reference
Help centerCommunityDevelopersAcademyStatus

Create contacts

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

mutation {
  createContacts(
    contactsInput: [
      {
        attributes: [
          { name: "First Name", value: "Diego" }
          { name: "Country", value: "Argentina" }
          { name: "Cell Phone", value: "+541130000000" }
        ]
      }
    ]
    dataSetId: "4fe4136f-c007-44a3-b38f-92220xxxxxxxx"
  ) {
    items {
      contactId
    }
  }
}

{
  "data": {
    "createContacts": {
      "items": [
        {
          "contactId": "a364f922-2845-4718-9705-00000000y000"
        }
      ]
    }
  }
}

Use an array to create multiple contacts simultaneously. 

mutation createMultipleContacts {
  createContacts(
    contactsInput: [
      {
        attributes: [
          { name: "First Name", value: "Diego" }
          { name: "Country", value: "Argentina" }
          { name: "Email Address", value: "[email protected]" }
        ]
      }
      {
        attributes: [
          { name: "First Name", value: "Taio" }
          { name: "Country", value: "Canada" }
          { name: "Email Address", value: "[email protected]" }
        ]
      }
      {
        attributes: [
          { name: "First Name", value: "Anna" }
          { name: "Country", value: "Canada" }
          { name: "Email Address", value: "[email protected]" }
        ]
      }
    ]
    dataSetId: "4fe4136f-c007-44a3-b38f-92220xxxxxxxx"
  ) {
    items {
      contactId
    }
  }
}

{
  "data": {
    "createContacts": {
      "items": [
        {
          "contactId": "a364f922-2845-4718-9705-00000000y000"
        },
        {
          "contactId": "a364f922-2845-4718-9705-00000000y000"
        },
        {
          "contactId": "a364f922-2845-4718-9705-00000000y000"
        }
      ]
    }
  }
}

You can identify contacts in your audience using their IDs (recommended) or addressable attributes (emails or phone numbers).

  • For the IDs, you need to have a contact attribute identified as key. You are responsible for generating and maintaining the IDs.
  • 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.

Arguments

Arguments required by the createContacts mutation

Argument nameValuesDefinition
dataSetIdIDThe ID of your audience
contactsInputArraySee the input fields

Input fields nested inside contactsInput

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

🚧

Important

To create a contact, you must submit at least one addressable attribute for them (the one that has a channel defined). It can be a phone number or an email address.

Fields

Fields returned by the createContacts mutation

FieldNested fieldRequired?Definition
itemscontactIdRequiredA unique identifier that will be generated for the new contact. Defines response structure.

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_CONTACT