Accounts

List accounts

Lists provider accounts in the current workspace. Account auth state is exposed through the Authentication endpoints.

GEThttps://api.unifyport.ai/v1/accounts

Before you call

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

Request parameters

Headers

X-Api-Key

stringrequired

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

Query parameters

limit

integer

Maximum accounts per page, from 1 to 100; defaults to 20 when omitted. Invalid values or repeated limit parameters return 400 invalid_request (numeric_code=10000). The value may change on subsequent pages.

minimum: 1 · maximum: 100

cursor

string

Opaque account-list cursor. Omit or pass an empty string for the first page; pass the previous data.next_cursor unchanged for subsequent pages. Valid only for the workspace where it was issued. Invalid, repeated, or cross-workspace cursor parameters return 400 invalid_request (numeric_code=10000).

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": "acc_example",
        "name": "Telegram Production",
        "provider": "telegram",
        "region": "global",
        "status": "active",
        "runtime_status": "running",
        "auth_mode": "qrcode",
        "capabilities": [
          "send_message",
          "receive_message"
        ],
        "metadata": {
          "env": "production"
        },
        "provider_account_ref": "provider-side-identifier",
        "provider_profile": {
          "id": "778899",
          "phone": "8600000000000",
          "username": "production_bot",
          "display_name": "Production Bot",
          "first_name": "Production",
          "last_name": "Bot",
          "avatar_url": "https://example.com/avatar.jpg",
          "bio": "Customer support"
        }
      }
    ],
    "has_more": false
  }
}

Response body

id

string

Unique account identifier (acc_...). Use it in account-scoped routes.

name

string

Human-readable account name.

provider

string

Channel identifier. Use the API value unchanged in later calls; see the enum below for the values returned by this endpoint.

enum: telegram, whatsapp, line, twitter, zalo, tiktok, whatsapp-protocol

region

string

Provider region the account is allocated to.

status

string

Account lifecycle state, such as active.

runtime_status

string

Normalized runtime state: one of unknown, starting, running, stopping, stopped, reconnecting, disconnected, or error.

enum: unknown, starting, running, stopping, stopped, reconnecting, disconnected, error

auth_mode

string

Authentication flow used by the account: code, qrcode, or session.

capabilities[]

string[]

Capabilities enabled for the account, such as send_message and receive_message.

metadata

object

Your own environment labels stored on the account.

provider_account_ref

string

Channel-side identifier you can attach to correlate the account with your own system.

proxy

object

Outbound proxy configuration attached to the account, when configured.

provider_profile

object

Channel-reported profile such as display_name. Omitted before the account is authenticated.

id

string

Channel-side account identity. WhatsApp returns an LID; it may be omitted before profile synchronization completes.

phone

string

Normalized account phone number with spaces, hyphens, and the leading plus sign removed.

username

string

Provider-reported username, when available.

display_name

string

Account display name; for WhatsApp this is generated by preferring BusinessName and falling back to PushName.

push_name

string

PushName currently set on the WhatsApp account; other providers do not define semantics for this field.

business_name

string

WhatsApp BusinessName; omitted when the provider does not return one.

first_name

string

Provider-reported first name, when available.

last_name

string

Provider-reported last name, when available.

avatar_url

string

Provider-reported account avatar URL, when available.

bio

string

Provider-reported account biography or status text, when available.

platform

string

Login platform identifier reported by WhatsApp during pairing. Treat it as an opaque string and accept unknown values; other providers do not define this field. It is distinct from device_platform.

has_more

boolean

Whether the account list has another page.

next_cursor

string

Opaque cursor for the next account-list page, returned only when has_more=true. Pass it unchanged as cursor for the next page; omitted on the last 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.

500

Internal Server Error

The service encountered an unexpected error.

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.