Documentation
Browse documentation

Accounts

Inspect the account and invoicing configuration available to an API key.
View as Markdown

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 string
Opaque identifier for an account.
object string
String identifying this as an Account object. Always account.
live boolean
True when the object belongs to the live environment; false for test data.
name string
Legal or trading name used when issuing invoices.
tax_id object
The account's current fiscal identifier and verification state.
Show child propertiesHide child properties
id string
Opaque identifier for a Tax ID.
object string
String identifying this as a Tax ID object. Always tax_id.
live boolean
True when the object belongs to the live environment; false for test data.
country string
ISO 3166-1 alpha-2 country associated with the tax ID. It must be compatible with the selected 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.
value string
The normalized fiscal identifier value.
owner object
The account or customer that owns the Tax ID.
Show child propertiesHide child properties
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.
id string
Account or customer ID, according to type.
verification object or null
The latest registry verification, or null when verification is unavailable.
Show child propertiesHide child properties
status 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.
valid boolean or null
The registry result, or null while pending or when verification failed.
completed_at string or null
When the verification attempt completed or failed, or null while it is pending.
email string or null
Contact email, or null when none was supplied.
phone string or null
Contact phone number, or null when none was supplied.
address object
Current business address.
Show child propertiesHide child properties
line_1 string
Primary street address.
line_2 string or null
Additional address information, or null when not supplied.
city string
City or locality.
postal_code string
Postal or ZIP code.
state string or null
State, province, or region, or null when not applicable.
country string
ISO 3166-1 alpha-2 country code.
environment 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 string
Tax regime key selected for this account.
timezone string
IANA timezone used to determine the account's local date.
invoice_locale enum
Default language used when rendering invoices.
Possible values
en English.
es Spanish.
default_invoice_series object or null
Series used when invoice issuance omits series, or null if none is configured.
default_credit_note_series object or null
Series used for credit notes created by amendments, or null if none is configured.
default_amendment_series object or null
Series used for replacement invoices created by amendments, or null if none is configured.
created_at string
When the account was created.
updated_at string
When the account was last updated.
Account object 
{
  "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 string required
The opaque ID of the account.
Responses

200 An Account object. JSON

Example request
curl --request GET \
  'https://api.fiscalrail.com/v1/accounts/acct_14Vxtqg2nwvPR75TpsGH8N' \
  --header "Authorization: Bearer ak_test_..."
Example response — 200 
{
  "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. JSON

Example request
curl --request GET \
  'https://api.fiscalrail.com/v1/accounts' \
  --header "Authorization: Bearer ak_test_..."
Example response — 200 
{
  "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"
    }
  ]
}