> ## 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. # List number series > Returns a cursor-paginated list of number series for the environment the API key belongs to, most recent first. Follow `next_url` to page through the rest. ## OpenAPI ````yaml /api-reference/openapi.json get /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: get: tags: - Number Series summary: List number series description: >- Returns a cursor-paginated list of number series for the environment the API key belongs to, most recent first. Follow `next_url` to page through the rest. operationId: listNumberSeries parameters: - name: limit in: query required: false description: Maximum number of number series to return (1–100). schema: default: 25 description: Maximum number of number series to return (1-100). example: 25 type: integer minimum: 1 maximum: 100 - name: starting_after in: query required: false description: 'Opaque cursor: return number series after this number series id.' schema: description: >- Cursor: return number series after this number series id. A cursor that points at a since-deleted series is rejected with `invalid_request`; restart from the first page by omitting this parameter. example: ns_clx123abc456 type: string responses: '200': description: A cursor-paginated page of number series. content: application/json: schema: $ref: '#/components/schemas/NumberSeriesList' '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 '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: NumberSeriesList: type: object properties: data: type: array items: $ref: '#/components/schemas/NumberSeries' has_more: type: boolean description: Whether more number series exist beyond this page. example: false next_cursor: anyOf: - type: string - type: 'null' description: >- Cursor to pass back as starting_after for the next page, or null on the last page. example: ns_clx123abc456 next_url: anyOf: - type: string - type: 'null' description: Relative path to the next page, or null on the last page. example: /v1/number_series?limit=25&starting_after=ns_clx123abc456 required: - data - has_more - next_cursor - next_url additionalProperties: false description: A cursor-paginated page of number series. 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). 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' securitySchemes: bearerAuth: type: http scheme: bearer description: API key sent as a bearer token in the `Authorization` header. ````