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