Skip to content

InvoiceXpress API (3.1.0)

The InvoiceXpress v3 API: invoicing documents (invoices, guides, estimates) and their series, clients, items, taxes, schedules and favorites; account, user, AT-communication and payment-service settings; batch CSV imports of invoices, products and clients; dashboard KPIs, reports, SAF-T export, digital signatures, EDI (CIUS-PT), Social Security declarations, and reference lists (currencies, tax countries, phone calling codes).

What changed between versions of this reference is listed under Changelog, at the end of the navigation.

Authentication

Send your api_key as a query parameter on JSON (or XML) requests. A request with no valid api_key answers 401. The Authorization: Bearer and X-Account headers authenticate the InvoiceXpress web app only; they are not meant for API clients. Endpoints marked as public need no key.

Download OpenAPI description
Overview
InvoiceXpress API Support
Languages
Servers
Production Server
https://api-v3.app.invoicexpress.com/

Invoices

Create invoices, invoice receipts, simplified invoices, vat moss invoices, credit notes & debit notes and send them to your clients.

Operations

Guides

Create shippings, transports & devolutions and send them to your clients.

Operations

Estimates

Create quotes, proformas and fees notes and send them to your clients.

Operations

Sequences

A Sequence is used to group invoices in a sequential order.

Operations

Clients

A Client is an entity you send invoices to.

Operations

Accounts

Manage your InvoiceXpress account settings, users, AT communication, and billing.

Operations

Account Credentials

Manage AT communication credentials for your account.

Operations

Collection Alerts

Configure automated payment collection alerts sent to clients.

Operations

Batch Invoices

Bulk-create invoices from a CSV file. Flow — GET batch → upload → process → mapping → configure_options → configure → validate → validation → available_docs → POST create → status. DELETE to discard.

Operations

Get Current Batch Invoice Job

Request

Returns the most recent non-expired batch invoice metadata. Returns 204 if no active batch exists.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices?api_key=YOUR_API_KEY"

Responses

SUCCESS — Returns the active batch invoice metadata

Bodyapplication/json
importobject(V3ImportBatchMetadata)
Response
application/json
{ "import": { "batch_metadata_id": 123, "batch_name": "My import batch", "status": "validated", "date": "2026-06-08T15:19:10.902Z", "expires_at": "2026-06-08T15:19:10.902Z", "doc_type": "invoices", "doc_status": "draft", "sequence_id": 12345, "sequence": "FAT 2024", "send_by_email": false, "header": "t", "separator": ",", "filename": "import.csv", "exemption_reason_id": null, "discount_type": null } }

Start Batch Invoice Creation

Request

Enqueues a background job to create invoices from validated batch previews. Requires an active batch in "validated" status.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices?api_key=YOUR_API_KEY"

Responses

ACCEPTED — Batch invoice job enqueued

Bodyapplication/json
importobject
Response
application/json
{ "import": { "job_id": "abc123def456", "message": "Import job enqueued" } }

Delete Active Batch Invoice Job

Request

Destroys the currently active batch invoice job and associated S3 files.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X DELETE "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices?api_key=YOUR_API_KEY"

Responses

NO CONTENT — Batch destroyed successfully

Response
No content

Get Batch Invoice CSV Template

Request

Returns a presigned S3 URL to download the batch invoice CSV template. Language matches the account language (en, es, pt).

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/template?api_key=YOUR_API_KEY"

Responses

SUCCESS — JSON with presigned download URL

Bodyapplication/json
templateobject
Response
application/json
{ "template": { "url": "https://s3.amazonaws.com/bucket/template.csv?signed=..." } }

Get Batch Invoice Configuration Options

Request

Returns data for populating the configure step dropdowns (sequences, exemption reasons). Only series registered with the AT are listed.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/configure_options?api_key=YOUR_API_KEY"

Responses

SUCCESS — Configuration options returned

Bodyapplication/json
sequencesArray of objects
exemption_reasonsArray of objects
Response
application/json
{ "sequences": [ { … } ], "exemption_reasons": [ { … } ] }

Upload CSV for Batch Invoice Import

Request

Validates the CSV file and uploads it to S3. Creates a new batch metadata record.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodymultipart/form-datarequired
filestring(binary)required

CSV file to import (max 10 MB)

curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/upload?api_key=YOUR_API_KEY" -F "file=@import.csv"

Responses

CREATED — File uploaded successfully

Bodyapplication/json
importobject
Response
application/json
{ "import": { "batch_metadata_id": 0, "batch_name": "My import", "status": "started", "date": "2026-06-08T15:19:10.902Z", "expires_at": "2026-06-08T15:19:10.902Z", "doc_type": "invoices", "doc_status": "draft", "sequence_id": 12345, "sequence": "", "send_by_email": false, "header": null, "separator": null, "filename": "import.csv", "exemption_reason_id": null, "discount_type": null } }

Process Uploaded CSV (Batch Invoice Mapping)

Request

After uploading, call this with separator and header info to build the column mapping.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
processobjectrequired
process.​separatorstring

Column separator. auto detects it from the first line. The value is lowercased before matching (e.g. TAB works as tab).

Default "auto"
Enum"auto"",""comma"";""semicolon""\t""tab""|""pipe"
Example: "auto"
process.​exclude_first_lineboolean
Example: false
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/process?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{"process":{"separator":"auto","exclude_first_line":true}}'

Responses

CREATED — Batch processed, mapping returned

Bodyapplication/json
importobject
Response
application/json
{ "import": { "batch_metadata_id": 0, "batch_name": "My import", "status": "mapping", "date": "2026-06-08T15:19:10.908Z", "expires_at": "2026-06-08T15:19:10.908Z", "doc_type": null, "doc_status": null, "sequence_id": null, "sequence": null, "send_by_email": false, "header": "t", "separator": ",", "filename": "import.csv", "exemption_reason_id": null, "discount_type": null, "mapping": { … } } }

Get CSV Column Mapping

Request

Returns the CSV column-to-field mapping for the active batch invoice job.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/mapping?api_key=YOUR_API_KEY"

Responses

OK — Returns the header mapping

Bodyapplication/json
mappingobject
Response
application/json
{ "mapping": { "client": { … }, "document": { … }, "items": [ … ], "cells": [ … ] } }

Save CSV Column Mapping

Request

Saves the user-selected column-to-field mapping for the active batch invoice job.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
mappingobject
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/mapping?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{}'

Responses

OK — Mapping saved successfully

Bodyapplication/json
mappingobject
Response
application/json
{ "mapping": { "client": { … }, "document": { … }, "items": [ … ], "cells": [ … ] } }

Configure Batch Invoice Job

Request

Updates the active batch invoice job with configuration options (name, document type, sequence, etc.) and transitions status to "configured".

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
configureobjectrequired
configure.​namestring<= 255 charactersrequired

Required (leading/trailing spaces are stripped). Must not be used by another document batch of the account ("Name is already used by another import batch"; blank → "Name can't be blank").

Example: "My import batch"
configure.​doc_typestring
Enum"invoices""invoice_receipts"
Example: "invoices"
configure.​doc_statusstring
Enum"draft""final"
Example: "draft"
configure.​sequence_idinteger

Must be a sequence of the account ("must belong to the current account"), of the same category as doc_type ("must match the selected document type") and registered at the tax authority ("must be a registered sequence"). See configure_options for the valid sequences.

Example: 12345
configure.​send_by_emailboolean
Example: false
configure.​exemption_reason_idinteger

Must be an existing exemption reason ("must be a valid exemption reason that exists").

Example: 1
configure.​discount_typestring
Enum"percentage""absolute"
Example: "percentage"
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/configure?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{}'

Responses

SUCCESS — Batch configured successfully

Bodyapplication/json
configureobject
Response
application/json
{ "configure": { "id": 123, "account_id": 0, "user_id": 0, "name": "My import batch", "status": "configured", "doc_type": "invoices", "doc_status": "draft", "filename": "import.csv", "import_type": "invoices", "separator": ",", "header": "t", "created_at": "2026-06-08T15:19:10.908Z", "updated_at": "2026-06-08T15:19:10.908Z", "expires_at": "2026-06-08T15:19:10.908Z", "sequence_id": 12345, "send_by_email": false, "exemption_reason_id": 0, "discount_type": "percentage" } }

Start Batch Invoice CSV Validation

Request

Enqueues a background job to validate the CSV rows. Requires batch in "configured" status. Poll GET /api/v3/imports/invoices/validation for results.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/validate?api_key=YOUR_API_KEY"

Responses

ACCEPTED — Validation job enqueued

Bodyapplication/json
validateobject
Response
application/json
{ "validate": { "job_id": "abc123", "message": "Validation job enqueued" } }

Get Batch Invoice Validation Status

Request

Poll this after POST /api/v3/imports/invoices/validate to get validation status and result.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/validation?api_key=YOUR_API_KEY"

Responses

OK — Validation completed

Bodyapplication/json
validateobject
Response
application/json
{ "validate": { "success": true, "status": "completed", "message": "The validation has completed.", "valid_count": 10, "invalid_count": 2, "ignored_count": 0, "total_rows": 12, "download_url": null, "expires_at": "2026-06-08 15:19:10 +0100" } }

Check Document Quota

Request

Returns whether the account has enough document quota to create invoices from validated previews. Use before POST /api/v3/imports/invoices.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/available_docs?api_key=YOUR_API_KEY"

Responses

OK — Availability check result

Bodyapplication/json
available_docsobject
Response
application/json
{ "available_docs": { "success": true, "can_import": true, "required_count": 15, "remaining_documents": 100 } }

Get Batch Invoice Creation Status

Request

Poll after POST /api/v3/imports/invoices to check invoice creation progress. Status values — processing (202), sending_email (202), completed (200), failed / exception_occurred / interrupted (422), stuck/unknown (500). Every body carries a success boolean.

Security
apiKeyAuth
Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/status?api_key=YOUR_API_KEY"

Responses

OK — Batch invoice creation completed

Bodyapplication/json
statusobject
Response
application/json
{ "status": { "success": true, "status": "completed", "message": "The import has completed.", "total_rows": 0, "processed": 0, "created_count": 0, "failed_count": 0, "import": { … } } }

Batch Products

Bulk import products from a CSV file. Flow — GET index (optional) → upload → process → GET/PUT mapping → validate → validation → POST create → status. DELETE to discard.

Operations

Batch Clients

Bulk import clients from a CSV file. Flow — GET index (optional) → upload → process → GET/PUT mapping → validate → validation → POST create → status. DELETE to discard. No configure step.

Operations

Items

An Item is the product or service you invoice.

Operations

Schedules

Create and manage recurring document schedules.

Operations

Taxes

Manage tax rates for your account.

Operations

Current User

Manage the currently authenticated user's own profile, API key, linked accounts, and password recovery.

Operations

Currencies

List supported currencies and look up exchange rates between them.

Operations

Dashboard

Retrieve dashboard KPIs and analytics about your clients and invoicing activity.

Operations

Favorites

Save and reuse custom filter presets for documents and other list views.

Operations

Payment Services

Configure and manage the payment service integration used to collect payments for your invoices.

Operations

Phone Calling Codes

List all phone country calling codes.

Operations

Reports

Reporting endpoints — currently covers the balance-per-client report, its summary, and XLSX export.

Operations

SAF-T

Generate the SAF-T (Standard Audit File for Tax) export for your account.

Operations

Tax Countries

List all tax countries.

Operations

Digital signatures

Allows opt-in for available digital signature providers, manage its credentials, and sign invoices.

Operations

EDI

Manage electronic invoice (CIUS-PT) generation and its additional customs/delivery fields. Note these endpoints are served under /api/v1/edi/ on the v3 host, and address documents by a bare id with no document-type segment.

Operations

Social Security

Helps self-employed accounts (trabalhadores independentes and ENI) fill in the quarterly income declaration for Segurança Social. InvoiceXpress calculates the quarter's totals from your invoices and an estimate of the monthly contribution; you record what you reported.

This feature submits nothing to Segurança Social. You type the figures into Segurança Social Direta yourself. It only calculates and records.

Authentication is api_key only, and every endpoint is JSON only. The declaration endpoints are served under /services/v1/social_security/... and the settings and report endpoints under /api/v3/accounts/..., all on the v3 host.

Operations

Changelog

Changes to the documented contract of the InvoiceXpress API v3: endpoints, fields, enum values, status codes and behaviour you can observe as an integrator. The newest version is at the top.

The version number is the one shown at the top of this reference, and it follows these rules:

  • Minor (3.1.0): something was added, such as a new endpoint, field or enum value. Existing integrations keep working.
  • Patch (3.0.1): the documentation was corrected and now describes what the API already did. No behaviour changed.
  • The major version stays at 3. A change that would break existing integrations is released as a new API version, not as 4.0.0 of this one.