Create attribute definition

Create attribute definition

post

https://api.bird.comhttp://localhost:3000https://api.bird.ai

/workspaces/{workspaceId}/attribute-definitions

This endpoint is used to create a new attribute definition for all contacts in a workspace. A contact attribute definition is used to define the attributes that a contact can have.

Authorizations

MessageBird_userMessageBird_accessKey

AuthorizationstringRequired

An access token issued to a user.

Path parameters

workspaceIdstring · uuidRequired

Your workspace identifier.

Example: b4e02c85-c6d2-4b15-8885-e09671799c61

Body

application/json

keystringRequired

A user-specified key, primarily for client reference.

Example: countryCodePattern: ^[A-Za-z\d_-]{1,64}$

displayNamestring · min: 1 · max: 150Required

A human-readable name of the attribute.

Example: Country Code

descriptionstring · max: 500Optional

A user-friendly description of the attribute.

Example: The country code of the contact

cardinalitystring · enumRequired

The cardinality configures how many values belong to the single key.

Possible values:

typestring · enumRequiredPossible values:

formatone ofOptional

or

or

or

or

or

or

or

piibooleanRequired

A flag to indicate whether this attribute is considered personally identifiable information.

Example: false

readOnlybooleanRequired

A flag to indicate whether this attribute may be updated after creation.

Example: false

Responses

201

The attribute definition was created successfully.

application/json

idstringOptional

The UUID, primarily for internal reference

Example: 123e4567-e89b-12d3-a456-426614174000

keystringOptional

A user-specified key, primarily for client reference.

Example: countryCode

displayNamestringOptional

A human-readable name of the attribute.

Example: Country Code

descriptionstringOptional

A user-friendly description of the attribute.

Example: The country code of the contact.

cardinalitystring · enumOptional

The cardinality configures how many values belong to the single key.

Possible values:

typestring · enumOptional

The data type of the attribute.

Possible values:

formatone ofOptional

or

or

or

or

or

or

or

piibooleanOptional

A flag to indicate whether this attribute is considered personally identifiable information.

Example: false

readOnlybooleanOptional

A flag to indicate whether this attribute may be updated after creation.

Example: false

builtinbooleanOptional

A flag to indicate whether this attribute is built-in. Built-in attributes are system-defined and cannot be updated or deleted by end-users.

Example: false

archivedbooleanOptional

A flag to indicate whether this attribute is archived.

Example: false

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

versionnumberOptional

The version number of the attribute definition.

Example: 1

404

The workspace was not found.

application/json

409

The HTTP could not be completed because of a conflict with the current state of the resource.

application/json

422

The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.

application/json

post

/workspaces/{workspaceId}/attribute-definitions

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/attribute-definitions HTTP/1.1
Host: api.bird.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 377

{
  "key": "countryCode",
  "displayName": "Country Code",
  "description": "The country code of the contact",
  "cardinality": "one",
  "type": "boolean",
  "format": {
    "type": "emailAddress"
  },
  "pii": false,
  "readOnly": false,
  "indexMapping": {
    "fields": [
      {
        "name": "emailaddress-standard",
        "analyzer": "simple",
        "type": "string"
      }
    ]
  },
  "acl": [
    {
      "roleId": "123e4567-e89b-12d3-a456-426614174000",
      "read": true,
      "write": true
    }
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "key": "countryCode",
  "displayName": "Country Code",
  "description": "The country code of the contact.",
  "cardinality": "one",
  "type": "boolean",
  "format": {
    "type": "emailAddress"
  },
  "pii": false,
  "readOnly": false,
  "builtin": false,
  "archived": false,
  "indexMapping": {
    "fields": [
      {
        "name": "emailaddress-standard",
        "analyzer": "simple",
        "type": "string"
      }
    ]
  },
  "createdAt": "2026-03-10T00:04:14.145Z",
  "updatedAt": "2026-03-10T00:04:14.145Z",
  "version": 1,
  "acl": [
    {
      "roleId": "123e4567-e89b-12d3-a456-426614174000",
      "read": true,
      "write": true
    }
  ]
}

Examples

Let's establish some of our data that will be used in the following examples:

• Workspace ID: a1405560-c8d3-4b1a-877d-3f449ad95352

• AccessKey: abcd

Create an attribute definition

In this example, we're creating a basic attribute definition.

Request

curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/attribute-definitions" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "type": "string",
  "key": "countryCode",
  "displayName": "countryCode", 
  "description": "Country code",
  "pii": false,
  "cardinality": "one",
  "readOnly": false
}'

Response (200 OK)

Create an attribute definition with a format

In this example, we're creating an attribute definition and prodivding a format in order to validate the value.

Request

curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/attribute-definitions" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "type": "string",
  "key": "countryCode",
  "displayName": "countryCode", 
  "description": "Country code",
  "pii": false,
  "cardinality": "one",
  "readOnly": false
  "format": {
    "type": "select",
    "select": {
      "options": [
        {
          "label": "US",
          "value": "US"
        },
        {
          "label": "BR", 
          "value": "BR"
        }
      ]
    }
  }
}'

Response (200 OK)