--- title: "Retrieve a provisioned account" method: GET path: "/v1/accounts/{account_id}" tags: ["Provisioning"] --- # Retrieve a provisioned account `GET /v1/accounts/{account_id}` ## Request - Base URL: `https://app.beel.es/api` - URL: `https://app.beel.es/api/v1/accounts/{account_id}` - Auth: HTTP bearer Returns 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. ## Path parameters - `account_id` string, uuid, required ## Response `200` The provisioned account. - object: The envelope every successful JSON response of the BeeL. API is wrapped in. There are no bare resources in v1 and none are planned: the payload always hangs off `data`. - A **single resource** is an object in `data`. - A **collection** hangs off a named key inside `data`, together with its `pagination`, also inside `data` — `data: {invoices: [...], pagination: {...}}`. - A collection carries `pagination` unless its operation declares itself a **closed catalogue**: a fixed, bounded list with nothing to page through. The declaration is explicit in the operation; a missing `pagination` is never something to infer. - `GET /v1/accounts` pages by cursor (`data: {accounts: [...], next_cursor}`). It is a documented variant of pagination, not another envelope. Putting the array straight into `data` with `pagination` as its sibling is the shape a v2 would adopt; v1 is not being flipped to it. - `success` boolean, required - `data` object, required: An account you provisioned, with its lifecycle status and the access you hold. - `account_id` string, uuid, required - `external_ref` string, required: The id you assigned to this account in your own system when provisioning it. - `display_name` string - `access_level` 'NONE' | 'VIEW' | 'OPERATE', required: How much access an actor has to an account or a company. The same three values are used everywhere access is granted or reported — whether the actor is a member of the account or a provisioner managing it on someone's behalf. `NONE` — no access to the data. `VIEW` — read invoices, customers, products, series and fiscal data. `OPERATE` — everything in `VIEW`, plus creating and editing them. Issuing invoices for an account you manage additionally requires a signed fiscal representation from the account holder (see `/v1/accounts/{account_id}/companies/{company_id}/representation`). Access level never affects billing: whoever provisioned an account pays for its subscription regardless of the level they keep over it. - `status` 'PROVISIONED' | 'CLAIMED' | 'ACTIVE', required: 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). - `claim` AccountClaim, required: Claim state of the account and, when there is a token to speak of, when it stops (or stopped) working. The token itself is **never** returned here: it is shown once, at the moment it is created (`POST /v1/accounts` or `POST /v1/accounts/{account_id}/claim-tokens`). A read that handed out live redemption links for a whole portfolio would be a needless prize; if the link was lost, issue a new one — doing so invalidates the previous. - `status` 'NOT_ISSUED' | 'PENDING' | 'EXPIRED' | 'CLAIMED', required: State of the account's claim link — the handover of the account to its holder. It answers the only question the manager has in front of a list: *can this person still take their account, or do I have to send them a new link?* `NOT_ISSUED` (no claim token was ever issued: the account was provisioned without `email` and has no holder yet); `PENDING` (a token is live — the holder can still claim); `EXPIRED` (the last token issued has lapsed, so the link in the holder's inbox no longer works); `CLAIMED` (the holder set their password and took ownership — nothing left to claim). `EXPIRED` and `NOT_ISSUED` are deliberately distinct: "it ran out" and "it was never sent" call for the same action but are not the same fact, and reporting one as the other would make the list lie. - `expires_at` string, date-time, nullable: When the last issued token stops (`PENDING`) or stopped (`EXPIRED`) working. Tokens last 30 days from issue. `null` for `NOT_ISSUED` and `CLAIMED`, where there is no expiry to report. - `company_id` string, uuid, nullable: The account's **single** company id (a UUID) — the value for the `BeeL-Active-Company` header when operating on this account. It is a **scalar, not a list**: it is present when the account holds exactly one company, and `null` otherwise (two or more, or none left). An account provisioned without `tax_profile` already holds one company, still without a NIF, so its id is returned; a company without a NIF does not make a claimed account `ACTIVE`. For a multi-NIF account, list them with `GET /v1/accounts/{account_id}/companies`. Same meaning as `company_id` in the response to `POST /v1/accounts`. - `representation_signed` boolean, required: Whether the account holder has signed at least one fiscal representation. - `created_at` string, date-time, required - `meta` ResponseMeta - `timestamp` string, date-time - `request_id` string ## Other responses - `401`: Missing or invalid authentication. Like every other error, `message`/`detail` is localized according to `Accept-Language` (`es`, `en`, `ca`); defaults to English when the header is missing or asks for none of those. - `403`: Every cause listed under the plain `403`, plus `PROVISIONING_ACCOUNT_NOT_ACCESSIBLE`: the account was not provisioned by you, its management ended, or it does not exist. The three are answered identically, so existence is never disclosed. - `429`: Rate limit exceeded. `RATE_LIMIT_EXCEEDED` when the request rate of your credential is over its limit; `TOO_MANY_REQUESTS` when an email the operation sends is held back because too many went out to that recipient in a short time. Either way, retry after the `Retry-After` seconds. `QUOTA_EXCEEDED` is the other `429`: the operation would go over a quota of your plan for the current period (issued invoices, for instance). Retrying does not help until the quota resets or the plan changes. `error.details` carries `feature_code`, `current_usage`, `quota_limit` and `reset_date`, and `RateLimit-Reset` the seconds until the reset when it is known. - `500`: Internal server error - `default`: Any status code the operation does not list above. Every operation declares it, so a generated client always has a branch to fall into and never loses the cause of a failure it did not anticipate. This is where the transport-level answers land — `405`, `406`, `415` and `429` — together with any status a future version of the API starts returning. All of them carry the same error envelope as the codes listed explicitly, so `error.code` is what tells them apart: switching on the status code alone is not enough. See «Transport-level errors» in the API description for when each one is produced. A `402` carrying `SUBSCRIPTION_REQUIRED` lands here when the account has no active subscription. `error.details` says why and what to do: `current_status` (absent if it never had one), `required_permission` and `action`. A `503` carrying `SERVICE_UNAVAILABLE` lands here too, with a `Retry-After` header: a dependency of BeeL itself (the database, the email provider) was momentarily unavailable and nothing was done. Retry after those seconds. A `502` carrying `EXTERNAL_SERVICE_ERROR` also lands here: an outbound integration the operation depends on failed or did not answer in time. It is a transient condition — retry with the same `Idempotency-Key` where the operation accepts one. One exception to the envelope: a failure of the network edge that never reaches the application (`502`, `503`, `504`, `524`) is generated by Cloudflare and its body is not BeeL's — it may not even be JSON. Treat those as "no answer", and retry. --- [API](https://skmtc.dev/beel/apis/beel-public-api.md) · [All operations](https://skmtc.dev/beel/apis/beel-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beel/apis/beel-public-api/revisions/ffbc0ae31f79?raw)