Accounts

Get account

Returns one account configuration. Sensitive provider credentials carried in provider_data are deliberately omitted from this response. Authentication state — including pending QR codes and verification codes — is exposed separately through the Authentication endpoints.

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

Supported channels

all

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 accounts route.

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": {
    "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"
    }
  }
}

Response body

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.

device_id

integer

Login device number, optionally returned in WhatsApp account details when the current session can be identified. It may change after reauthorization and is not a permanent device identifier.

minimum: 0 · maximum: 65535

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.

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.

Responses

200

200 OK

Request succeeded. See the example response body.

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.