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

mutation {
  createContacts(
    contactsInput: [
      {
        attributes: [
          { name: "First name", value: "Diego" }
          { name: "Unique ID", value: "MAZ_93216421" }
          { name: "Email Address", value: "[email protected]" }
          { name: "Phone Number", value: "+581747557000" }
          { name: "Existing Customer", value: true }
        ]
      }
    ]
  ) {
    items {
      contactKey
    }
  }
}

{
  "data": {
    "createContacts": {
      "items": [
        {
          "contactKey": "MAZ_93216421"
        }
      ]
    }
  }
}

Use an array to create multiple contacts simultaneously.

mutation createMultipleContacts {
  createContacts(
    contactsInput: [
      {
        attributes: [
          { name: "First Name", value: "Frank" }
          { name: "Unique ID", value: "TAO_93216421" }
          { name: "Email Address", value: "[email protected]" }
          { name: "Existing Customer", value: true }
        ]
      }
      {
        attributes: [
          { name: "First Name", value: "Taio" }
          { name: "Unique ID", value: "MAW_93676421" }
          { name: "Phone Number", value: "+5845047557000" }
          { name: "Email Address", value: "[email protected]" }
        ]
      }
      {
        attributes: [
          { name: "First Name", value: "Anna" }
          { name: "Unique ID", 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"
        }
      ]
    }
  }
}

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	Values	Definition
`contactsInput`	Array	See the input fields

Input fields nested inside contactsInput

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

🚧
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

Field	Nested field	Required?	Definition
`items`	`contactKey`	Required	The unique identifier you have assigned to the new 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`

Create contacts

Arguments

🚧
Important

Fields

Possible error messages

Arguments

🚧Important

Fields

Possible error messages

🚧
Important