Account

Provision a managed account

Provision a SEPARATE account for one of your clients, with its tax ID, plan and your access_level; your account pays it.

Returns 201 with the claim voucher shown EXACTLY ONCE, or emailed with send_email: true.
Repeating an external_ref returns 200 with no new voucher; Idempotency-Key is required.
Requires the privileged accounts:write scope.

post/accounts

Request

Base URL: https://api.factuarea.com/v1
URL: https://api.factuarea.com/v1/accounts
Auth: one of:
- HTTP bearer
- API key in header X-API-Key

Headers

Idempotency-Keystring required

Example:01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b

Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns 422 idempotency_key_reused; the values of secret fields (password, secret…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the Idempotency guide. Required on this operation: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with 422 idempotency_key_required before any business logic runs.

Factuarea-Versionstring date

Example:2026-06-01

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Request body

external_refstring required

Your own reference for the account (up to 128 characters), unique per provider. Provisioning it again returns the same account (200) without a new voucher.

plan'emprendedor' | 'empresario' | 'integral' | 'enterprise' required

Plan of the managed account: emprendedor, empresario or integral. enterprise returns 422 managed_account_plan_not_self_serve.

access_level'none' | 'view' | 'operate'

Access level your account keeps on the managed account: none (default, provisioning only), view (read-only) or operate.

tax_idstring required

Spanish tax identifier (NIF, CIF or NIE) of the managed account.

legal_namestring required

Legal name of the managed account.

display_namestring nullable

Visible name of the account and of its tax ID; without it, the legal name.

addressstring nullable

Fiscal address.

citystring nullable

City of the fiscal address.

postal_codestring nullable

Postal code (derives the AEAT zone).

provincestring nullable

Province.

countrystring nullable

Country.

language'es' | 'en' | 'ca' | 'null' nullable

Language of the account and of its claim voucher: es (default), en or ca.

owner_emailstring email nullable

Email of the holder of the account. Required with a live key and whenever send_email is true.

send_emailboolean

Email the claim link to owner_email (true) or return the voucher once in the response (false, default).

Response

Managed account provisioned. The Location header contains the canonical URL of the new managed account; the body carries its claim voucher once.

Example response

{
  "data": {
    "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
    "object": "managed_account",
    "external_ref": "cliente-0042",
    "status": "provisioned",
    "environment": "live",
    "plan": "empresario",
    "billing_interval": "monthly",
    "access_level": "operate",
    "display_name": "Talleres García",
    "language": "es",
    "companies": [
      {
        "id": "0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f",
        "tax_id": "B12345674",
        "name": "Talleres García SL"
      }
    ],
    "management": {
      "status": "active"
    },
    "paid_by_provider": true,
    "created_at": "2026-09-27T09:00:00+00:00",
    "claim": {
      "status": "valid",
      "issued_at": "2026-09-27T09:00:00+00:00",
      "expires_at": "2026-10-11T09:00:00+00:00",
      "ttl_days": 14,
      "masked_email": "c***@talleresgarcia.es"
    },
    "plan_renews_at": "2026-10-27T09:00:00+00:00",
    "claim_token": "c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1",
    "claim_url": "https://app.factuarea.com/account-claims/accept?token=c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1",
    "claim_expires_at": "2026-10-11T09:00:00+00:00"
  }
}

Changes

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