Contacts

List contacts

Lists contacts in real time. limit accepts 1..100 and defaults to 50. cursor is opaque; invalid or expired values may be handled differently by each provider. q matches display_name, phone, or username, and updated_since enables provider-supported incremental sync.

GEThttps://api.unifyport.ai/v1/accounts/{account_id}/contacts

Before you call

Use a server-side X-Api-Key for the workspace that owns the resource. Replace every placeholder before running a sample.

Prepare your parameters

account_id: Use data.id from account creation or an account query. Account identifiers belong to the workspace selected by X-Api-Key. Get account

Request parameters

Headers

X-Api-Key

stringrequired

Workspace API key. The workspace is resolved from this header.

Path parameters

account_id

stringrequired

Identifier used in the contacts route.

Query parameters

cursor

string

Opaque next_cursor from a previous response. Omit or leave empty for the first page; invalid or expired cursors are not handled uniformly across providers.

limit

integer

Page size from 1 to 100. Endpoint descriptions state the endpoint-specific default.

minimum: 1 · maximum: 100

q

string

Search filter matching display_name, phone, or username.

updated_since

string

RFC3339 timestamp; return only contacts updated since then, for incremental sync where the provider supports it.

format: date-time

Request body

This endpoint does not require a JSON request body.

Understand the result

Use the documented response fields and HTTP status. Successful 204 responses have no body; use X-Request-Id for diagnosis. Follow the related operations for the next step.

Response 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "items": [
      {
        "id": "user_example",
        "conversation_id": "peer_example",
        "display_name": "Alice",
        "avatar_url": "",
        "provider_user_id": "user_example",
        "extra": {
          "phone": "8600000000000"
        }
      }
    ],
    "next_cursor": "",
    "has_more": false
  }
}

Response body

id

string

Contact identifier.

conversation_id

string

Conversation identifier for this contact; use it to send messages or locate the chat.

display_name

string

Contact display name, or an empty string when missing.

avatar_url

string

Contact avatar URL, or an empty string when missing.

provider_user_id

string

Channel-side user identifier for the contact.

is_blocked

boolean

Whether the contact is blocked by the connected account.

extra

object

Provider-specific extra fields, such as phone.

phone

string

WhatsApp phone JID 中解析出的纯手机号。

first_name

string

当前账号通讯录中保存的联系人简称或名字部分。

full_name

string

当前账号通讯录中保存的完整联系人名称。

push_name

string

联系人自行在 WhatsApp 设置的个人名称。

business_name

string

WhatsApp Business 账号的商业或认证名称。

redacted_phone

string

Provider 仅返回部分号码时的遮蔽手机号。

next_cursor

string

Opaque cursor for the next page. Pass it back as cursor; an empty string means there are no more pages.

has_more

boolean

true when more results are available beyond this page.

Responses

200

200 OK

Request succeeded. See the example response body.

400

Bad Request

The request body, path, or parameters are invalid.

401

Unauthorized

The X-Api-Key header is missing or invalid.

409

Conflict

The requested operation conflicts with an existing provider account or resource.

500

Internal Server Error

The service encountered an unexpected error.

501

Not Implemented

The selected provider does not implement this operation.

502

Bad Gateway

The provider adapter or upstream provider could not complete the operation.

If the request fails

Inspect HTTP status and error.code/numeric_code, and keep request_id for diagnosis. Correct invalid parameters, complete required authorization or check runtime state as appropriate. Confirm the outcome before retrying a send or another write. Error reference

invalid_request · 10000 · 400: Check required fields, formats and channel conditions, then correct the request.
invalid_api_key · 11001 · 401: Check X-Api-Key and whether the workspace is active.