Retrieve a provisioned account
Scopeaccounts:readReturns one account you provisioned, with the same shape the list returns: its lifecycle status, the access_level you hold, the state of its claim link and its company_id when the account holds exactly one company.
Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key
short of the scope an operation needs is answered 403. The scope an operation requires
is shown next to its title, and the full catalogue lives in the Scopes reference.
Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.
In: header
Path Parameters
Identifier (UUID) of an account you provisioned. An account you did not provision answers exactly like one that does not exist, so its existence is never disclosed.
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://app.beel.es/api/v1/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08"{
"success": true,
"data": {
"account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
"external_ref": "string",
"display_name": "string",
"access_level": "NONE",
"status": "PROVISIONED",
"claim": {
"status": "NOT_ISSUED",
"expires_at": "2019-08-24T14:15:22Z"
},
"company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf",
"representation_signed": true,
"created_at": "2019-08-24T14:15:22Z"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication is required to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "PROVISIONING_ACCOUNT_NOT_ACCESSIBLE",
"message": "That account is not managed by your organisation."
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please try again in 60 seconds."
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type: text/plain. Supported: application/json"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}List the accounts you provisioned GET
Returns the accounts you provisioned, newest first. Each carries its lifecycle `status` (`PROVISIONED` → `CLAIMED` → `ACTIVE`), the `access_level` you hold over it and the state of its claim link. - **`status`:** narrows the list to one lifecycle stage. - **`external_ref`:** looks an account up by the reference you assigned when provisioning it; returns the 0..1 matching accounts. **Cursor pagination.** This collection pages by `cursor`/`next_cursor` instead of by `page`, so it carries no `pagination` block. That is a documented variant of pagination, not a different envelope: the collection still travels under a named key inside `data`. Keep asking with the `next_cursor` of the previous response until it comes back `null`.
Get your provisioning usage GET
Returns how many accounts you have provisioned and the billable count that follows from them — the figure behind your offline B2B invoice. - **Billable unit:** the provisioned account, not the real NIF. Every account you provision counts as one, empty and unclaimed ones included. - **`account_id`:** your own account. Usage is a property of the provisioner, not of each provisioned account, so any other id returns `404`. - **Entitlement:** requires `manage_accounts`.