Create attribute definition
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.
Your workspace identifier.
b4e02c85-c6d2-4b15-8885-e09671799c61
A user-specified key, primarily for client reference.
countryCode
Pattern: ^[A-Za-z\d_-]{1,64}$
A human-readable name of the attribute.
Country Code
A user-friendly description of the attribute.
The country code of the contact
The cardinality configures how many values belong to the single key.
A flag to indicate whether this attribute is considered personally identifiable information.
false
A flag to indicate whether this attribute may be updated after creation.
false
The attribute definition was created successfully.
The workspace was not found.
The HTTP could not be completed because of a conflict with the current state of the resource.
The HTTP request is well-formed but was unable to be processed. The HTTP response should include details about the error.
POST /workspaces/{workspaceId}/attribute-definitions HTTP/1.1
Host: api.bird.com
Authorization: Bearer JWT
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": "2025-08-22T18:19:36.732Z",
"updatedAt": "2025-08-22T18:19:36.732Z",
"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.
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
}'
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.
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"
}
]
}
}
}'
Last updated
Was this helpful?