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

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

Get User

Request

Returns the current user. id must be the id of the caller.

Security
apiKeyAuth
Path
idstringrequired

User id. Must be the caller's own id.

Query
api_keystringrequired

Your API Key.

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

Responses

SUCCESS

Bodyapplication/json
userobject(V3UserObject)
Response
application/json
{ "user": { "id": 1, "name": "Jean Dias", "email": "john.doe@invoicexpress.com", "phone": "987654321", "phone_country_id": 1, "accepted_marketing": true } }

Update User

Request

Updates the current account user's profile.

The email (and login) cannot be changed here. user.email / user.login may be sent only with the current value; a different value rejects the whole request with 422. Email changes go through POST /api/v3/users/{id}/email_change.

user.name is saved as first_name. To change the password, send actual_password (current password), password and password_confirmation.

Security
apiKeyAuth
Path
idstringrequired

User id. Must be the caller's own id.

Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
Bodyapplication/jsonrequired
userobjectrequired

Required. An empty body (no user root and no top-level user field) returns 500; top-level user fields (e.g. first_name, phone) are wrapped into user automatically.

To change the password, send actual_password (current password), password and password_confirmation.

user.​namestring

Saved as first_name (it overrides first_name when both are sent). No enforced character limit (text column).

Example: "Jean Dias"
user.​first_namestring

Same field as name.

Example: "Jean"
user.​phone_country_idinteger

Id of the phone calling code (see Phone Calling Codes).

Example: 1
user.​emailstring<= 255 characters

Cannot be changed through this endpoint. Optional; if sent it must equal the user's current email (case-insensitive), otherwise the whole request is rejected with 422 "Email changes must be requested through POST /users/:id/email_change." The same applies to login. To change the email use POST /api/v3/users/{id}/email_change.

Example: "john.doe@invoicexpress.com"
user.​phonestring

No enforced character limit (text column).

Example: "987654321"
user.​accepted_marketingboolean
Example: true
user.​actual_passwordstring

Current password. Required to change the password (see above).

Example: "123456"
user.​passwordstring[ 12 .. 40 ] characters
Example: "yoDWznBeH5j$JP98"
user.​password_confirmationstring[ 12 .. 40 ] characters
Example: "yoDWznBeH5j$JP98"
curl -X PUT "https://api-v3.app.invoicexpress.com/api/v3/users/1?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{}'

Responses

SUCCESS

Bodyapplication/json
userobject(V3UserObject)
Response
application/json
{ "user": { "id": 1, "name": "Jean Dias", "email": "john.doe@invoicexpress.com", "phone": "987654321", "phone_country_id": 1, "accepted_marketing": true } }

Get User Api Key

Request

Returns the caller's API key for the current account. id must be the id of the caller.

Security
apiKeyAuth
Path
idstringrequired

User id. Must be the caller's own id.

Query
api_keystringrequired

Your API Key.

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

Responses

SUCCESS

Bodyapplication/json
account_namestring
Example: "companyname"
api_keystring
Example: "aa8e739bbcbb406c90eccbe0825e87c5c1c4c5a9"
Response
application/json
{ "account_name": "companyname", "api_key": "aa8e739bbcbb406c90eccbe0825e87c5c1c4c5a9" }

Create User Api Key

Request

Generates a new API key for the caller on the current account.

Warning: this regenerates the key. If the caller already has an API key, it is replaced and the old one stops working immediately, including the key used to make this request.

The id path parameter is ignored: the call always acts on the caller.

Security
apiKeyAuth
Path
idstringrequired

User id. Ignored; the call acts on the caller.

Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/users/1/api_key?api_key=YOUR_API_KEY" -H "Content-Type: application/json" --data '{}'

Responses

SUCCESS

Bodyapplication/json
account_namestring
Example: "companyname"
api_keystring
Example: "aa8e739bbcbb406c90eccbe0825e87c5c1c4c5a9"
Response
application/json
{ "account_name": "companyname", "api_key": "aa8e739bbcbb406c90eccbe0825e87c5c1c4c5a9" }

Delete User Api Key

Request

Removes the caller's API key on the current account, which disables API access for the caller on that account (including the key used to make this request) until a new key is created.

The id path parameter is ignored: the call always acts on the caller.

Security
apiKeyAuth
Path
idstringrequired

User id. Ignored; the call acts on the caller.

Query
api_keystringrequired

Your API Key.

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

Responses

NO CONTENT

Response
No content

Get User Accounts

Request

Returns the list of accounts the caller has access to. The id path parameter is ignored; the call always acts on the caller.

Security
apiKeyAuth
Path
idstringrequired

User id. Ignored; the call acts on the caller.

Query
api_keystringrequired

Your API Key.

Example: api_key=YOUR_API_KEY
curl -X GET "https://api-v3.app.invoicexpress.com/api/v3/users/1/accounts?api_key=YOUR_API_KEY"

Responses

SUCCESS

Bodyapplication/json
accountsArray of objects(V3UserAccountObject)
Response
application/json
{ "accounts": [ { … } ] }

Recover Password

Request

Sends a password reset link to the given user's email address. No authentication. Messages are in the language given by language (pt, en or es), Portuguese by default; the examples below are in English.

Bodyapplication/jsonrequired
languagestring

Optional. Language of the response messages. It can also be sent as a query parameter. Without it (or with another value) the messages use Portuguese (pt).

Enum"pt""en""es"
Example: "en"
userobjectrequired
user.​emailstring<= 255 charactersrequired

Missing or blank returns 422 "Enter your email address."

Example: "john.doe@invoicexpress.com"
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/users/recover_password" -H "Content-Type: application/json" --data '{}'

Responses

SUCCESS

Bodyapplication/json
messagestring
Example: "We've sent a link to reset your password to your email address."
Response
application/json
{ "message": "We've sent a link to reset your password to your email address." }

Reset Password

Request

Resets a user's password using the reset code sent by the recover password endpoint. No authentication. Messages are in the language given by language (pt, en or es); otherwise in the language of the user's account, or Portuguese. The examples below are in English.

Bodyapplication/jsonrequired
languagestring

Optional. Language of the response messages. It can also be sent as a query parameter. Without it (or with another value) the messages use the language of the user's account, or Portuguese (pt) when the reset code is invalid.

Enum"pt""en""es"
Example: "en"
userobjectrequired
user.​reset_codestringrequired
Example: "e72bfdaeb6d719ec975162f8dbbc6733297b0cb0d3d780f4c42163acfb5aa0502285dccacae0cab41d044c19ed21bd9c7c04b3c7eb8e58b16245e0a97e468dfe"
user.​passwordstring[ 12 .. 40 ] charactersrequired

New password. Must differ from the current one (Password can't be identical to the current one).

Example: "yoDWznBeH5j$JP98"
user.​password_confirmationstring[ 12 .. 40 ] charactersrequired

Must equal password (Password mismatch).

Example: "yoDWznBeH5j$JP98"
curl -X POST "https://api-v3.app.invoicexpress.com/api/v3/users/reset_password" -H "Content-Type: application/json" --data '{}'

Responses

SUCCESS

Bodyapplication/json
messagestring
Example: "Password successfully reset."
Response
application/json
{ "message": "Password successfully reset." }

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.