Skip to main content

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.

Omit password and the new agent is emailed a one-time link to set their own — the right choice for a real person. Supply one and the account works immediately, which suits a service account a machine will drive.

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.

Request​

Responses​

Agent created.

Response Headers
    X-Request-Id

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