List the accounts you provisioned, with lifecycle status
Scopeaccounts:readReturns the accounts you provisioned, each with its lifecycle status (PROVISIONED → CLAIMED → ACTIVE) and the access you hold. Newest first, cursor-paginated. Filter by status, or look one up by external_ref (your own id) — an external_ref that matches nothing returns an empty list, never an error. Requires the accounts:read scope.
API Key authentication.
Format: Authorization: Bearer beel_sk_<key>
Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with
specific scopes that limit which endpoints it can access. The required scope for each
endpoint is documented in the operation's security section under OAuth2.
Obtaining Keys: API Keys are managed from the BeeL dashboard
Security: API Keys are secret credentials. Do not share them or store them in source code
In: header
Query Parameters
Lifecycle stage of a provisioned account. The claim gates the stage: PROVISIONED (created, not yet claimed — the holder has not set a password / taken ownership, even if a NIF was seeded at provisioning or you invoice on their behalf with OPERATE); CLAIMED (the holder set their password and took ownership, no NIF yet); ACTIVE (claimed and has at least one NIF — can operate under their own ownership).
"PROVISIONED" | "CLAIMED" | "ACTIVE"Your own id for the account; returns the 0..1 matching accounts.
Maximum number of accounts to return per page (1–200). Defaults to 50.
501 <= value <= 200Opaque pagination cursor from a previous response's next_cursor.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://app.beel.es/api/v1/accounts"{
"success": true,
"data": {
"accounts": [
{
"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"
}
],
"next_cursor": "string"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "You do not have permission to access this resource"
},
"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"
}
}Import managed accounts from a file POST
Provisions the managed accounts described in an uploaded file, switches each one on in Live, and leaves them ready to invoice. It is the same act as calling `POST /v1/accounts` once per row and then `POST /v1/companies/{company_id}/activations`, with the bookkeeping done for you. **The file is declarative and the import is re-runnable.** Each pass applies only what is missing: an `external_ref` you already provisioned is reconciled, not duplicated, and so are its series and its customers. That is the recovery path for anything that went wrong — fix the cause and upload the same file again. There is no resume and no partial state to clean up. **Two files, one act.** `accounts_file` describes the accounts, one per row. `customers_file` is optional and holds a list of customers applied to **every** account of the import, new and pre-existing alike. It is what makes both directions cheap: a new managed account is born knowing all the customers, and a new customer reaches all the accounts on the next pass. It is the same CSV that `GET /v1/templates/customer-import` describes, and it is idempotent by tax id. **Live activation is part of the act, and it never charges you by surprise.** Every row is weighed against the same verdict the account state publishes, and **only rows entitled to Live are executed**; the rest come back `BLOCKED` with the reason. The import never opens a checkout: chaining N payments inside a file upload would turn a declarative import into a payment flow with intermediate states nobody can recover from. Settle your billing once and re-upload. **Not atomic.** Each row is processed and reported independently: a row that fails leaves the rows already provisioned in place. Read `statistics.accounts_created` to know how many accounts this call actually created. **Claim tokens are shown once.** Each newly provisioned row carries `account.claim_token` and `account.claim_url` in this response and nowhere else. Persist them before discarding the response; a lost token is re-issued with `POST /v1/accounts/{account_id}/claim-tokens`. **Limits:** 5 MB per file; 100 rows in the accounts file and 1,000 in the customers file. The accounts cap is far below the customers one because an account row is an order of magnitude heavier — a provision, a census lookup, a Live activation, its series and its customers — and the answer is synchronous. A larger population is imported in passes, which costs nothing: the file is declarative. **Idempotency:** `Idempotency-Key` is required. The real guarantee, though, is in the data: rows are idempotent by `external_ref`, so the same file uploaded twice creates nothing twice even under a different key. To see what this would do without writing anything, use `POST /v1/accounts/imports/preview`, a separate operation with no effects at all — the import is never governed by a boolean flag. Requires the `accounts:write` scope and the managed-accounts capability on your account.
Get a provisioned account's authoritative status GET
Returns the current lifecycle status and access for one account you provisioned. A `403` is returned when the account was not provisioned by you or does not exist (existence is not disclosed). Requires the `accounts:read` scope.