AccountsPOST

Create account

Creates a provider account. Supported provider names include telegram, whatsapp, twitter, line, and zalo. Use the auth_mode that matches the account connection flow. When the chosen provider plus auth_mode pairs require a phone number (for example WhatsApp with auth_mode=code), the number must be supplied here through provider_data.phone — it is persisted on the account and automatically replayed for subsequent 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

stringrequired

Human-readable account name.

provider

stringrequired

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

region

stringrequired

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

auth_mode

string

Authentication flow: code, qrcode, or session.

provider_data

object

Provider-specific configuration. Keep secret values out of logs.

metadata

object

Platform-side metadata for environment labels.

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, or zalo.

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.

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.

provider_account_ref

string

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

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.

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