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
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-06-22T18:49:30.781Z",
"updatedAt": "2025-06-22T18:49:30.781Z",
"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?