Tax ID portfolio

The tax ID portfolio is the list of tax IDs (NIF) that your account operates. It holds the titular company the account was opened with and every additional tax ID you register or receive by a transfer. These operations register a tax ID, follow how it is set up, deactivate, reactivate and archive it, and read its statistics and whether it can issue.

They are operations of the account, so they hang off /v1/accounts/{account}/companies. {account} is the account.id that GET /v1/me returns, and {company} is the id of a tax ID, an opaque UUID v7, not its tax_id. Working inside a tax ID (its invoices, contacts and series) goes through the company axis, /v1/companies/{company}/…: reach a tax ID explains it. The tax IDs of another account that you reach through granted access or a managed account are not part of your portfolio, and the list never shows them.

Register a tax ID

POST /v1/accounts/{account}/companies registers a tax ID in your account. name and tax_id are the only required fields: the rest of the fiscal profile is optional and can travel in the same request. The tax_id (NIF / CIF / NIE) must pass the fiscal validation and be unique within your account. It requires the companies:write scope and an Idempotency-Key: without it the answer is 422 idempotency_key_required, before anything runs.

Every tax ID after the first is an additional tax ID. The registration goes through its gate before anything is created. It occupies a free contracted seat of the account and does not charge. Without a free seat the web application answers 422 contracted_seats_exhausted and asks you to buy seats, while the v1 API and the MCP buy the missing ones as part of the call. When any check fails nothing is created and nothing is charged.

curl -X POST https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Talleres García",
    "business_name": "Talleres García, Sociedad Limitada",
    "tax_id": "B12345674"
  }'

Response (201), with a Location header that carries the canonical URL of the new tax ID:

{
  "data": {
    "object": "company",
    "id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
    "name": "Talleres García",
    "business_name": "Talleres García, Sociedad Limitada",
    "tax_id": "B12345674",
    "status": "active",
    "address": "Calle Mayor 1",
    "city": "Madrid",
    "postal_code": "28013",
    "province": "Madrid",
    "country_aeat_zone": "peninsula",
    "email": "contacto@talleresgarcia.es",
    "phone": "+34911234567",
    "logo_url": null,
    "paid_until": "2026-07-15T10:00:00+00:00",
    "suspension_reason": null,
    "created_at": "2026-01-15T09:30:00+00:00",
    "updated_at": null
  }
}

Request body

The status in the response is the state of the tax ID, a different axis from the provisioning_status that tracks its setup. paid_until is informative data: the end of the period the tax ID was last paid for. It decides no charge, and it is null when it was not charged, in a trial for example. There is no country_aeat_zone input field: you send a free-text country, and the zone is derived from the postal_code.

The new tax ID enters the scope of the key that registered it, so you can work with it right away. When that key cannot take it, the registration still succeeds and the key keeps exactly the scope it had. That happens when the key is published in a browser, when one of its scopes is not available on the new tax ID, or when the person who issued the key does not reach the new tax ID at the level the key needs. GET /v1/me lists what a key reaches in scope: to reach the new tax ID, issue a key that names it.

What the gate can answer

The gate is the one of additional tax IDs, and it judges in this order: who pays, the plan, the cap, the seats. These are the answers you can meet, each of them before any charge:

Duplicate tax ID

A tax_id that is already in your account, active or inactive, answers 409 with resource_already_exists, and error.details.existing_resource_id points at the tax ID that holds it:

{
  "error": {
    "type": "conflict_error",
    "code": "resource_already_exists",
    "subcode": "managed_company_tax_id_already_exists",
    "message": "Ya existe una empresa con ese NIF/CIF/NIE en la cuenta.",
    "param": "tax_id",
    "details": {
      "existing_resource_id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c"
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_already_exists",
    "request_id": "req_01J8Y3M2Q4CF0000000000MCT1"
  }
}

The subcode keeps the name it always had. An archived tax ID no longer holds its fiscal identifier: you can register the same tax_id again, as a new tax ID with a new id that inherits no paid_until.

A tax ID that belongs to another account

A tax_id that already belongs to another account is not registered twice. The answer is 422 business_rule_violation with the subcode nif_already_claimed_by_another_account and param tax_id, and it names neither the other account nor anything of it. The account that holds the tax ID hands it over with a tax ID transfer, and you accept it.

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "subcode": "nif_already_claimed_by_another_account",
    "message": "Este NIF ya pertenece a otra cuenta. Para traerlo a la tuya, pide a la cuenta que lo tiene un traspaso de NIF y acéptalo; un NIF no puede estar en dos cuentas a la vez.",
    "param": "tax_id",
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_01J8Y3M2Q4CF0000000000NAC1"
  }
}

Provisioning

The registration is atomic: when its seat can be neither occupied nor bought it creates nothing, so there is never a half-open tax ID. The 201 already describes an active tax ID. Right after it, in the background, we create its default document series and its minimal fiscal configuration, and has_default_series of issuing readiness turns true when that is done. Two endpoints expose the provisioning state: one to poll it and one to reconcile it.

Provisioning states

provisioning_status walks a small, one-way lifecycle:

A tax ID with no stored provisioning state reads active. No new registration leaves a tax ID in awaiting_payment: only one that was already waiting for its payment can still show it, and verifying the creation settles it.

What adding a tax ID costs

An additional tax ID occupies a contracted seat of the account, and registering or reactivating one does not charge: it takes a free seat. Only buying seats charges, prorated for the rest of the period, on the additional-nifs subscription of the account. When no seat is free the web application answers 422 contracted_seats_exhausted, and the v1 API and the MCP buy the missing ones in the call itself (automatic purchase). Deactivating a tax ID frees its seat without lowering the bill: to pay less you reduce the seats. The API does not hold the amount: ask the preview or read unit_amount in gestoria_seats instead of hard-coding it. Additional tax IDs explains the price and the plans, and the trial rule and what happens to the extra tax IDs when your plan changes complete it.

Poll the creation status

GET /v1/accounts/{account}/companies/{company}/creation-status returns the current provisioning_status and its timestamps. Requires the companies:read scope.

curl https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies/$COMPANY_ID/creation-status \
  -H "Authorization: Bearer $FACTUAREA_KEY"

Response (200):

{
  "data": {
    "object": "company_creation_status",
    "id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
    "provisioning_status": "active",
    "payment_setup_url": null,
    "failed_reason": null,
    "started_at": "2026-01-15T09:30:00+00:00",
    "completed_at": "2026-01-15T09:31:00+00:00"
  }
}

payment_setup_url is present only while the state is awaiting_payment and for a production key that reaches the titular company, and null otherwise. failed_reason is present only when the state is failed.

Verify the creation

POST /v1/accounts/{account}/companies/{company}/verify-creation reconciles a tax ID against the subscription of the account titular and advances it when it can. It takes no request body and is idempotent. Requires the companies:write scope.

curl -X POST \
  https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies/$COMPANY_ID/verify-creation \
  -H "Authorization: Bearer $FACTUAREA_KEY"

It only acts on a tax ID in awaiting_payment:

• Once the titular has a payment method, the tax ID is charged as an additional tax ID and moves to active.
• While the titular still has none, the call does nothing and answers no error: the tax ID stays in awaiting_payment.
• In any other state the call does nothing, so it is safe to repeat.

It never answers 402: a charge that fails leaves the provisioning in failed, with its reason. It returns the same resource as the poll, so you read the resulting provisioning_status from the response. It charges the account titular, so the key must reach the titular company (403 forbidden_action otherwise).

The state of a tax ID

Separate from provisioning, every tax ID has a status in the account. It is the status field of the tax ID and walks three states:

Transitions are active ↔ inactive (deactivate and reactivate), and active → archived or inactive → archived (archive). Two more fields describe the state:

• paid_until. Informative data of the tax ID: the end of the period it was last paid for. It decides no charge, because reactivating takes a free seat or buys one whatever the date. It is null when the tax ID has no paid period to report.
• suspension_reason. Why the system suspended an inactive tax ID: payer_blocked when the account that pays for a managed account has its billing blocked, and management_ended when the management ended before anyone took over the payment. It is null when the system did not suspend it, for example because the account itself deactivated it.

The account keeps one. An account always has at least one active tax ID. Deactivating or archiving the titular company, or the last active tax ID, needs a successor: another active tax ID of the account takes over as titular in the same operation. With none, the answer is 422 business_rule_violation with the subcode account_must_keep_one_nif and nothing changes.

Deactivate a tax ID

POST /v1/accounts/{account}/companies/{company}/deactivate moves an active tax ID to inactive. It stops operating and keeps all its data, reversibly. It never charges and never answers 402: the additional tax ID frees its seat, and the contracted seats and the bill stay as they are, so you can reactivate it into that free seat. To pay less, reduce the seats. Requires the companies:write scope.

curl -X POST \
  https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies/$COMPANY_ID/deactivate \
  -H "Authorization: Bearer $FACTUAREA_KEY"

It returns the updated tax ID with status: "inactive".

Reactivate a tax ID

POST /v1/accounts/{account}/companies/{company}/activate moves an inactive tax ID back to active, and it requires an Idempotency-Key. The reactivated tax ID is an additional tax ID again, so it goes through the same gate as a registration and occupies a free contracted seat at no charge. Without a free seat the web application answers 422 contracted_seats_exhausted, and the v1 API and the MCP buy the missing seat first: only if the purchase succeeds does the tax ID become active. One in a trial, one of an enterprise account billed by contract and one of a test account are not charged. Requires the companies:write scope.

curl -X POST \
  https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies/$COMPANY_ID/activate \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

It returns the updated tax ID with status: "active".

Reactivate tax IDs in batch

POST /v1/accounts/{account}/companies/activate reactivates several tax IDs in one call. They occupy the free seats and, in the v1 API and the MCP, the seats still missing for the whole batch are bought in a single combined purchase: one invoice for the batch. The body takes company_ids, a list of id values (1–1000), and the call requires an Idempotency-Key. Requires the companies:write scope.

curl -X POST https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies/activate \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "company_ids": [
      "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
      "01931b3e-8d5b-7a1f-9c2d-5e6f7a8b9c0d"
    ]
  }'

The batch is all or nothing. Every tax ID is validated before any purchase: one that is not part of your account answers 404 for the whole batch, and one that is not inactive answers 422 business_rule_violation. The gate and the cap judge the batch as a whole. The response is the list of reactivated tax IDs ({ "data": [ … ] }).

Preview the charge

GET /v1/accounts/{account}/companies/seat-charge-preview returns the seats that adding or reactivating additional tax IDs would occupy or buy and what that would cost, computed from the upcoming invoice of the account titular and without charging anything. The contracted seats free today are used first. Use it to show the prorated amount before a registration or a reactivation. Requires the companies:read scope. The path keeps its original name.

It has two modes:

• count (1–1000, default 1) previews the combined proration of adding that many tax IDs.
• company_ids[] takes specific id values and sizes the operation for exactly those tax IDs. When present, it takes precedence over count.

curl -G https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies/seat-charge-preview \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  --data-urlencode "count=3"

Response (200):

{
  "data": {
    "object": "seat_charge_preview",
    "amount": "7.50",
    "tax_amount": "1.58",
    "total": "9.08",
    "tax_rate": 21,
    "currency": "EUR",
    "next_invoice_date": "2026-04-01T00:00:00Z",
    "requires_payment_method": false,
    "requires_active_plan": false,
    "included_in_trial": false,
    "already_covered": false,
    "is_first_seat": false,
    "recurring_quantity": 3,
    "recurring_base_cents": 4500,
    "recurring_total_cents": 5445
  }
}

amount is the taxable base of the proration, tax_amount the VAT and total (amount + tax_amount) what is actually charged, all in euros as strings with two decimals. tax_rate is the VAT percentage, or null when it could not be resolved. The recurring_* fields project the monthly fee after the operation: how many additional tax IDs are billed, their base and the same with VAT. The two _cents fields stay in cents, as their names say, and recurring_total_cents is null when the VAT is not computable.

Four mutually exclusive flags explain an amount of 0, in priority order (already_covered stays in the response and is always false: paid_until no longer covers anything):

is_first_seat is true when the operation creates the first additional tax ID subscription of the account: the charge is then a full month, and today becomes the monthly billing day.

free_seats_used is how many free contracted seats the operation would occupy and seats_to_buy how many it would have to buy. included_in_seats is true when the free seats cover it all, and then zero_reason is included_in_seats. seats is the contracted-seats block after the operation, and cancels_pending_reduction is true when the operation would cancel a pending reduction. These fields are additive: the response example above does not list them.

The preview is a read, so it never answers 402 and does not judge the plan or the cap of the writes. It answers 403 billing_managed_by_provider when the provider pays the billing of the account, and 404 when a company_ids[] value is not a tax ID of the account. Additional tax IDs explains every field.

List and retrieve tax IDs

GET /v1/accounts/{account}/companies returns the tax IDs of your account that your key reads, with cursor pagination. GET /v1/accounts/{account}/companies/{company} returns one. Both require companies:read.

curl "https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies?status=inactive&limit=25" \
  -H "Authorization: Bearer $FACTUAREA_KEY"

Only the tax IDs of the account in the path are ever returned, and only those within the scope of your key. A tax ID that is not one of them answers 404: see isolation.

Statistics per tax ID

GET /v1/accounts/{account}/companies/stats returns one company_stats row for each tax ID your key reads, archived ones hidden: the issued invoices of the period (invoices_count), what they invoice (total_invoiced, a string with two decimals) and the last issued invoice whatever the period (last_invoice, or null). The period is date_from and date_to (YYYY-MM-DD, inclusive and both optional): without them it is the current calendar year. The list is not paginated. Requires companies:read.

curl "https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies/stats?date_from=2026-01-01&date_to=2026-09-30" \
  -H "Authorization: Bearer $FACTUAREA_KEY"

{
  "data": [
    {
      "object": "company_stats",
      "company_id": "01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c",
      "tax_id": "B12345674",
      "name": "Talleres García",
      "invoices_count": 3,
      "total_invoiced": "363.00",
      "last_invoice": {
        "number": "F-2026-003",
        "issued_on": "2026-09-20",
        "total": "121.00"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Can this tax ID issue?

GET /v1/accounts/{account}/companies/{company}/issuing-readiness answers whether a tax ID is ready to issue invoices. It is a neutral, fiscal read: can_issue is the verdict, blockers lists the machine-readable reasons when it is false, and the other fields are the signals it was built from. It never looks at the subscription, the plan or the price, and it never answers with a payment-required state. With include=readiness on the list, each tax ID carries the same object in readiness.

{
  "data": {
    "can_issue": false,
    "blockers": [
      "census_not_identified",
      "no_default_series"
    ],
    "census_status": "not_identified",
    "has_default_series": false,
    "fiscal_profile_complete": true,
    "operable": true,
    "missing_modules": [],
    "checked_at": "2026-05-25T18:00:00+00:00"
  }
}

Branch on the code of each blocker, such as verifactu_certificate_missing when VeriFactu is enabled and the tax ID has no valid certificate. New reasons can appear: treat an unknown one as a blocker you cannot fix through the API. Accounts and tax IDs describes the fields.

Update a tax ID

PATCH /v1/accounts/{account}/companies/{company} is a partial update of the profile: name, business_name, address, city, postal_code, province, country, email and phone. Omitted fields keep their value, and "" clears one. name is always the name the company is known by: changing only name renames the trade name when there is a distinct legal name, and the legal name otherwise. Changing only business_name changes the legal name and keeps name, and "business_name": "" makes name the legal name. country_aeat_zone is derived from the postal code, and the tax_id is immutable: sending it answers 422. Only an active tax ID can be edited (422 business_rule_violation otherwise). Editing is not billed and never answers 402. Requires the companies:write scope.

curl -X PATCH \
  https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies/$COMPANY_ID \
  -H "Authorization: Bearer $FACTUAREA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Talleres García e Hijos SL" }'

Archive a tax ID

DELETE /v1/accounts/{account}/companies/{company} archives the tax ID rather than deleting it: its status moves to archived, it stops accepting operations, and the company and its history are preserved. The answer is 204. An active or inactive tax ID can be archived, and archived is terminal. Archiving never charges and never answers 402. Requires the companies:delete scope.

curl -X DELETE \
  https://api.factuarea.com/v1/accounts/$ACCOUNT_ID/companies/$COMPANY_ID \
  -H "Authorization: Bearer $FACTUAREA_KEY"

What archiving does besides:

• It frees the fiscal identifier, as registering explained, and it revokes the open tax ID transfers of that tax ID.
• It releases its seat once. An additional tax ID that was still active frees the seat it occupied, without lowering the bill, and one that was already inactive has no seat to free again.
• It stays readable. An archived tax ID keeps appearing in the list with status=archived, and GET /v1/accounts/{account}/companies/{company} still returns it. A change through the account (PATCH, activate or DELETE) answers 404 resource_not_found, the same as for a tax ID that is not one of the account, and an operation on its data through /v1/companies/{company}/… answers 403 company_inactive (resolution).

Scopes, capacity and isolation

The portfolio has its own scopes, and they need no particular plan. The plan only matters inside the operation that adds a tax ID, through the additional tax ID gate:

• companies:read lists and retrieves tax IDs, reads the statistics, the issuing readiness and the creation status, and previews the charge.
• companies:write registers, updates, reactivates (one or several), deactivates and verifies the creation.
• companies:delete archives.

None of the three is granted through OAuth: use an API key.

Account capability. Every write is a capability of the account. The person who issued the key must be an owner or admin of the account with the user_management section available, and otherwise the answer is 403 forbidden_action, before anything is charged or changed. A write that can buy seats (register, reactivate, batch and verify) also needs a key that reaches the titular company, which is the one that pays.

Level on the tax ID. A key holds view or operate on each tax ID it reaches, as scoped keys explains. With view, a write on that tax ID answers 403 company_read_only and changes nothing, and with no access it answers the same 404 as a tax ID outside the account.

Isolation. A {company} that does not exist, belongs to another account, is outside what your key reads, belongs to the other environment or is not an identifier answers the same 404 resource_not_found, with param company, and never a 403: a 403 would say that the tax ID exists. An {account} that is not the account of your key answers 404 account_not_found.

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "NIF no encontrado en la cuenta.",
    "param": "company",
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_not_found",
    "request_id": "req_01J8Y3M2Q4CF0000000000RNF1"
  }
}

A tax ID that you reach only through a relation between accounts is not a tax ID of your account. Editing, activating, deactivating, archiving or verifying a granted tax ID through your own {account} answers that same 404, with no change and no charge. Its data is served through the company axis, as reach a tax ID explains. Managed accounts describes the closed list of routes on which {account} may name a managed account instead of your own.

Test keys. A fact_test_ key belongs to your real account, so it reads your portfolio as a live key does. Every write of the portfolio on your live account answers 403 live_credential_required with nothing written. Test managed accounts covers what a test key can do.

Identity for document sending

Sending a document by email may require the identity of the sender to be proved, and a new account starts in probation. A tax ID takes both from the company it inherits its trust from:

• The titular company of an account inherits from nobody.
• Any other tax ID of an account that is not managed, because the account bought it, received it by transfer or registered it, inherits from the titular company of its own account.
• The tax IDs of a managed account inherit from the titular company of the provider's account for as long as the management lasts, and from their own titular company once it ends.
• A tax ID you reach through granted access inherits nothing from the receiving account: its trust stays that of the titular company of its own account.

422 sender_identity_not_verified means that the identity of the company the tax ID inherits from has to be corrected, and a 429 concerns a separate sending budget. See sending documents and what the tax IDs of an account share.

Follow the portfolio with events

Account webhooks publish what happens to the tax IDs of the account: account.nif_added when one enters it (registered when you register it), account.nif_transferred with direction in or out when one moves by transfer, and account.nif_archived when you archive one. The catalog has no event for deactivating or reactivating a tax ID.

Related