Managed accounts

A managed account is the account you create for one of your clients. It is a normal account, separate from yours: it has its own tax ID, its own fiscal profile, its own plan and, once the client claims it, its own holder. You provision it over the API, your account pays for it and you keep an access level on it (none, view or operate) until the client takes over. This guide is written for the account that provisions, the provider. It covers the privilege you need, how to create and read managed accounts, how the client claims one, how your level and the end of the management work, which routes a managed account opens and how to upload the client's VeriFactu certificate so its tax ID can issue.

What you pay for each managed account is in managed account pricing and payer change. The whole flow with a fact_test_ key, with no charges, is in test managed accounts. To create many at once, use the bulk import. The account you operate yourself, and the {account} segment, are in accounts and tax IDs.

The life of a managed account

Two fields say where a managed account is. status is the state of the account itself, and the management block says whether your account still manages it.

An account whose management ends before anyone claims it stays provisioned.

Privileged scopes

The provisioning operations of this guide need accounts:read or accounts:write. They are privileged scopes, and they differ from every other scope in four ways:

• * does not cover them. A key that only holds * gets 403 insufficient_scope on these operations. List accounts:read and accounts:write explicitly, next to * if you also want the rest.
• We grant them, account by account. Factuarea grants the account provider privilege to an account, and only Factuarea can. Ask us for it: the API has no operation that grants it. GET /v1/me tells you whether you have it, with account.is_provider and account.privileged_scopes. A key can only carry accounts:* while that list names them, so creating such a key without the privilege answers 403 privileged_scope_required.
• They do not come through OAuth. Use an API key, also with the MCP server.
• No plan gates them. The gate is the privilege, not the plan.

The check runs on every request and nothing comes from a cache. The key must list the scope, your account must hold the privilege today and the person who issued the key must still be an owner or admin of your account. If any of the three fails, the answer is 403 privileged_scope_required, and both causes answer alike. If we revoke the privilege, or that person stops being an owner or admin, the same key stops working on its next request.

The plan and the import operations have their own guides: managed account pricing and payer change and bulk import.

The environment of the key is the environment of everything it provisions and reads. A fact_live_ key works with live managed accounts and a fact_test_ key with test ones, and each sees only its own.

{
  "data": {
    "account": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00",
      "name": "Asesoría Martínez",
      "environment": "live",
      "is_provider": true,
      "privileged_scopes": [
        "accounts:read",
        "accounts:write"
      ]
    }
  }
}

The account block of GET /v1/me, shortened. The same response lists the managed accounts your account reaches in client_accounts, with origin: "provisioned", up to 100 of them; GET /v1/accounts lists all.

Provision an account

POST /v1/accounts creates the account, its tax ID and the relation with your account in one call. It has no {account} segment, because the account does not exist yet. The provider is always the account of the key and the environment is the one of the key: neither goes in the body.

curl -X POST https://api.factuarea.com/v1/accounts \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_ref": "cliente-0042",
    "plan": "empresario",
    "access_level": "operate",
    "tax_id": "B12345674",
    "legal_name": "Talleres García SL",
    "display_name": "Talleres García",
    "language": "es",
    "owner_email": "laura@talleresgarcia.example",
    "send_email": false
  }'

{
  "data": {
    "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
    "object": "managed_account",
    "external_ref": "cliente-0042",
    "status": "provisioned",
    "environment": "live",
    "plan": "empresario",
    "pending_plan": null,
    "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"
      }
    ],
    "claimed": false,
    "claimed_at": null,
    "management": {
      "status": "active",
      "ended_at": null
    },
    "paid_by_provider": true,
    "created_at": "2026-09-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"
  }
}

A new account answers 201 Created with Location: /v1/accounts/{id}. The body is the managed account plus its claim voucher. companies[].id is the {company} you use on the tax ID axis, and id is the {account} of the routes that name a managed account.

Your account pays for it. In live mode we charge it on the managed-accounts subscription of your account, and managed account pricing and payer change explains how much and when. A fact_test_ key creates a test account instead: nothing is charged, there is no voucher (claim_token and claim_url are null) and it does not count against your cap.

Idempotency-Key is required, because provisioning cannot be taken back. A request without it is rejected with 422 idempotency_key_required before any business logic runs. A rejection creates nothing.

Idempotency: Idempotency-Key and external_ref

Two protections work together, and they do different jobs.

Idempotency-Key protects one request. If the connection drops and you repeat the same request with the same key, we replay the first response, with the header Idempotent-Replayed: true, and provision nothing twice. The voucher is the one exception: we never store it in the clear, not even in the idempotency cache, so a replay answers claim_token and claim_url as null. If you never received the first response, reissue the voucher. The same key with another body is 422 idempotency_key_reused.

external_ref protects the account. It is unique for your account across both environments, so it is the natural key of your CRM. Provisioning an external_ref your account already provisioned, even with a new Idempotency-Key, never creates a second account:

The claim voucher

The voucher is what the client needs to claim the account. It comes in three fields of the provisioning response:

What you get back depends on the call:

The voucher is issued in the name of owner_email: a person who signs in with another address cannot use it.

Who delivers the voucher: send_email

You choose one of two ways, and the voucher never travels both ways.

• send_email: false (the default). The response carries claim_url once and you deliver it through your own channel, for example your CRM or your own email. owner_email is still required with a live key, because the voucher is issued in its name.
• send_email: true. We email the link to owner_email, in the language of the account, and the response carries null in claim_token and claim_url. owner_email is required.

Reissue the voucher

POST /v1/accounts/{account}/claim-tokens issues a new voucher for a managed account its holder has not claimed yet. {account} is the id of the managed account. The pending vouchers stop working and the new one goes to the same email and language. The body is optional and takes send_email, with the same meaning as above. It needs an Idempotency-Key.

curl -X POST https://api.factuarea.com/v1/accounts/$MANAGED_ACCOUNT_ID/claim-tokens \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "send_email": false }'

{
  "data": {
    "object": "managed_account_claim",
    "account_id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
    "claim_token": "d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2",
    "claim_url": "https://app.factuarea.com/account-claims/accept?token=d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2",
    "expires_at": "2026-10-11T09:00:00+00:00"
  }
}

With send_email: true, claim_token and claim_url are null, but expires_at still carries the date: the expiry is not a secret and a reissue always issues a new voucher. An idempotent replay returns claim_token and claim_url as null too, and keeps expires_at. The new voucher lasts 14 days, like the first one.

List and read your managed accounts

GET /v1/accounts lists the accounts your account provisioned, in the environment of the key only: a fact_test_ key lists your test accounts and a live key your live ones. No item carries a voucher.

curl -G https://api.factuarea.com/v1/accounts \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --data-urlencode "status=provisioned" \
  --data-urlencode "limit=25"

{
  "data": [
    {
      "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
      "object": "managed_account",
      "external_ref": "cliente-0042",
      "status": "provisioned",
      "environment": "live",
      "plan": "empresario",
      "pending_plan": null,
      "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"
        }
      ],
      "claimed": false,
      "claimed_at": null,
      "management": {
        "status": "active",
        "ended_at": null
      },
      "paid_by_provider": true,
      "created_at": "2026-09-27T09:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

An unknown status value or an external_ref longer than 128 characters answers 422, and an unknown query parameter or a malformed limit or starting_after answers 400.

GET /v1/accounts/{account} returns one managed account by its id, in the same shape. It works with any access level, none included: the provisioning operations only ask that the management is in force.

With status=ended, your account has lost access to the account, so each item is reduced to what you already knew:

{
  "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
  "object": "managed_account",
  "external_ref": "cliente-0042",
  "management": {
    "status": "ended",
    "ended_at": "2026-10-05T10:00:00+00:00"
  }
}

Provisioning usage

GET /v1/accounts/{account}/provisioning-usage tells you how many managed accounts you run and how many more you can provision. Unlike the routes above, {account} is your own account, the account.id of GET /v1/me: any other value answers 404 account_not_found.

{
  "data": {
    "object": "provisioning_usage",
    "managed_accounts": {
      "live": 12,
      "test": 3
    },
    "limit": 50,
    "remaining": 38,
    "managed_accounts_by_plan": {
      "emprendedor": 7,
      "empresario": 5,
      "integral": 0,
      "enterprise": 0
    },
    "provider_paid_additional_nifs": 2,
    "provider_paid_employee_seats": 9
  }
}

The claim

The client claims the account in the app, not through the API. The claim link opens a page where the client sees the account that is waiting, with its plan and its price. A new person chooses a password, and someone who already has a Factuarea account signs in. Either way they must use the address the voucher was issued to (owner_email): another address is rejected, and so is a voucher that was already used, revoked or has expired.

The claim has these effects:

• The client becomes the owner of the account. claimed is true, claimed_at is set and status moves from provisioned to claimed. If you had already ended the management, the account goes straight to active.
• You keep your level. The claim never changes access_level. After it, you can lower the level but no longer raise it: see the level rules.
• You keep paying until the client takes over. While paid_by_provider is true, the account is yours to pay. Managed account pricing and payer change explains how the payment passes to the client.
• We tell you. The owners and admins of your account get an email saying the account was claimed.
• The voucher is consumed. Reissuing it answers 409 provisioning_account_claimed.

A test account cannot be claimed: 422 managed_account_not_claimable when you try to reissue its voucher.

Your access level

PATCH /v1/accounts/{account}/access-level changes the level your account keeps on a managed account. The body takes level, which is required.

curl -X PATCH https://api.factuarea.com/v1/accounts/$MANAGED_ACCOUNT_ID/access-level \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "level": "view" }'

The answer is 200 with the managed account and its new access_level.

Before the claim, you can raise and lower the level as often as you need. After the claim, you can lower it at any time, but raising it answers 422 access_level_raise_forbidden and changes nothing: only the holder can raise it, from their panel. Lowering takes effect at once, and narrows what your credentials reach in its tax IDs from their next request.

End the management

DELETE /v1/accounts/{account}/management ends the management of a managed account. From the next request your account loses access to it and to its tax IDs, and every route answers 404. It needs an Idempotency-Key, and the answer is 200 with the account and management.status: "ended".

curl -X DELETE https://api.factuarea.com/v1/accounts/$MANAGED_ACCOUNT_ID/management \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

{
  "data": {
    "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
    "object": "managed_account",
    "external_ref": "cliente-0042",
    "status": "provisioned",
    "environment": "live",
    "plan": "empresario",
    "pending_plan": null,
    "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"
      }
    ],
    "claimed": false,
    "claimed_at": null,
    "management": {
      "status": "ended",
      "ended_at": "2026-09-28T10:00:00+00:00"
    },
    "paid_by_provider": true,
    "created_at": "2026-09-27T09:00:00+00:00"
  }
}

What happens next depends on whether the client had claimed the account:

• Before the claim. The account stays provisioned and is not operable: all its tax IDs become inactive, with suspension_reason: "management_ended". The voucher keeps working. The account stays that way until the client claims it, or until you provision the same external_ref again, which reactivates the management.
• After the claim. The account becomes active and the payment passes to the holder. If the holder has no payment method, the management ends anyway: you stop paying and the tax IDs of the account stay suspended until the holder takes over the payment.
• An enterprise account by contract that you really pay needs a plan to continue on. Without it, the answer is 422 enterprise_contract_transition_required and the management stays in force. Contact us so we set the plan, then repeat the call.

Afterwards, GET /v1/accounts?status=ended still lists the account with its id, your external_ref and the management block, so your CRM can close the loop. The client can also end the management from their panel.

Which {account} routes accept a managed account

{account} normally names your own account. A managed account is accepted on a closed list of routes, and only when your account provisioned it, its management is in force and it is in the same environment as the key.

Anything a managed account is not accepted on answers the same 404 account_not_found, with the same body, in every case: an account that is not yours, one that does not exist, one in the other environment, one whose management ended, one that gave you granted access instead of being provisioned by you, and a value that is not an identifier. Nothing in the answer tells them apart, so it cannot be used to find out which accounts exist.

The managed account's tax IDs are also reachable on the tax ID axis, at /v1/companies/{company}/…, with the companies[].id you read above. Your keys reach them as they reach your own tax IDs, limited by your level and by the tax ID scope of each key. To add the client's tax IDs to a key you already deployed, send the complete resulting list to PATCH /v1/accounts/{account}/api-keys/{api_key}/nif-scope as scoped_company_ids. A new scope can never exceed the one of the credential that changes it.

Once the client takes over the payment, the account pays for its own tax IDs: your relation becomes granted access with the same level, and registering, activating, deactivating or archiving tax IDs is for the account that pays. Additional tax IDs explains what you can add while you pay.

The client's side is in the app

What the client does with a managed account happens in the app, and none of it has a /v1 operation or an MCP tool. A credential of yours cannot decide for the holder. The client uses the app to:

• claim the account with the voucher;
• see which account manages theirs and at which level;
• raise or lower the level you keep, which is the only way to raise it after the claim;
• end the management;
• take over the payment.

Everything in this guide is your side, the provider's.

The cap: max_managed_accounts

Each account that provisions has a cap on its live managed accounts. It is 25 by default, it lives on your account as max_managed_accounts and only we change it. provisioning-usage returns it as limit.

• What counts. Only live managed accounts whose management is in force. Test accounts never consume it, and neither do accounts whose management ended.
• When it is reached. Provisioning one more live account, or reactivating one, answers 422 managed_accounts_limit_reached and creates nothing. Two requests at the same time cannot get past the cap together, because your account is locked while each one is checked.
• How to make room. End the management of an account you no longer run, or ask us to raise the cap of your account.

The client's VeriFactu certificate

Each tax ID submits to VeriFactu with its own certificate. A provider does not sign on behalf of its clients, and there is no representation or power-of-attorney mode: what you can do with operate is upload the client's certificate, so its tax ID can issue.

The certificate must be the client's own FNMT certificate, in PKCS#12 format, and it must match the tax ID it is uploaded to. You need a key whose effective level on that tax ID is operate, with the verifactu:write scope, and the id of the tax ID from companies[].id of the managed account. With view the upload answers 403 company_read_only, and with none it answers the same 404 as any tax ID you cannot reach.

POST /v1/companies/{company}/verifactu/certificates takes multipart/form-data with certificate_file (.p12 or .pfx, up to 100 KB) and certificate_password. It needs an Idempotency-Key. The uploaded certificate is activated at once and the previous ones are deactivated.

curl -X POST https://api.factuarea.com/v1/companies/$CLIENT_COMPANY_ID/verifactu/certificates \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "certificate_file=@talleres-garcia.p12" \
  -F "certificate_password=$CERTIFICATE_PASSWORD"

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13",
    "object": "verifactu_certificate",
    "subject_nif": "B12345674",
    "subject_name": "Talleres García SL",
    "subject_kind": "juridica",
    "valid_from": "2026-01-01T00:00:00+01:00",
    "valid_to": "2029-01-01T00:00:00+01:00",
    "is_active": true,
    "revoked_at": null,
    "created_at": "2026-01-10T09:00:00+01:00"
  }
}

The upload is rejected with 422 in these cases, and error.param names the field:

What blocks a tax ID from issuing

GET /v1/accounts/{account}/companies/{company}/issuing-readiness answers whether a tax ID can issue right now, and why not when it cannot. It works with the {account} of a managed account and needs companies:read. can_issue is the verdict, and blockers is a closed list of reasons, in no particular order.

{
  "data": {
    "can_issue": false,
    "blockers": [
      "verifactu_certificate_missing"
    ],
    "census_status": "verified",
    "has_default_series": true,
    "fiscal_profile_complete": true,
    "operable": true,
    "missing_modules": [],
    "checked_at": "2026-09-30T10:15:00+00:00"
  }
}

verifactu_certificate_missing is a value of blockers, not an error code: the operation answers 200 and the catalog of error codes has no page for it. It is added to whatever else blocks the tax ID, so a tax ID can carry several at once. It only applies while VeriFactu is on for the tax ID. Upload the certificate and read issuing-readiness again: the blocker disappears when the certificate is valid.

The list can grow over time. Treat a reason you do not know as a blocker you cannot fix through the API. The read is neutral: it looks at the fiscal state and the modules, and never at the subscription, the plan or the payments.

A test account has no VeriFactu: the module is not available with a test key. Test managed accounts explains what the test path leaves out.

Follow a managed account with events

An account webhook endpoint of your account receives the events of the managed accounts you provision when they meet the delivery rules of that guide: account.managed_account_provisioned, account.managed_account_claimed, account.management_ended and account.access_level_changed. They are the way to learn, without polling, that a client claimed their account or that the management ended.

From the MCP server

Ten MCP tools mirror the provider's operations. Each one needs the scope of the operation it mirrors, which is always privileged: use an API key, because OAuth does not carry accounts:*.

The bulk import has no MCP tool: it reads uploaded files, which the MCP server does not carry. MCP tools lists the rest of the catalog.

Next steps