Accounts

Provision an account

Provisions a new account on BeeL and, when it is born with a holder, returns a single-use claim_token to deliver so they can set a password and take ownership.

  • email: send it to create the account with a holder. Omit it and the account is created with no person at all, no person_id and no claim_token; a holder can be added later with POST /v1/accounts/{account_id}/claim-tokens.
  • tax_profile: send it and the account comes back ready to invoice, with its NIF, default invoice series and VeriFactu configuration set up. Omit it and the account's company is created without a NIF until its holder registers one. Either way its company_id is in the response.
  • access_level: the access you retain over the account. Defaults to NONE; OPERATE requires a tax_profile.
  • external_ref: the idempotency key. Resending the same one returns the existing account rather than creating a second.
  • Entitlement: requires manage_accounts.

Reactivation

If you previously ended your management of this account (DELETE /v1/accounts/{account_id}/management) and its holder has not claimed it yet, provisioning the same email reactivates that account instead of creating a new one. The same account, holder, NIFs and invoices come back under your management, with the external_ref and access_level of this request, and it counts towards your billable usage again. Once the holder has claimed the account it is theirs, and only they can grant you access again.

post/v1/accounts

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/accounts
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

emailstring email

Optional. Email address of the account holder, used as their login. Omit it to create the account without a person: no login, no person_id and no claim_token. You can add the holder later with POST /v1/accounts/{account_id}/claim-tokens. Required when send_email is true (there is nobody to write to otherwise) — else 422.

display_namestring required

Human-readable name for the account. Must not be blank.

external_refstring required

Your own identifier for this account in your system. Used as an idempotency key: re-provisioning with the same external_ref returns the existing account (201, not 409).

language'es' | 'en' | 'ca'

Supported languages: es Spanish, en English, ca Catalan.

access_level'NONE' | 'VIEW' | 'OPERATE'

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.

send_emailboolean

Optional. When true, BeeL emails the account holder a claim link (/reclamar?token=...) so they can set their password and take ownership. Defaults to false: by default you receive the claim_token in the response and deliver it yourself. Requires a deliverable email: sending true without one returns 422.

Example request

{
  "language": "es",
  "tax_profile": {
    "entity_type": "INDIVIDUAL",
    "address": {
      "street": "Calle Mayor, 123",
      "number": "123",
      "floor": "2º A",
      "door": "A",
      "postal_code": "28001",
      "city": "Madrid",
      "province": "Madrid",
      "country": "España",
      "country_code": "ES"
    },
    "legal_representative": {
      "full_name": "María García López",
      "nif": "12345678A",
      "address": {
        "street": "Calle Mayor, 123",
        "number": "123",
        "floor": "2º A",
        "door": "A",
        "postal_code": "28001",
        "city": "Madrid",
        "province": "Madrid",
        "country": "España",
        "country_code": "ES"
      }
    },
    "default_main_tax": {
      "type": "IVA",
      "percentage": 21,
      "regime_key": "01"
    }
  }
}

Response

Account provisioned successfully. Business idempotency by external_ref: resending the same external_ref returns 201 with the same account id (not 409). While the account is still unclaimed, a claim link that is still valid is never revoked: the response comes back with claim_token and claim_url null and claim_link_already_issued: true, and no email is re-sent. Only when no valid link remains (expired, or none was ever issued) is a fresh claim_token issued. To replace a valid link on purpose, use POST /v1/accounts/{account_id}/claim-tokens. For exact response idempotency (same body, same token on retries) send an Idempotency-Key header — the response is cached for 24h.

successboolean required

Example response

{
  "success": true,
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.