AuthenticationPOST

Start code authentication

Starts a verification-code login flow. After this call, submit the provider code through /auth/code. If two-factor auth is required, continue with /auth/password. WhatsApp uses this same endpoint for phone-number pairing — the phone number is read from the account (saved at creation through provider_data.phone) and does not need to be supplied here.

https://api.unifyport.ai/v1/accounts/{account_id}/auth/start

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

Request body

This endpoint does not require a JSON request body.

Response body

account_id

string

Provider account this response refers to.

status

string

Current authentication flow state, such as awaiting_code, awaiting_qr_scan, authorized, or cancelled.

auth_fields

object[]

Describes what the next step requires — each entry carries a type and whether it is required.

auth_payload

object

Material the client needs to render the next step, such as qr_code or verify_code.

expires_at

string

RFC3339 timestamp after which the current auth_payload is no longer valid.

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.

Request

curl -X POST https://api.unifyport.ai/v1/accounts/{account_id}/auth/start \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "data": {
    "account_id": "acc_example",
    "status": "awaiting_code",
    "auth_fields": [
      { "type": "code", "required": true }
    ],
    "auth_payload": {
      "verify_code": "ABCD-EFGH"
    },
    "expires_at": "2026-01-01T00:00:00Z"
  }
}