Skip to content
DashboardGet API key

Create sub-account

View .md
POST

Create a new sub-account (project) with its own API key. All charges are billed to the parent team's balance. Use creditLimit to set a spending cap. The sub-account's API key is returned only in the creation response. Requires a parent project API key; sub-account API keys receive HTTP 403.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json

  • namestringrequired

    Name of the sub-account.

    Limitsmax length 200
  • externalIdstring

    External reference ID for your own tracking.

  • creditLimitinteger

    Spending cap in cents. When reached, messages from this sub-account will be blocked. Omit or set to 0 for no limit.

    Limitsmin 0
  • metadataobject

Responses

201Sub-account created.
  • subAccountobjectrequired
    9 properties
    • idstringrequired
    • namestringrequired
    • externalIdstringnullable

      External reference ID set by the parent account.

    • statusstringrequired

      active and inactive are set with PATCH. pending_deletion is read-only: the sub-account was deactivated with DELETE, its API keys are revoked, and it is removed after 14 days.

      One ofactiveinactivepending_deletion
    • totalSpentintegerrequired

      Total amount spent by this sub-account in cents.

    • creditLimitintegernullable

      Spending cap in cents. When reached, messages from this sub-account will be blocked.

    • metadataobjectnullable
    • apiKeystring

      API key for the sub-account. Only returned on creation.

    • createdAtstring<date-time>required
400Invalid request.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
403Forbidden. Sub-account API keys cannot manage sub-accounts.
  • codestringrequired
  • messagestringrequired
  • detailsobject
409A sub-account with this `externalId` already exists in the team.
  • codestringrequired
  • messagestringrequired
  • detailsobject