Documentation
Browse documentation

Account

Inspect and update the account selected by an API key.
View as Markdown

An API key selects one account and one environment. Retrieve it at /v1/account; no account ID is required in the path. The live field identifies Live or Test data.

Update business identity, contact information, and address through PATCH /v1/account. Issued invoices retain their supplier snapshot. Invoicing configuration has its own resource at /v1/account/invoicing.

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.
tax_regime string
Tax regime key selected for this account.
timezone string
IANA timezone used to determine the account's local date.
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"
  },
  "tax_regime": "es",
  "timezone": "Europe/Madrid",
  "created_at": "2026-07-31T09:00:00Z",
  "updated_at": "2026-07-31T09:00:00Z"
}

Retrieve the authenticated account

GET/v1/account

Returns the account selected by the API key.

Responses

200 An Account object. JSON

Example request
import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

account = client.account.retrieve()
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"
  },
  "tax_regime": "es",
  "timezone": "Europe/Madrid",
  "created_at": "2026-07-31T09:00:00Z",
  "updated_at": "2026-07-31T09:00:00Z"
}

Update the authenticated account

PATCH/v1/account

Updates business identity, contact information, or address. Issued invoices retain their immutable supplier snapshot.

Request body
name string
Legal or trading name.
email string or null
Contact email; null clears it.
phone string or null
Contact phone number; null clears it.
address object
Supplier address fields to update; omitted fields remain unchanged.
Show child propertiesHide child properties
line_1 string or null
A new primary street address. Null values are rejected.
line_2 string or null
New additional address information, or null to clear it.
city string or null
A new city or locality. Null values are rejected.
postal_code string or null
A new postal or ZIP code. Null values are rejected.
state string or null
A new state, province, or region, or null to clear it.
country string or null
A new ISO 3166-1 alpha-2 country code. Null values are rejected.
Responses

200 The updated Account object. JSON

Example request
import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

account = client.account.update(
    address={
        "line_1": "Clara del Rey 64",
        "line_2": "6\u00BAB",
    },
)
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"
  },
  "tax_regime": "es",
  "timezone": "Europe/Madrid",
  "created_at": "2026-07-31T09:00:00Z",
  "updated_at": "2026-07-31T09:00:00Z"
}

Invoicing settings

The invoicing resource controls PDF locale and footer, numbering scope, default series, and ordered default payment instructions. default_series replaces all three assignments when supplied. Use footer: null to clear the footer. An empty payment-instruction array removes all defaults.

A rendered PDF remains cached when these settings change. An older invoice whose PDF has not yet been rendered can use the new locale or footer.

The Account Invoicing object

Properties
object string
String identifying invoicing settings. Always account_invoicing.
locale enum
Default PDF language.
Possible values
en
es
footer string or null
PDF footer; null removes it.
numbering_scope enum
Invoice numbering scope for every series. Defaults to account.
Possible values
account
customer
default_series object
Complete default series assignments.
Show child propertiesHide child properties
invoice string
Series used when invoice issuance omits series.
credit_note object or null
Series used for credit notes created by amendments, or null if none is configured.
amendment object or null
Series used for replacement invoices created by amendments, or null if none is configured.
default_payment_instructions array of strings
Ordered payment instruction defaults.
Account Invoicing object 
{
  "object": "account_invoicing",
  "locale": null,
  "footer": null,
  "numbering_scope": "account",
  "default_series": {
    "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "credit_note": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "amendment": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ"
  },
  "default_payment_instructions": [
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT"
  ]
}

Retrieve invoicing settings

GET/v1/account/invoicing

Returns the selected account's invoicing configuration.

Responses

200 Account invoicing settings. JSON

Example request
import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

invoicing = client.account.invoicing.retrieve()
Example response — 200 
{
  "object": "account_invoicing",
  "locale": null,
  "footer": null,
  "numbering_scope": "account",
  "default_series": {
    "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "credit_note": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "amendment": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ"
  },
  "default_payment_instructions": [
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT"
  ]
}

Update invoicing settings

PATCH/v1/account/invoicing

Omitted fields remain unchanged. Default series and payment instructions are replaced atomically when supplied. Settings affect PDFs rendered after the update, including older invoices without a cached PDF.

Request body
locale enum
Default PDF language.
Possible values
en
es
footer string or null
PDF footer; null removes it.
numbering_scope enum
Invoice numbering scope for every series. Defaults to account.
Possible values
account
customer
default_series object
Complete default series assignments.
Show child propertiesHide child properties
invoice string required
Series used when invoice issuance omits series.
credit_note object or null required
Series used for credit notes created by amendments, or null if none is configured.
amendment object or null required
Series used for replacement invoices created by amendments, or null if none is configured.
default_payment_instructions array of strings
Ordered payment instruction defaults.
Responses

200 Updated account invoicing settings. JSON

Example request
import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

invoicing = client.account.invoicing.update(
    numbering_scope="customer",
)
Example response — 200 
{
  "object": "account_invoicing",
  "locale": null,
  "footer": null,
  "numbering_scope": "account",
  "default_series": {
    "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "credit_note": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "amendment": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ"
  },
  "default_payment_instructions": [
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT"
  ]
}