{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-provision-account-result-schema.json",
  "title": "ProvisionAccountResult",
  "description": "Result of a successful account provision. `claim_token` is a single-use secret to deliver to the account holder so they can set their password and take ownership. It is returned only once; `null` if the account was already claimed, `null` when the account was provisioned without `email` (there is no holder to hand it to yet), and `null` when a repeated provision found a claim link still valid (`claim_link_already_issued: true`). `claim_url` is the ready-to-use claim link BeeL builds for the current environment; `status` disambiguates a `null` `claim_token` (already claimed) from an error.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beel-es-accounts-api-openapi.yml#/components/schemas/ProvisionAccountResult",
  "type": "object",
  "required": [
    "account_id",
    "status",
    "claim_link_already_issued"
  ],
  "properties": {
    "person_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "The account holder. `null` when the account was provisioned **without `email`**: it has no person yet, and gains one when a claim token is issued."
    },
    "account_id": {
      "type": "string",
      "format": "uuid"
    },
    "status": {
      "allOf": [
        {
          "$ref": "#/$defs/ProvisioningStatus"
        }
      ],
      "description": "Lifecycle stage of the account right after this call. A newly provisioned account is `PROVISIONED` (not yet claimed). Combined with `claim_token`, it is self-explanatory: a `null` `claim_token` with `status: CLAIMED`/`ACTIVE` means the holder already took ownership (not an error)."
    },
    "claim_token": {
      "type": [
        "string",
        "null"
      ],
      "description": "Single-use claim token (shown once); `null` if the account is already claimed, or if a claim link issued earlier is still valid (see `claim_link_already_issued`)."
    },
    "claim_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "description": "Ready-to-use claim link for the account holder, built by BeeL for the current environment (no need to assemble `/reclamar?token=` yourself). `null` when `claim_token` is `null`."
    },
    "claim_link_already_issued": {
      "type": "boolean",
      "description": "`true` when this call repeated the provision of an unclaimed account that already has a claim link still valid (pending and not expired). That link is **kept working**: nothing is issued or revoked, `claim_token` and `claim_url` come back `null`, and no email is re-sent even with `send_email: true` (there is no token in clear to send). The link you already handed out is the one the holder uses. To replace it on purpose, call `POST /v1/accounts/{account_id}/claim-tokens`, which revokes the previous one. `false` otherwise."
    },
    "company_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "The account's company id (a UUID) — send it in the `BeeL-Active-Company` header to operate on this account. Every account is born with one company: with a `tax_profile` it is ready to invoice; without one it has no NIF yet (the holder registers it on claim), and its issuing readiness reports `COMPANY_HAS_NO_NIF` until then. `null` only when resending an `external_ref` whose account now holds two or more companies."
    }
  },
  "$defs": {
    "ProvisioningStatus": {
      "type": "string",
      "enum": [
        "PROVISIONED",
        "CLAIMED",
        "ACTIVE"
      ],
      "description": "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)."
    }
  }
}