AccountsPOST

Create account

Creates a provider account. auth_mode is required and must be qrcode, code, or session. When a provider/auth_mode pair requires a phone number (for example WhatsApp with auth_mode=code), supply provider_data.phone here; it is persisted and replayed for later authentication actions.

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

Headers

X-Api-Key

stringrequired

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

Content-Type

stringrequired

Use application/json when sending a JSON request body.

Path parameters

This endpoint has no path parameters.

Request body

name

string

Human-readable account name.

provider

stringrequired

Customer provider identifier: telegram, whatsapp, line, twitter, zalo, or tiktok.

enum: telegram, whatsapp, line, twitter, zalo, tiktok, x, x_client, twitter_client

region

stringrequired

Provider region used for allocation. Pick a region reported as allocatable: true by List provider regions.

minLength: 1

status

string

Account business state, such as active or inactive.

runtime_status

string

Requested runtime state when the provider supports changing it through account configuration.

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

auth_mode

stringrequired

Required when creating an account. Authentication flow: qrcode, code, or session.

enum: qrcode, code, session

capabilities[]

string[]

Capabilities enabled for this account. On PATCH, omit to retain or send [] to clear; null is invalid.

metadata

object

Platform-side metadata. On PATCH, omit to retain or send {} to clear; null is invalid.

provider_account_ref

string

Channel-side account identity, normally populated after authorization.

provider_data

object

Provider-specific configuration. On PATCH, omit to retain or send {} to clear; null is invalid. Keep secret values out of logs.

proxy

object

Optional outbound proxy configuration for this account.

Response body

id

string

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

name

string

Human-readable account name.

provider

string

Provider identifier such as telegram, whatsapp, line, twitter, zalo, or tiktok.

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

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

Provider-reported display name, when available.

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.

Responses

201

201 Created

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.

503

Service Unavailable

A required backend service is temporarily unavailable.

Request

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Telegram Production",
  "provider": "telegram",
  "region": "global",
  "status": "active",
  "auth_mode": "qrcode",
  "capabilities": ["send_message", "receive_message"],
  "provider_data": {},
  "metadata": {
    "env": "production"
  },
  "provider_account_ref": "provider-side-identifier"
}'

Response

{
  "data": {
    "id": "acc_example",
    "name": "Telegram Production",
    "provider": "telegram",
    "region": "global",
    "status": "active",
    "runtime_status": "stopped",
    "auth_mode": "qrcode",
    "capabilities": ["send_message", "receive_message"],
    "provider_account_ref": "provider-side-identifier"
  }
}