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

Contacts

View as Markdown

The contact object

Attributes

  • idstringrequiredpattern^[1-9][0-9]{0,18}$

    Opaque Polymorfa resource ID. Keep this value as a string.

  • phoneNumberstring

    Phone number in international format.

  • bsuidstring

    Business-scoped user identifier (BSUID), scoped to the owning business portfolio.

  • usernamestring

    WhatsApp username when one is available.

  • namestringrequired

    Human-readable name for this resource.

  • pushNamestringrequired

    WhatsApp display name reported by the sender's client.

  • businessNamestring

    Business name shown to the customer.

  • profileUrlstring

    URL for the profile.

The contact object
{
  "id": "739182640518203",
  "phoneNumber": "string",
  "bsuid": "string",
  "username": "string",
  "name": "string",
  "pushName": "string",
  "businessName": "string",
  "profileUrl": "string"
}

List contacts

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

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Responses

  • 200Contact list
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 8 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
GET /messaging/{session}/contactscURL
curl "https://api.polymorfa.com/messaging/<session>/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": [
    {
      "id": "739182640518203",
      "name": "string",
      "pushName": "string"
    }
  ]
}

Get blocklist

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

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Responses

  • 200Blocked contacts
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

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

Get contact

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

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • contactIdstringrequiredpattern^[1-9][0-9]{0,18}$

    Identifier for the contact.

Responses

  • 200Contact details
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 8 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
GET /messaging/{session}/contacts/{contactId}cURL
curl "https://api.polymorfa.com/messaging/<session>/contacts/<contactId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "id": "739182640518203",
    "name": "string",
    "pushName": "string"
  }
}

Get contact picture

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

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • contactIdstringrequiredpattern^[1-9][0-9]{0,18}$

    Identifier for the contact.

Responses

  • 200Profile picture URL
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 1 child field
    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}/contacts/{contactId}/picturecURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/contacts/<contactId>/picture" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "url": "string"
  }
}

Get user info

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

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • contactIdstringrequiredpattern^[1-9][0-9]{0,18}$

    Identifier for the contact.

Responses

  • 200User metadata
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 8 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
GET /messaging/{session}/contacts/{contactId}/infocURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/contacts/<contactId>/info" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "id": "739182640518203",
    "status": "string",
    "pictureId": "string",
    "verifiedName": "string",
    "devices": [
      {
        "id": "739182640518203",
        "device": 0
      }
    ]
  }
}

Get user devices

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

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • contactIdstringrequiredpattern^[1-9][0-9]{0,18}$

    Identifier for the contact.

Responses

  • 200Linked devices
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 3 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
GET /messaging/{session}/contacts/{contactId}/devicescURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/contacts/<contactId>/devices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": [
    {
      "device": 0
    }
  ]
}

Get business profile

GET/messaging/{session}/contacts/{contactId}/business-profileMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
contacts:read

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • contactIdstringrequiredpattern^[1-9][0-9]{0,18}$

    Identifier for the contact.

Responses

  • 200Business profile
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 14 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
GET /messaging/{session}/contacts/{contactId}/business-profilecURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/contacts/<contactId>/business-profile" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "id": "739182640518203",
    "address": "string",
    "email": "string",
    "description": "string",
    "websites": [
      "https://example.com"
    ],
    "coverPhotoId": "string",
    "categories": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "options": {},
    "hoursTimeZone": "string",
    "hours": [
      {
        "dayOfWeek": "string",
        "mode": "string",
        "openTime": "string",
        "closeTime": "string"
      }
    ]
  }
}

Check contacts

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

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Query parameters

  • phonestring or arrayrequired

    Phone number in international format.

    Accepts one of
    • string

    • array, max items 1000

Responses

  • 200Contact check results
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 5 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
GET /messaging/{session}/contacts/checkcURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/contacts/check?phone=<phone>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": [
    {
      "exists": true
    }
  ]
}

Block contact

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

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • contactIdstringrequiredpattern^[1-9][0-9]{0,18}$

    Identifier for the contact.

Responses

  • 200Contact blocked
    • 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
POST /messaging/{session}/contacts/{contactId}/blockcURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/messaging/<session>/contacts/<contactId>/block" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true
}

Unblock contact

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

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • contactIdstringrequiredpattern^[1-9][0-9]{0,18}$

    Identifier for the contact.

Responses

  • 200Contact unblocked
    • 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
POST /messaging/{session}/contacts/{contactId}/unblockcURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/messaging/<session>/contacts/<contactId>/unblock" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true
}