Accounts

API reference descriptions are provided in English to preserve the exact published contract.

Get the authenticated account

GET /v1/accounts/{AC}

getV1AccountsByAc200

Required scope: `accounts:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Update the authenticated account

PATCH /v1/accounts/{AC}

patchV1AccountsByAcIdempotency-Key required200

Required scope: `accounts:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (6 fields)

Request body
Name	Type	Required	Description
`autoReadReceipts`	boolean
`consentPolicy`	"STRICT" \| "STANDARD"
`displayName`	string (max 128 chars)
`homeRegion`	string (pattern ^[a-z0-9][a-z0-9-]*$, max 64 chars)
`reason`	string (max 2000 chars)	yes
`timezone`	string (max 64 chars) \| null		IANA time zone the account schedules in (for example Africa/Lagos). null returns to the zone of the organization's country.

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List API date versions and the account default

GET /v1/accounts/{AC}/api-versions

getV1AccountsByAcApiVersions200

The version registry: known dates, their status and their end-of-support dates, together with this account's default and the version this request resolved to. Required scope: `accounts:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Set the account default API version

PATCH /v1/accounts/{AC}/api-versions/default

patchV1AccountsByAcApiVersionsDefaultIdempotency-Key required200

: the per-account default a request without `ShipMessages-Version` resolves to. `null` restores the platform default. A sunset or unknown date is refused. Required scope: any one of `accounts:write`, `api_keys:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (1 fields)

Request body
Name	Type	Required	Description
`version`	string (pattern ^\d{4}-\d{2}-\d{2}$) \| null	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Irreversibly close the authenticated account

POST /v1/accounts/{AC}/close

postV1AccountsByAcCloseIdempotency-Key required202

Required scope: `organization:delete`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (4 fields)

Request body
Name	Type	Required
`caseRef`	string (max 128 chars)	yes
`confirmation`	string (max 28 chars)	yes
`reason`	string (max 2000 chars)	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Get the owning organization

GET /v1/accounts/{AC}/organization

getV1AccountsByAcOrganizationPaginated200

Required scope: `users:read`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Update the owning organization

PATCH /v1/accounts/{AC}/organization

patchV1AccountsByAcOrganizationIdempotency-Key required200

Required scope: `accounts:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (5 fields)

Request body
Name	Type	Required
`country`	string (pattern ^[A-Z]{2}$)
`defaultCurrency`	string (pattern ^[A-Z]{3}$)
`displayName`	string (max 128 chars)
`legalName`	string (max 200 chars)
`reason`	string (max 2000 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List organization accounts

GET /v1/accounts/{AC}/organization/accounts

getV1AccountsByAcOrganizationAccountsPaginated200

Required scope: `accounts:read`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Create an account in the organization

POST /v1/accounts/{AC}/organization/accounts

postV1AccountsByAcOrganizationAccountsIdempotency-Key required201

Required scope: `organization:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (3 fields)

Request body
Name	Type	Required
`displayName`	string (max 128 chars)	yes
`homeRegion`	string (pattern ^[a-z0-9][a-z0-9-]*$, max 64 chars)	yes
`reason`	string (max 2000 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Irreversibly close the organization

POST /v1/accounts/{AC}/organization/close

postV1AccountsByAcOrganizationCloseIdempotency-Key required202

Required scope: `organization:delete`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (4 fields)

Request body
Name	Type	Required
`caseRef`	string (max 128 chars)	yes
`confirmation`	string (max 28 chars)	yes
`reason`	string (max 2000 chars)	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Read customer key custody configuration and verification state

GET /v1/accounts/{AC}/security/customer-kms

getV1AccountsByAcSecurityCustomerKms200

Required scope: `accounts:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Configure approved customer OpenBao Transit custody

POST /v1/accounts/{AC}/security/customer-kms

postV1AccountsByAcSecurityCustomerKmsIdempotency-Key required200

Required scope: `accounts:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (7 fields)

Request body
Name	Type	Required
`address`	string (max 500 chars)	yes
`approvalSid`	string (AP… SID)	yes
`mount`	string (max 128 chars)	yes
`namespace`	string (max 128 chars)
`provider`	"CUSTOMER_OPENBAO_TRANSIT"	yes
`stepUpToken`	string (max 256 chars)	yes
`tokenSecretRef`	string (max 500 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Activate approved customer key custody after verification

POST /v1/accounts/{AC}/security/customer-kms/activate

postV1AccountsByAcSecurityCustomerKmsActivateIdempotency-Key required200

Required scope: `accounts:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (2 fields)

Request body
Name	Type	Required	Description
`approvalSid`	string (AP… SID)	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Start approved customer key custody rotation

POST /v1/accounts/{AC}/security/customer-kms/start

postV1AccountsByAcSecurityCustomerKmsStartIdempotency-Key required200

Required scope: `accounts:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (2 fields)

Request body
Name	Type	Required	Description
`approvalSid`	string (AP… SID)	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Show the account data encryption key version and its last rotation

GET /v1/accounts/{AC}/security/keys

getV1AccountsByAcSecurityKeys200

Required scope: `audit:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Rotate the account data encryption key (new Transit key version)

POST /v1/accounts/{AC}/security/keys/rotate

postV1AccountsByAcSecurityKeysRotateIdempotency-Key required200

Required scope: `accounts:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (4 fields)

Request body
Name	Type	Required
`approvalSid`	string (AP… SID)	yes
`caseRef`	string (max 128 chars)
`reason`	string (max 2000 chars)	yes
`stepUpToken`	string (max 256 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

List subaccounts

GET /v1/accounts/{AC}/subaccounts

getV1AccountsByAcSubaccountsPaginated200

Required scope: `accounts:read`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)
`AC`	path · string (AC… SID)	yes	Account SID

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Create a subaccount

POST /v1/accounts/{AC}/subaccounts

postV1AccountsByAcSubaccountsIdempotency-Key required201

Required scope: `accounts:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID

Request body (1 fields)

Request body
Name	Type	Required	Description
`displayName`	string (max 128 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Get a subaccount

GET /v1/accounts/{AC}/subaccounts/{SA}

getV1AccountsByAcSubaccountsBySa200

Required scope: `accounts:read`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`SA`	path · string (SA… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Update a subaccount

PATCH /v1/accounts/{AC}/subaccounts/{SA}

patchV1AccountsByAcSubaccountsBySaIdempotency-Key required200

Required scope: `accounts:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`SA`	path · string (SA… SID)	yes

Request body (1 fields)

Request body
Name	Type	Required	Description
`displayName`	string (max 128 chars)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Close an empty subaccount

DELETE /v1/accounts/{AC}/subaccounts/{SA}

deleteV1AccountsByAcSubaccountsBySa200

Required scope: `accounts:write`.

Parameters

Parameters
Name	Type	Required	Description
`AC`	path · string (AC… SID)	yes	Account SID
`SA`	path · string (SA… SID)	yes

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Public API changelog feed

GET /v1/changelog

getV1ChangelogPaginatedNo key needed200

Every known API date version with its release, deprecation and end-of-support dates, newest first. The same entries are published as RSS 2.0 at `/v1/changelog.rss`.

Parameters

Parameters
Name	Type	Required	Description
`limit`	query · integer (1–100)
`cursor`	query · string (max 2048 chars)

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.

Public API changelog feed as RSS 2.0

GET /v1/changelog.rss

getV1ChangelogRssNo key needed200

Errors: 400, 401, 403, 404, 409, 422, 429, 500, 503 — see errors.