Skip to content
Shortcut: /, ⌘K or Ctrl+K

Labels

View as Markdown

The label object

Attributes

  • idstringrequired

    Identifier for this resource.

  • namestringrequired

    Human-readable name for this resource.

  • colorintegerrequired

    Specifies color for this native label.

  • orderIndexinteger

    Specifies order index for this native label.

  • chatCountinteger

    Number of chats.

  • observedAtstring (date-time)

    ISO 8601 timestamp when Polymorfa observed this state.

The label object
{
  "id": "string",
  "name": "string",
  "color": 0,
  "orderIndex": 0,
  "chatCount": 0,
  "observedAt": "2026-09-22T12:00:00Z"
}

Create label

POST/messaging/{session}/labelsMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
labels:manage

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Body

  • namestringrequiredlength1–100

    Human-readable name for this resource.

  • colorintegerrange0–19

    Specifies color for this native create label request.

Responses

  • 200Label created
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
POST /messaging/{session}/labelscURL
Not available with the Test key. Use a team key or project token.
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"
}'
Response
{
  "success": true,
  "data": {
    "id": "string",
    "name": "string",
    "color": 0
  }
}

List labels

GET/messaging/{session}/labelsMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
labels:read

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Query parameters

  • includeObservationstring

    Specifies include observation for this query parameter.

    Allowed valuestruefalse

Responses

  • 200Label list
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataarray or objectrequired

      Structured data carried by this object.

      One of
      • idstringrequired

        Identifier for this resource.

      • namestringrequired

        Human-readable name for this resource.

      • colorintegerrequired

        Specifies color for this native label.

      • orderIndexinteger

        Specifies order index for this native label.

      • chatCountinteger

        Number 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
GET /messaging/{session}/labelscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/labels" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": [
    {
      "id": "string",
      "name": "string",
      "color": 0
    }
  ]
}

Get chat labels

GET/messaging/{session}/labels/chats/{conversation}Messaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
labels:read

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • conversationstringrequired

    Public conversation identifier or E.164 phone number.

Query parameters

  • includeObservationstring

    Specifies include observation for this query parameter.

    Allowed valuestruefalse

Responses

  • 200Chat labels
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataarray or objectrequired

      Structured data carried by this object.

      One of
      • idstringrequired

        Identifier for this resource.

      • namestringrequired

        Human-readable name for this resource.

      • colorintegerrequired

        Specifies color for this native label.

      • orderIndexinteger

        Specifies order index for this native label.

      • chatCountinteger

        Number 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
GET /messaging/{session}/labels/chats/{conversation}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/labels/chats/<conversation>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": [
    {
      "id": "string",
      "name": "string",
      "color": 0
    }
  ]
}

Update label

PUT/messaging/{session}/labels/{labelId}Messaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
labels:manage

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • labelIdstringrequired

    Identifier for the label.

Body

  • namestringlength1–100

    Human-readable name for this resource.

  • colorintegerrange0–19

    Specifies color for this native update label request.

Responses

  • 200Label updated
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-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
PUT /messaging/{session}/labels/{labelId}cURL
Not available with the Test key. Use a team key or project token.
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
}'
Response
{
  "success": true
}

Set chat labels

PUT/messaging/{session}/labels/chats/{conversation}Messaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
labels:manage

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • conversationstringrequired

    Public conversation identifier or E.164 phone number.

Body

  • labelsarray of stringrequiredmax items20item length1–128

    Labels associated with this resource.

Responses

  • 200Chat labels updated
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-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
PUT /messaging/{session}/labels/chats/{conversation}cURL
Not available with the Test key. Use a team key or project token.
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"
  ]
}'
Response
{
  "success": true
}

Delete label

DELETE/messaging/{session}/labels/{labelId}Messaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
labels:manage

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • labelIdstringrequired

    Identifier for the label.

Responses

  • 200Label deleted
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-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
DELETE /messaging/{session}/labels/{labelId}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/messaging/<session>/labels/<labelId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true
}