> ## Documentation Index > Fetch the complete documentation index at: https://www.finseed.es/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a number series > Creates a numbering series for the environment the API key belongs to. The prefix is normalized server-side (whitespace removed, letters uppercased) and must be unique in the environment. A series is immutable once created: to change how invoices are numbered, create a new series and issue on it instead. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/number_series openapi: 3.1.0 info: title: Finseed API version: 1.0.0 description: >- REST API for programmatic Verifactu invoicing. Every request is sent over HTTPS and authenticated with an API key passed as a bearer token. Each key is scoped to a single environment (test or live). Payloads are JSON with snake_case fields: amounts are integer minor units (cents) and timestamps are RFC 3339 in UTC. List endpoints are cursor-paginated. Errors return a small application/json envelope with a stable, machine-readable `code`. servers: - url: https://api.finseed.es security: - bearerAuth: [] paths: /v1/number_series: post: tags: - Number Series summary: Create a number series description: >- Creates a numbering series for the environment the API key belongs to. The prefix is normalized server-side (whitespace removed, letters uppercased) and must be unique in the environment. A series is immutable once created: to change how invoices are numbered, create a new series and issue on it instead. operationId: createNumberSeries parameters: - name: Idempotency-Key in: header required: false description: >- Optional key that makes the request safe to retry: 1 to 255 printable ASCII characters. Sending the same key with the same body within 24 hours returns the stored response instead of executing again; such a replay carries an `Idempotent-Replayed: true` header. Reusing a key with a different body is rejected. schema: type: string requestBody: description: The number series to create. required: true content: application/json: schema: $ref: '#/components/schemas/NumberSeriesCreateRequest' responses: '201': description: The created number series. content: application/json: schema: $ref: '#/components/schemas/NumberSeries' headers: Idempotent-Replayed: description: >- Present with value `true` only when this response is a stored replay of an earlier request that used the same `Idempotency-Key`. schema: type: string '400': description: >- The request was rejected during validation. The `errors` array lists each failing field with a reason, so you can map the failure back to a specific parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: invalid_request detail: >- The request is not valid. A parameter is missing, malformed, or out of range. See the `errors` array for the fields that failed. errors: [] doc_url: >- https://www.finseed.es/docs/api-reference/errors#invalid_request '401': description: >- Authentication failed: the API key is missing, malformed, or revoked. Send a valid key as a bearer token in the `Authorization` header. Each key is bound to a single environment (test or live). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: unauthorized detail: >- Authentication failed. Send your API key as a bearer token in the `Authorization` header. Keys are scoped to one environment, so a test key cannot read live data and vice versa. errors: [] doc_url: https://www.finseed.es/docs/api-reference/errors#unauthorized '409': description: >- Returned as `idempotency_conflict`: The supplied `Idempotency-Key` cannot be honored. This happens in three situations: the key was already used with a different request body; the original request with this key is still being processed, in which case retrying with the same key and body once it completes replays its response; or the original request ended in an unknown state, in which case the key stays blocked for up to 24 hours. If you never received a stored response, send the request again with a fresh key. Returned as `number_series_prefix_taken`: The prefix of the series being created is already taken in this environment. Prefixes are normalized before the uniqueness check (whitespace is removed and letters are uppercased), so two prefixes that only differ in casing or spacing are the same prefix. Pick a different prefix, or reuse the existing series. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: idempotency_conflict: summary: idempotency_conflict value: code: idempotency_conflict detail: >- This `Idempotency-Key` cannot be honored: it was already used with a different request body, the original request is still being processed, or that request ended in an unknown state. If the original is still running, retry with the same key and body once it completes to replay its response. If you never received a stored response, the key stays blocked for up to 24 hours; send the request again with a fresh key. errors: [] doc_url: >- https://www.finseed.es/docs/api-reference/errors#idempotency_conflict number_series_prefix_taken: summary: number_series_prefix_taken value: code: number_series_prefix_taken detail: >- A number series with this prefix already exists in this environment. Prefixes are normalized before the uniqueness check: whitespace is removed and letters are uppercased, so "fra" and "F RA" both collide with "FRA". errors: [] doc_url: >- https://www.finseed.es/docs/api-reference/errors#number_series_prefix_taken '500': description: >- An unexpected error occurred on our side. No partial work is persisted, so the request can be retried safely. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: code: internal_error detail: >- Something went wrong on our side. The request did not complete and can be retried safely. errors: [] doc_url: >- https://www.finseed.es/docs/api-reference/errors#internal_error components: schemas: NumberSeriesCreateRequest: type: object properties: prefix: type: string description: >- Prefix stamped on every invoice number of the series. Normalized server-side: whitespace is removed and letters are uppercased. After normalization it must be 1-20 characters using only A-Z letters (no accents or "Ñ"), digits, "_", "/", "." or "-", and must be unique in the environment. example: F first_value: description: The number the first invoice on this series takes. Defaults to 1. example: 1 type: integer minimum: 1 number_digits: description: >- Zero-padding width of the numeric part of the invoice number (0-12). Defaults to 0, meaning no padding. example: 5 type: integer minimum: 0 maximum: 12 type: description: >- What the series numbers: regular invoices (`standard`) or rectifying invoices (`rectifying`). Defaults to `standard`. example: standard type: string enum: - standard - rectifying required: - prefix additionalProperties: false description: The number series to create. example: prefix: F first_value: 1 number_digits: 5 NumberSeries: type: object properties: id: type: string description: Opaque, prefixed number series identifier. example: ns_clx123abc456 prefix: type: string description: >- Prefix stamped on every invoice number of this series, stored normalized: whitespace removed and letters uppercased. example: F type: type: string description: >- What the series numbers: regular invoices (`standard`) or rectifying invoices (`rectifying`). This is an extensible enum: new values may be added in the future, so clients must tolerate values not listed here. Known values: standard, rectifying. example: standard first_value: type: integer description: The number assigned to the first invoice on this series. example: 1 next_value: type: integer description: The number the next invoice on this series will take. example: 42 number_digits: type: integer description: >- Zero-padding width of the numeric part of the invoice number. 0 means no padding. example: 5 is_default: type: boolean description: >- Whether this is the default series of the environment. Read-only: only the series seeded with the environment can be the default. example: false created_at: type: string description: Creation timestamp, RFC 3339 in UTC. example: '2026-06-01T09:30:00Z' required: - id - prefix - type - first_value - next_value - number_digits - is_default - created_at additionalProperties: false description: >- An invoice numbering series as exposed by the public API. Invoice numbers are always assigned by the server: prefix plus a gapless, zero-padded counter. A series is immutable once created. example: id: ns_clx123abc456 prefix: F type: standard first_value: 1 next_value: 42 number_digits: 5 is_default: false created_at: '2026-06-01T09:30:00Z' ErrorEnvelope: type: object properties: code: type: string description: >- Stable, machine-readable error code. The branch key. This is an extensible enum: new values may be added in the future, so clients must tolerate values not listed here. Known values: invalid_request, unauthorized, invoice_not_found, download_link_expired, number_series_not_found, number_series_prefix_taken, number_series_in_use, customer_not_found, customer_ambiguous, idempotency_conflict, rate_limited, invalid_number_series, invalid_tax_rate, invalid_tax_data, invalid_tax_id, tax_id_type_country_mismatch, insufficient_recipient_data, simplified_amount_exceeded, simplified_incompatible_tax_type, invalid_recargo_equivalencia, aeat_mandate_not_approved, no_active_subscription, tax_id_validation_unavailable, invalid_rectifies_reference, rectified_invoice_not_found, invoice_already_voided, invoice_already_replaced, invoice_not_family_tip, invoice_pending_at_aeat, invoice_not_rectifiable_at_aeat, family_balance_below_zero, replacement_total_negative, reason_incompatible_with_recipient, recipient_overrides_not_allowed_for_differences, rectifying_series_invalid, external_reference_invalid, external_reference_matches_existing_invoice, rectified_amounts_required_for_substitution, line_item_without_tax_items, internal_error. example: invalid_request detail: type: string description: Human-readable, context-specific explanation. example: The query parameters are not valid. errors: type: array items: type: object properties: field: type: string description: Location of the offending value (JSON path). example: limit code: type: string description: Machine-readable validation issue code. example: too_big message: type: string description: Human-readable explanation of the field-level issue. example: Number must be less than or equal to 100 required: - field - code - message additionalProperties: false description: >- Field-level issues. Always present; empty unless this is a validation failure. doc_url: type: string description: Link to the reference documentation for this error code. example: https://www.finseed.es/docs/api-reference/errors#invalid_request required: - code - detail - errors - doc_url additionalProperties: false description: >- Uniform error body returned for every non-2xx response (application/json). securitySchemes: bearerAuth: type: http scheme: bearer description: API key sent as a bearer token in the `Authorization` header. ````