To create a new contact attribute, use the updateDataSet mutation. You must submit the type of operation (create) as an argument.

The maximum number of attributes in the audience is 2000.

mutation {
  updateDataSet(
    where: { dataSetId: "4fe4136f-c007-44a3-b38f-92220xxxxxxxx" }
    to: {
      attributes: {
        create: {
          name: "Delivery address"
          type: TEXT
          category: "Contact information"
        }
      }
    }
  ) {
    dataSetId
    dataJobId
  }
}

{
  "data": {
    "updateDataSet": {
      "dataSetId": "4fe4136f-c007-44a3-b38f-92220xxxxxxxx"
    }
  }
}

A non-null dataJobId means the change hasn't been applied yet. Poll the data job to confirm completion.

Use an array to create multiple contact attributes simultaneously.

mutation {
  updateDataSet(
    where: { dataSetId: "4fe4136f-c007-44a3-b38f-92220xxxxxxxx" }
    to: {
      attributes: {
        create: [
          { name: "Last order", type: DATE, category: "Demographic" }
          { name: "Avg. order amount", type: NUMBER, category: "Demographic", decimalPrecision: 0 }
        ]
      }
    }
  ) {
    dataSetId
    dataJobId
  }
}

{
  "data": {
    "updateDataSet": {
      "dataSetId": "4fe4136f-c007-44a3-b38f-92220xxxxxxxx"
    }
  }
}

Arguments

Arguments required by the updateDataSet object.

Argument	Nested field - level 1	Nested field - level 2	Values	Definition
`where`	`dataSetId`		ID	The ID of the audience to update
`to`	`attributes`	`create`	Object or array of objects	The changes you want to make

Here are the fields supported by the create object.

Field	Nested field	Values	Required?	Definition
`category`		String	Optional	Assigns an attribute to a category. 💡Use the Get all categories query to get the list of available values.
`decimalPrecision`		Integer	Optional	The number of decimal places to display. Applies to numeric attributes.
`identifyAs`	`channels`	Enumeration or array. Valid values: - `EMAIL` - `SMS` - `WHATSAPP` MOBILE is not a valid value here - this operation doesn't support it as a write channel.	Optional	Marks an attribute (Phone number or Email address) as addressable and ties it to the respective communication channel.
	`key`	Boolean. Default value - `false`.	Optional	Marks an attribute as key. The key attribute stores unique identifiers for contacts.
`mapAs`		Enumeration. Currently supported values: - `FIRST_NAME` - `LAST_NAME`	Optional	Maps this attribute to a standard field. Only these two values are currently supported — narrower than a general-purpose field.
`name`		String (case-sensitive)	Required	The name to assign to the new contact attribute. The name must be unique within the audience.
`type`		Enumeration. Valid values: - `TEXT` - `NUMBER` - `BOOLEAN` - `DATE` - `JSON` - `ARRAY`	Required	The data format of the attribute
`validateAs`		Enumeration (schema-defined validation types)	Optional	Applies built-in validation to this attribute's values.

Note on attributes related to contact information

When creating an attribute for contact information, you can specify which channel it applies to. The attribute will be marked as addressable in the system and tied to consent.

💡You can map the Phone number attribute to two channels: WhatsApp and SMS.

mutation {
  updateDataSet(
    where: { dataSetId: "4fe4136f-c007-44a3-b38f-92220xxxxxxxx" }
    to: {
      attributes: {
        create: {
          name: "Cell phone"
          type: TEXT
          category: "Contact information"
          identifyAs: {
          channels: [SMS, WHATSAPP]
        }
        }
      }
    }
  ) {
    dataSetId
    dataJobId
  }
}

{
  "data": {
    "updateDataSet": {
      "dataSetId": "4fe4136f-c007-44a3-b38f-92220xxxxxxxx"
    }
  }
}

If your audience was created without a key attribute, you can add this attribute any time later. Use the key field for this purpose. Other values to submit:

name: any string
type: TEXT
category: skip this field or submit Contact information (it's the default value for the key attribute)

⚠️ Once added, the key attribute cannot be removed from the audience.

mutation {
  updateDataSet(
    where: { dataSetId: "4fe4136f-c007-44a3-b38f-92220xxxxxxxx" }
    to: {
      attributes: {
        create: {
          name: "Contact key"
          type: TEXT
          identifyAs: { key: true }
        }
      }
    }
  ) {
    dataSetId
    dataJobId
  }
}

{
  "data": {
    "updateDataSet": {
      "dataSetId": "4fe4136f-c007-44a3-b38f-92220xxxxxxxx"
    }
  }
}

Fields

Fields returned by the updateDataSet mutation

Field	Values	Required?	Definition
`dataSetId`	ID	Required	The ID of your audience
`dataJobId`	ID	Optional	Present when the change hasn't finished processing yet. Poll this ID to confirm completion.

Possible error messages

Error code Definition

ATTRIBUTE_ALREADY_EXISTS An attribute with the same name is already available in the audience.

KEY_CATEGORY_NOT_ALLOWED

Error code	Definition
ATTRIBUTE_ALREADY_EXISTS	An attribute with the same name is already available in the audience.
KEY_CATEGORY_NOT_ALLOWED	This error appears if you try to add the Contact key attribute and assign it to a category other than Contact information. 💡 Change the `category` value to Contact information or remove the field from the mutation.
KEY_CREATION_NOT_ALLOWED	The audience already has a key attribute.

This error appears if you try to add the Contact key attribute and assign it to a category other than Contact information.

💡 Change the category value to Contact information or remove the field from the mutation.

KEY_CREATION_NOT_ALLOWED The audience already has a key attribute.