Labels
The label object
Attributes
idstringrequiredIdentifier for this resource.
namestringrequiredHuman-readable name for this resource.
colorintegerrequiredSpecifies color for this native label.
orderIndexintegerSpecifies order index for this native label.
chatCountintegerNumber of chats.
observedAtstring (date-time)ISO 8601 timestamp when Polymorfa observed this state.
{
"id": "string",
"name": "string",
"color": 0,
"orderIndex": 0,
"chatCount": 0,
"observedAt": "2026-09-22T12:00:00Z"
}Create label
- Base URL
https://api.polymorfa.com- Required permission
labels:manage
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
Body
namestringrequiredlength1–100Human-readable name for this resource.
colorintegerrange0–19Specifies color for this native create label request.
Responses
200Label created
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 6 child fields
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
curl -X POST "https://api.polymorfa.com/messaging/<session>/labels" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"name": "string"
}'{
"success": true,
"data": {
"id": "string",
"name": "string",
"color": 0
}
}List labels
- Base URL
https://api.polymorfa.com- Required permission
labels:read
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
Query parameters
includeObservationstringSpecifies include observation for this query parameter.
Allowed valuestruefalse
Responses
200Label list
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataarray or objectrequiredStructured data carried by this object.
One ofidstringrequiredIdentifier for this resource.
namestringrequiredHuman-readable name for this resource.
colorintegerrequiredSpecifies color for this native label.
orderIndexintegerSpecifies order index for this native label.
chatCountintegerNumber of chats.
observedAtstring (date-time)ISO 8601 timestamp when Polymorfa observed this state.
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
curl "https://api.polymorfa.com/messaging/<session>/labels" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"data": [
{
"id": "string",
"name": "string",
"color": 0
}
]
}Get chat labels
- Base URL
https://api.polymorfa.com- Required permission
labels:read
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
conversationstringrequiredPublic conversation identifier or E.164 phone number.
Query parameters
includeObservationstringSpecifies include observation for this query parameter.
Allowed valuestruefalse
Responses
200Chat labels
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataarray or objectrequiredStructured data carried by this object.
One ofidstringrequiredIdentifier for this resource.
namestringrequiredHuman-readable name for this resource.
colorintegerrequiredSpecifies color for this native label.
orderIndexintegerSpecifies order index for this native label.
chatCountintegerNumber of chats.
observedAtstring (date-time)ISO 8601 timestamp when Polymorfa observed this state.
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
curl "https://api.polymorfa.com/messaging/<session>/labels/chats/<conversation>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true,
"data": [
{
"id": "string",
"name": "string",
"color": 0
}
]
}Update label
- Base URL
https://api.polymorfa.com- Required permission
labels:manage
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
labelIdstringrequiredIdentifier for the label.
Body
namestringlength1–100Human-readable name for this resource.
colorintegerrange0–19Specifies color for this native update label request.
Responses
200Label updated
successbooleanrequiredWhether the request succeeded.
messagestringHuman-readable message associated with this result.
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
409The session has no authoritative view of its labels yet. Retry once a cached or project-retained snapshot is complete.
500Internal server error
curl -X PUT "https://api.polymorfa.com/messaging/<session>/labels/<labelId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"color": 0
}'{
"success": true
}Set chat labels
- Base URL
https://api.polymorfa.com- Required permission
labels:manage
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
conversationstringrequiredPublic conversation identifier or E.164 phone number.
Body
labelsarray of stringrequiredmax items20item length1–128Labels associated with this resource.
Responses
200Chat labels updated
successbooleanrequiredWhether the request succeeded.
messagestringHuman-readable message associated with this result.
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
409The session has no authoritative view of its labels yet. Retry once a cached or project-retained snapshot is complete.
500Internal server error
curl -X PUT "https://api.polymorfa.com/messaging/<session>/labels/chats/<conversation>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"labels": [
"string"
]
}'{
"success": true
}Delete label
- Base URL
https://api.polymorfa.com- Required permission
labels:manage
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
labelIdstringrequiredIdentifier for the label.
Responses
200Label deleted
successbooleanrequiredWhether the request succeeded.
messagestringHuman-readable message associated with this result.
Show 3 headers
400Bad request — request body or params failed validation
401Missing or invalid authentication token
403Authenticated but not permitted (missing scope or rule violation)
404Resource not found
500Internal server error
curl -X DELETE "https://api.polymorfa.com/messaging/<session>/labels/<labelId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true
}