# 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 under `default_series`. It also controls invoice numbering for every series through `invoice_numbering_scope`.

`default_payment_instructions` is an ordered array of Payment Instruction IDs. When invoice issuance omits `payment_terms.options`, FiscalRail snapshots those instructions onto the invoice in that order. Set the array to `[]` to disable account defaults.

The `live` boolean identifies whether the account contains live or test data. Updating `default_series` replaces all three defaults atomically, so the object must include `invoice`, `credit_note`, and `amendment`. Use `null` for an optional default that is not configured.

`account` numbering uses one sequence per configured series. `customer` numbering appends the customer's invoice prefix to generated codes and keeps an independent sequence for each series and customer; customerless invoices continue on the base sequence. This changes future numbering only and applies to every series in the account.

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.


#### `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.

#### `invoice_numbering_scope`

Type: `enum`

Account uses one sequence per configured series. Customer appends the customer's invoice prefix to generated codes and maintains an independent sequence for each series and customer; customerless invoices use the base sequence. Defaults to `account`.

Possible values:

- `account` — 
- `customer` — 

#### `default_series`

Type: `object`

Series used by each invoice operation when no explicit series is supplied.

##### `default_series.invoice`

Type: `string`

Series used when invoice issuance omits `series`.

##### `default_series.credit_note`

Type: `object or null`

Series used for credit notes created by amendments, or null if none is configured.

##### `default_series.amendment`

Type: `object or null`

Series used for replacement invoices created by amendments, or null if none is configured.


#### `default_payment_instructions`

Type: `array of strings`

Ordered payment instructions used when invoice issuance omits `payment_terms.options`. The first instruction is preferred.

#### `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"
  },
  "tax_regime": "es",
  "timezone": "Europe/Madrid",
  "invoice_locale": "es",
  "invoice_numbering_scope": "account",
  "default_series": {
    "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "credit_note": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR",
    "amendment": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS"
  },
  "default_payment_instructions": [
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT"
  ],
  "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 requests

#### Python

```python
import os

from fiscalrail import FiscalRail

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

account = client.accounts.retrieve(
    "acct_14Vxtqg2nwvPR75TpsGH8N",
)
```

#### cURL

```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"
  },
  "tax_regime": "es",
  "timezone": "Europe/Madrid",
  "invoice_locale": "es",
  "invoice_numbering_scope": "account",
  "default_series": {
    "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "credit_note": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR",
    "amendment": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS"
  },
  "default_payment_instructions": [
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT"
  ],
  "created_at": "2026-07-31T09:00:00Z",
  "updated_at": "2026-07-31T09:00:00Z"
}
```

## Update account invoicing settings

`PATCH /v1/accounts/{id}`

Updates invoice numbering or atomically replaces account invoicing defaults.

### Path parameters

#### `id`

Type: `string` — required

The opaque ID of the account.


### Request body

#### `invoice_numbering_scope`

Type: `enum`

Account uses one sequence per configured series. Customer appends the customer's invoice prefix to generated codes and maintains an independent sequence for each series and customer; customerless invoices use the base sequence. Defaults to `account`.

Possible values:

- `account` — 
- `customer` — 

#### `default_series`

Type: `object`

Complete replacement for the account's three default series assignments.

##### `default_series.invoice`

Type: `string` — required

Series used when invoice issuance omits `series`.

##### `default_series.credit_note`

Type: `object or null` — required

Series used for credit notes created by amendments, or null if none is configured.

##### `default_series.amendment`

Type: `object or null` — required

Series used for replacement invoices created by amendments, or null if none is configured.


#### `default_payment_instructions`

Type: `array of strings`

Complete ordered replacement for the account's default payment instructions. Every instruction must belong to the account.


### Responses

- `200` — [The updated Account object.](#the-account-object) Formats: JSON.

### Example requests

#### Python

```python
import os

from fiscalrail import FiscalRail

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

account = client.accounts.update(
    "acct_14Vxtqg2nwvPR75TpsGH8N",
    invoice_numbering_scope="customer",
    default_series={
        "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
        "credit_note": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR",
        "amendment": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS",
    },
    default_payment_instructions=[
        "pay_ins_14Vxtqm9KHu4rP3eZyN8gT",
    ],
)
```

#### cURL

```bash
curl --request PATCH \
  'https://api.fiscalrail.com/v1/accounts/acct_14Vxtqg2nwvPR75TpsGH8N' \
  --header "Authorization: Bearer ak_test_..." \
  --json '{
  "invoice_numbering_scope": "customer",
  "default_series": {
    "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "credit_note": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR",
    "amendment": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS"
  },
  "default_payment_instructions": [
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT"
  ]
}'
```

### 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"
  },
  "tax_regime": "es",
  "timezone": "Europe/Madrid",
  "invoice_locale": "es",
  "invoice_numbering_scope": "account",
  "default_series": {
    "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
    "credit_note": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR",
    "amendment": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS"
  },
  "default_payment_instructions": [
    "pay_ins_14Vxtqm9KHu4rP3eZyN8gT"
  ],
  "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 requests

#### Python

```python
import os

from fiscalrail import FiscalRail

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

accounts = client.accounts.list()
```

#### cURL

```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"
      },
      "tax_regime": "es",
      "timezone": "Europe/Madrid",
      "invoice_locale": "es",
      "invoice_numbering_scope": "account",
      "default_series": {
        "invoice": "inv_ser_14Vxtqg4QFd6rL8cUoK3sZ",
        "credit_note": "inv_ser_14Vxtqj7HFs2pM9cXwL6eR",
        "amendment": "inv_ser_14Vxtqk8JGt3qN2dYxM7fS"
      },
      "default_payment_instructions": [
        "pay_ins_14Vxtqm9KHu4rP3eZyN8gT"
      ],
      "created_at": "2026-07-31T09:00:00Z",
      "updated_at": "2026-07-31T09:00:00Z"
    }
  ]
}
```