דילוג לתוכן הראשי

Create a human agent

POST 
/agents

Create a human agent.

⚠️ This may charge the card on file. An agent occupies a seat; if the plan has none free, a prorated charge is taken for the rest of the billing period, exactly as in the console. Two consequences to design around:

  • A 402 with code: seat_charge_failed means the card was declined and nothing was created — the agent is rolled back before the response is written, so a retry is safe.
  • A 201 may carry a seat_charge object saying what was charged. Log it: "why did my invoice go up" is a question an automated provisioning integration will eventually have to answer.

The new agent is always emailed a one-time link to choose their own password — the same flow the console uses. password is not accepted and a request carrying it is refused with 400: credentials never travel in an API request, and the account only becomes usable from the new agent's own mailbox.

role_id comes from GET /v1/roles. Omitted, the account's default Agent role is applied, which is a working least-privilege role rather than no permissions. Any of the account's roles may be assigned, Owner included — granting a key the agents_teams scope means trusting it with exactly that decision.

Request​

Responses​

Agent created.

Response Headers
    X-Request-Id

    Correlation id for this request. Quote it when reporting a problem.