NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Identity

Get my identity

Returns the identity of the authenticated principal: the account the credential belongs to, the person's email, name, logo and interface language, and a description of the credential itself. Unlike every other operation, it requires no scope — any valid credential resolves, so a 200 confirms the credential works and tells you which account it belongs to, and a 401 that it does not.

  • account_id: identifies who the credential belongs to, not what it is currently pointed at; selecting a different company with BeeL-Active-Company does not change it.
  • name: resolves as trade_name ?? legal_name of the active fiscal profile, and is null until onboarding creates one.
  • credential: describes the credential the call was authenticated with — its type, the environment it operates on and the permissions it holds — so a client can adapt what it offers instead of discovering the limits through a 403.
  • Caching: responses are never cached (Cache-Control: no-store).
GET
/v1/me/identity

Authorization

AuthorizationBearer <token>

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

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/me/identity"
{
  "success": true,
  "data": {
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "BeeL.es",
    "email": "user@example.com",
    "logo_url": "https://assets.beel.es/logos/.../profile-logo.jpg",
    "language": "es",
    "credential": {
      "type": "api_key",
      "environment": "PROD",
      "scopes": [
        "invoices:write",
        "customers:read",
        "companies:list"
      ]
    }
  },
  "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": "FEATURE_NOT_AVAILABLE",
    "message": "Your plan does not include api_access",
    "details": {
      "feature_code": "api_access",
      "current_plan": "FREE"
    }
  },
  "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"
  }
}

Validate a NIF against the AEAT register POST

Checks a NIF or CIF against the AEAT register through VeriFactu and returns what the register says about it. It only reads the register: it creates nothing and stores no customer. - **`status`:** distinguishes a NIF found in the register from one that is syntactically correct but absent, and from a check that could not be completed because VeriFactu was unavailable — in which case the NIF is validated automatically once the service is back. - **`valid: true`:** means different things by holder. For an individual, AEAT matched NIF and name together. For a legal entity the name you sent is **not verified** at all — AEAT identifies a company by its CIF alone — so it says nothing about your name. - **`legal_name_verified`:** tells those two cases apart. - **`census_status`:** says whether an identified NIF is also deregistered or revoked. ## Invalid input - **Bad syntax is an answer, not an error:** it comes back `200` with `status: INVALID`, so a pre-validation flow never has to tell rejections apart by status code. - **A missing NIF is an error:** an absent or empty `nif` answers `422` `FIELD_BLANK`, with `details.field` naming it.

Update my preferences PATCH

Updates the preferences of the authenticated person. Today the only mutable preference is `language`. It applies to the interface, to template names and colours in invoice customisation, and to the emails the person receives. It belongs to the person, not to a fiscal profile: the languages of invoices and of emails are separate settings of each company.