API Reference

Accounts

Update account

Partially updates account metadata and provider configuration. Omitted fields, including provider and region, retain their values; null is invalid; empty arrays or objects clear collection and object fields. A duplicate provider identity returns 409 duplicate_provider_account.

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

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.

Content-Type
stringrequired

Use application/json when sending a JSON request body.

Path parameters

account_id
stringrequired

Identifier used in the accounts route.

Request body

name
string

Human-readable account name.

provider
string

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

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

region
string

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
string

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. When creating a Telegram account, api_id and api_hash are optional. If no custom app credentials are provided, the platform uses its default app credentials. To use your own app, provide both fields as strings from the same Telegram app.

proxy
object

Optional outbound proxy configuration for this account.

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",
    "status": "active",
    "auth_mode": "code"
  }
}

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.

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.

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.