# Accounts Inspect the account and invoicing configuration available to an API key. An account owns its customers, invoice series, API keys and invoices. Every account is isolated in either the `live` or `test` environment; resources cannot be shared between environments. The account exposes the invoice, credit-note, and amendment series used when an operation omits an explicit series. Account resources are currently read-only. An account API key has access to exactly one account, so the list endpoint currently returns one item. The collection shape leaves room for credentials that can access multiple accounts in the future. ## The Account object ### Properties #### `id` Type: `string` Opaque identifier for an account. #### `object` Type: `string` String identifying this as an Account object. Always `account`. #### `live` Type: `boolean` True when the object belongs to the live environment; false for test data. #### `name` Type: `string` Legal or trading name used when issuing invoices. #### `tax_id` Type: `object` The account's current fiscal identifier and verification state. ##### `tax_id.id` Type: `string` Opaque identifier for a Tax ID. ##### `tax_id.object` Type: `string` String identifying this as a Tax ID object. Always `tax_id`. ##### `tax_id.live` Type: `boolean` True when the object belongs to the live environment; false for test data. ##### `tax_id.country` Type: `string` ISO 3166-1 alpha-2 country associated with the tax ID. It must be compatible with the selected tax ID type. ##### `tax_id.type` Type: `enum` FiscalRail's normalized fiscal identifier type. Possible values: - `es_nif` — A Spanish NIF, including DNI and NIE identifiers for individuals and NIF identifiers for legal entities. - `eu_vat` — A VAT identifier issued by an EU member state and checked for intra-EU registration. - `local` — A domestic fiscal identifier that FiscalRail validates locally without querying a registry. ##### `tax_id.value` Type: `string` The normalized fiscal identifier value. ##### `tax_id.owner` Type: `object` The account or customer that owns the Tax ID. ###### `tax_id.owner.type` Type: `enum` The kind of resource that owns the Tax ID. Possible values: - `account` — The FiscalRail account whose legal entity uses this Tax ID. - `customer` — The customer associated with this Tax ID. ###### `tax_id.owner.id` Type: `string` Account or customer ID, according to `type`. ##### `tax_id.verification` Type: `object or null` The latest registry verification, or null when verification is unavailable. ###### `tax_id.verification.status` Type: `enum` The current state of the latest registry-verification attempt. Possible values: - `pending` — The registry check is queued, running or waiting to be retried. - `completed` — The registry returned a result; inspect `valid` for the outcome. - `failed` — FiscalRail could not complete the registry query; this is not evidence that the Tax ID is invalid. ###### `tax_id.verification.valid` Type: `boolean or null` The registry result, or null while pending or when verification failed. ###### `tax_id.verification.completed_at` Type: `string or null` When the verification attempt completed or failed, or null while it is pending. #### `email` Type: `string or null` Contact email, or null when none was supplied. #### `phone` Type: `string or null` Contact phone number, or null when none was supplied. #### `address` Type: `object` Current business address. ##### `address.line_1` Type: `string` Primary street address. ##### `address.line_2` Type: `string or null` Additional address information, or null when not supplied. ##### `address.city` Type: `string` City or locality. ##### `address.postal_code` Type: `string` Postal or ZIP code. ##### `address.state` Type: `string or null` State, province, or region, or null when not applicable. ##### `address.country` Type: `string` ISO 3166-1 alpha-2 country code. #### `environment` Type: `enum` Whether the account creates live or test resources. Possible values: - `live` — Produces live invoices and uses live services. - `test` — Isolated account for test data and simulated services. #### `tax_regime` Type: `string` Tax regime key selected for this account. #### `timezone` Type: `string` IANA timezone used to determine the account's local date. #### `invoice_locale` Type: `enum` Default language used when rendering invoices. Possible values: - `en` — English. - `es` — Spanish. #### `default_invoice_series` Type: `object or null` Series used when invoice issuance omits `series`, or null if none is configured. #### `default_credit_note_series` Type: `object or null` Series used for credit notes created by amendments, or null if none is configured. #### `default_amendment_series` Type: `object or null` Series used for replacement invoices created by amendments, or null if none is configured. #### `created_at` Type: `string` When the account was created. #### `updated_at` Type: `string` When the account was last updated. ### Example ```json { "id": "acct_14Vxtqg2nwvPR75TpsGH8N", "object": "account", "live": true, "name": "Example supplier", "tax_id": { "id": "tax_id_14Vxtqg2nwvPR75TpsGH8N", "object": "tax_id", "live": true, "country": "ES", "type": "es_nif", "value": "B02850360", "owner": { "type": "account", "id": "acct_14Vxtqg2nwvPR75TpsGH8N" }, "verification": { "status": "completed", "valid": true, "completed_at": "2026-08-09T10:24:00Z" } }, "email": "billing@example.com", "phone": "+34910000000", "address": { "line_1": "Gran Via 1", "line_2": null, "city": "Madrid", "postal_code": "28013", "state": "Madrid", "country": "ES" }, "environment": "live", "tax_regime": "es", "timezone": "Europe/Madrid", "invoice_locale": "es", "default_invoice_series": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ", "default_credit_note_series": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR", "default_amendment_series": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS", "created_at": "2026-07-31T09:00:00Z", "updated_at": "2026-07-31T09:00:00Z" } ``` ## Retrieve an account `GET /v1/accounts/{id}` Returns an account accessible to the API key and its current invoicing configuration. ### Path parameters #### `id` Type: `string` — required The opaque ID of the account. ### Responses - `200` — [An Account object.](#the-account-object) Formats: JSON. ### Example request ```bash curl --request GET \ 'https://api.fiscalrail.com/v1/accounts/acct_14Vxtqg2nwvPR75TpsGH8N' \ --header "Authorization: Bearer ak_test_..." ``` ### Example response — 200 ```json { "id": "acct_14Vxtqg2nwvPR75TpsGH8N", "object": "account", "live": true, "name": "Example supplier", "tax_id": { "id": "tax_id_14Vxtqg2nwvPR75TpsGH8N", "object": "tax_id", "live": true, "country": "ES", "type": "es_nif", "value": "B02850360", "owner": { "type": "account", "id": "acct_14Vxtqg2nwvPR75TpsGH8N" }, "verification": { "status": "completed", "valid": true, "completed_at": "2026-08-09T10:24:00Z" } }, "email": "billing@example.com", "phone": "+34910000000", "address": { "line_1": "Gran Via 1", "line_2": null, "city": "Madrid", "postal_code": "28013", "state": "Madrid", "country": "ES" }, "environment": "live", "tax_regime": "es", "timezone": "Europe/Madrid", "invoice_locale": "es", "default_invoice_series": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ", "default_credit_note_series": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR", "default_amendment_series": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS", "created_at": "2026-07-31T09:00:00Z", "updated_at": "2026-07-31T09:00:00Z" } ``` ## List accounts `GET /v1/accounts` Returns the accounts accessible to the API key. Account keys currently return exactly one account. ### Responses - `200` — [A list of Account objects.](#the-account-object) Formats: JSON. ### Example request ```bash curl --request GET \ 'https://api.fiscalrail.com/v1/accounts' \ --header "Authorization: Bearer ak_test_..." ``` ### Example response — 200 ```json { "object": "list", "has_more": null, "data": [ { "id": "acct_14Vxtqg2nwvPR75TpsGH8N", "object": "account", "live": true, "name": "Example supplier", "tax_id": { "id": "tax_id_14Vxtqg2nwvPR75TpsGH8N", "object": "tax_id", "live": true, "country": "ES", "type": "es_nif", "value": "B02850360", "owner": { "type": "account", "id": "acct_14Vxtqg2nwvPR75TpsGH8N" }, "verification": { "status": "completed", "valid": true, "completed_at": "2026-08-09T10:24:00Z" } }, "email": "billing@example.com", "phone": "+34910000000", "address": { "line_1": "Gran Via 1", "line_2": null, "city": "Madrid", "postal_code": "28013", "state": "Madrid", "country": "ES" }, "environment": "live", "tax_regime": "es", "timezone": "Europe/Madrid", "invoice_locale": "es", "default_invoice_series": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ", "default_credit_note_series": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR", "default_amendment_series": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS", "created_at": "2026-07-31T09:00:00Z", "updated_at": "2026-07-31T09:00:00Z" } ] } ```