The Invoys API is organized around REST principles. The API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Welcome to the API documentation for Invoys Accounts Payable and Accounts Receivable Automation solutions. Invoys offers a robust set of tools to enhance both Accounts Payable and Accounts Receivable operations, empowering your business with efficiency, accuracy, and security.
Below are presented the sequence diagrams of interaction between your system and Invoys API.
Create a company profile to establish secure connection between Invoys and your destination system.
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
Company details
company_name required | string The company name. |
name required | string The contact name. |
email required | string The contact email. |
country required | string The two-letter ISO 3166-1 alpha-2 code representing the company's country. Must be UPPERCASE. |
address | string Company's address. |
website | string Company's website. |
phone | string Company's contact phone number. |
primary_color | string Company's primary color in HEX used for branding the Invoys links and invoices. |
logo_url | string <url> Company's URL to logo used for branding the Invoys links and invoices. |
{- "company_name": "Acme",
- "name": "John Doe",
- "email": "john.doe@acme.com",
- "country": "RO",
- "primary_color": "#FFA500",
}
{- "message": "Created",
- "company_id": "09dcc7ac-ffd0-4eed-bdb3-3e6d7fdaab19",
- "client_id": "9a76d0e8-a761-4da9-bad8-c364ec3274ff",
- "client_secret": "S6iIcz5zfBVZFsb7ZOSnKEGwbasqonvF47NUHRoa",
}
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
Company details
primary_color | string Company's primary color in HEX used for branding the Invoys links and invoices. |
logo_url | string <url> Company's URL to logo used for branding the Invoys links and invoices. |
{- "primary_color": "#FFA500",
}
{- "message": "Created",
- "company_id": "09dcc7ac-ffd0-4eed-bdb3-3e6d7fdaab19",
- "primary_color": "#FFA500",
}
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
client_id required | string The client ID. |
client_secret required | string The client secret. |
grant_type required | string The grant type. Must be equal to 'client_credentials' |
{- "token_type": "Bearer",
- "expires_in": 31622400,
- "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlNhbXBsZSB0b2tlbiIsImlhdCI6MTUxNjIzOTAyMn0.8HfuypQb9AyJZnaOTtBtxt2bReHjJskMyIRrfUUpQKM"
}
When the registration status is registered
and consent status is confirmed
, then it indicates that the connection is successfully established and from this point invoices can be processed.
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
{- "company_status": "unregistered",
- "system_consent_status": "unconfirmed"
}
Get the full list of available applications for a company.
category | string Enum: "delivery" "import" Category of applications. |
string Email of the counterparty user. | |
company_name | string Company name of the counterparty. |
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
{- "applications": [
- {
- "id": "6dd33f77-3906-48fa-ac54-a1379a26d369",
- "name": "Invoice Recognition",
- "status": "activated",
- "consent_id": "64598398-198b-4aa8-9bb8-b3d26ed329a2",
- "category": "import"
}, - {
- "id": "741e17a6-0126-41bb-9896-8698d3512b9f",
- "name": "Email",
- "status": "default",
- "category": "delivery"
}
]
}
Get the redirect URL to the App Redirect UI where the user can activate notification channels.
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
return_url | string <url> The URL where the user will be redirected after finalizing the interaction with the App Redirect. |
{
}
Create the consent to activate a specific application for a company.
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
object The additional configuration relevant for activated application. | |||
|
{- "config": {
- "trusted_emails": [
- "email1@email.com",
- "email2@email.com",
- "email3@email.com"
]
}
}
{- "id": "1c3ed75b-204f-448e-a302-fb4da6e98ba1",
- "connected_at": "2023-06-04T12:22:23Z",
- "status": "confirmed",
- "is_active": true,
- "config": {
- "inbox_address": "5426b06ao7506@inbox.invoys.io",
- "trusted_emails": [
- "email1@email.com",
- "email2@email.com"
]
}, - "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf"
}
Update the configuration for a company's specific application that was activated.
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
required | object The additional configuration relevant for activated application. | ||
|
{- "config": {
- "trusted_emails": [
- "email1@email.com",
- "email2@email.com",
- "email3@email.com"
]
}
}
{- "id": "1c3ed75b-204f-448e-a302-fb4da6e98ba1",
- "connected_at": "2023-06-04T12:22:23Z",
- "status": "confirmed",
- "is_active": true,
- "config": {
- "inbox_address": "5426b06ao7506@inbox.invoys.io",
- "trusted_emails": [
- "email1@email.com",
- "email2@email.com",
- "email3@email.com"
]
}, - "company_id": "b2e6a1c3-1a5e-44ae-a8fd-81f76fd715cf"
}
Revoke the consent to deactivate the specified application for the company.
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
{- "id": "4707b026-21ca-449e-9b40-c8c6c0d4f404",
- "message": "Bad Request",
- "errors": [
- {
- "detail": "The 'Vendor-Software-Version' header is required."
}
]
}
Upload a document to be processed via OCR.
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
file required | string <binary> The file attempted to be uploaded must be a file of type .PDF, .JPG, .PNG. |
document_type | string Enum: "invoice" "receipt" The document type. |
{- "status": "processing",
- "id": "52857f07-72e5-493d-9153-52e30c2d8719",
- "created_at": "2024-04-06T10:48:50.966234Z",
}
Create an invoice, get recognized invoice data and delete after successfully fetching all needed data.
Get full list of processed invoices under the established connection.
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
[- {
- "id": "a9321020-93ba-45c1-8d26-1528427de127",
- "created_at": "2024-02-20T23:03:10.000000Z",
}, - {
- "id": "b629775d-72d2-4b4f-8e4a-23af9f3b42c8",
- "created_at": "2024-02-21T20:46:32.000000Z",
}
]
Create an invoice record along with associated Invoys link.
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
direction required | string Enum: "incoming" "outgoing" The direction of the invoice. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
required | object Container for the invoice data. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
{- "direction": "outgoing",
- "data": {
- "invoice": {
- "number": "12345",
- "issuing_date": "2023-10-01",
- "due_date": "2023-12-01",
- "total_amount": "999.00",
- "subtotal_amount": "900.00",
- "tax_amount": "100.00",
- "currency_code": "EUR"
}, - "seller": {
- "name": "Company A",
- "business_number": "IT12345678901",
- "vat_number": "IT12345678901",
- "address": {
- "adress_line": "str. ABC, Milano 20100, IT",
- "country_code": "IT",
- "postal_code": "20100"
}, - "email": "email@company-a.com",
- "website": "www.company-a.com",
- "bank_details": {
- "iban": "IT60X0542811101000000123456",
- "swift": "AAAA-BB-CC-123"
}
}, - "buyer": {
- "name": "Company B",
- "business_number": "DE123456789",
- "vat_number": "DE123456789",
- "billing_address": {
- "adress_line": "str. DCE, Berlin 10117, DE",
- "country_code": "DE",
- "postal_code": "10117"
}, - "delivery_address": {
- "adress_line": "str. FGH, Berlin 10115, DE",
- "country_code": "DE",
- "postal_code": "10115"
}, - "email": "email@company-b.com"
}, - "items": [
- {
- "description": "Item 1",
- "code": "00012345678901",
- "date": "2023-10-01",
- "unit": "Kg",
- "unit_price": "100",
- "quantity": "10",
- "tax_amount": "100.00",
- "discount": "1.00",
- "total_price": "999.00"
}
]
}
}
{- "data": {
- "invoice": {
- "number": {
- "value": "12345",
- "raw": "12345",
- "confidence": 1
}, - "issuing_date": {
- "value": "2023-10-01",
- "raw": "01/10/2023",
- "confidence": 1
}, - "due_date": {
- "value": "2023-12-01",
- "raw": "01/12/23",
- "confidence": 1
}, - "total_amount": {
- "value": "999.00",
- "raw": "999,00",
- "confidence": 1
}, - "subtotal_amount": {
- "value": "900.00",
- "raw": "900,00",
- "confidence": 1
}, - "tax_amount": {
- "value": "100.00",
- "raw": "100,00",
- "confidence": 1
}, - "currency_code": {
- "value": "EUR",
- "raw": "EUR",
- "confidence": 1
}
}, - "seller": {
- "name": {
- "value": "Company A",
- "raw": "Company A",
- "confidence": 1
}, - "business_number": {
- "value": "IT12345678901",
- "raw": "IT12345678901",
- "confidence": 1
}, - "vat_number": {
- "value": "IT12345678901",
- "raw": "IT12345678901",
- "confidence": 1
}, - "address": {
- "value": "str. ABC, Milano 20100, IT",
- "raw": "str. ABC, Milano 20100, IT",
- "confidence": 1,
- "country_code": "IT",
- "postal_code": "20100"
}, - "email": {
- "value": "email@company-a.com",
- "raw": "email@company-a.com",
- "confidence": 1
}, - "website": {
- "value": "www.company-a.com",
- "raw": "www.company-a.com",
- "confidence": 1
}, - "bank_details": {
- "iban": {
- "value": "IT60X0542811101000000123456",
- "raw": "IT60X0542811101000000123456",
- "confidence": 1
}, - "swift": {
- "value": "AAAA-BB-CC-123",
- "raw": "AAAA-BB-CC-123",
- "confidence": 1
}
}
}, - "buyer": {
- "name": {
- "value": "Company B",
- "raw": "Company B",
- "confidence": 1
}, - "business_number": {
- "value": "DE123456789",
- "raw": "DE123456789",
- "confidence": 1
}, - "vat_number": {
- "value": "DE123456789",
- "raw": "DE123456789",
- "confidence": 1
}, - "billing_address": {
- "value": "str. DCE, Berlin 10117, DE",
- "raw": "str. DCE, Berlin 10117, DE",
- "confidence": 1,
- "country_code": "DE",
- "postal_code": "10117"
}, - "delivery_address": {
- "value": "str. FGH, Berlin 10115, DE",
- "raw": "str. FGH, Berlin 10115, DE",
- "confidence": 1,
- "country_code": "DE",
- "postal_code": "10115"
}, - "email": {
- "value": "email@company-b.com",
- "raw": "email@company-b.com",
- "confidence": 1
}
}, - "items": [
- {
- "description": {
- "value": "Item 1",
- "raw": "Item 1",
- "confidence": 1
}, - "code": {
- "value": "00012345678901",
- "raw": "00012345678901",
- "confidence": 1
}, - "date": {
- "value": "2023-10-01",
- "raw": "01/10/2023",
- "confidence": 1
}, - "unit": {
- "value": "Kg",
- "raw": "Kg",
- "confidence": 1
}, - "unit_price": {
- "value": 100,
- "raw": "100,00",
- "confidence": 1
}, - "quantity": {
- "value": 10,
- "raw": "10",
- "confidence": 1
}, - "tax_amount": {
- "value": "100.00",
- "raw": "100,00",
- "confidence": 1
}, - "discount": {
- "value": "1.00",
- "raw": "1,00",
- "confidence": 1
}, - "total_price": {
- "value": 999,
- "raw": "999,00",
- "confidence": 1
}
}
]
}, - "meta": {
- "id": "01he6q5348xtq3df6cad1g6196",
- "action": "api-import",
- "version": 2,
- "created_at": "2023-11-02T18:53:29.687575Z",
- "confirmed": {
- "confirmed_at": "2024-01-08T10:37:39.656093Z",
- "status": true
}, - "status": "created",
- "direction": "outgoing",
- "link": {
- "id": "e2376749-b724-4853-af4c-94fcec2a0ceb",
}
}
}
Get detailed information for a specific invoice which was processed.
id required | string The invoice ID. |
include_raw | boolean The indicator to return the raw data in the response. |
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
{- "data": {
- "invoice": {
- "number": {
- "value": "12345",
- "raw": "12345",
- "confidence": 0.974
}, - "issuing_date": {
- "value": "2023-10-01",
- "raw": "01/10/2023",
- "confidence": 0.942
}, - "due_date": {
- "value": "2023-12-01",
- "raw": "01/12/23",
- "confidence": 0.954
}, - "total_amount": {
- "value": "1000.00",
- "raw": "1000,00",
- "confidence": 0.913
}, - "subtotal_amount": {
- "value": "900.00",
- "raw": "900,00",
- "confidence": 0.913
}, - "tax_amount": {
- "value": "100.00",
- "raw": "100,00",
- "confidence": 0.913
}, - "currency_code": {
- "value": "EUR",
- "raw": "EUR",
- "confidence": 0.974
}, - "payment_reference": {
- "value": "PRJ-2024-XYZ",
- "raw": "PRJ-2024-XYZ",
- "confidence": 0.974
}
}, - "seller": {
- "name": {
- "value": "Company A",
- "raw": "Company A",
- "confidence": 0.974
}, - "business_number": {
- "value": "IT12345678901",
- "raw": "IT12345678901",
- "confidence": 0.974
}, - "vat_number": {
- "value": "IT12345678901",
- "raw": "IT12345678901",
- "confidence": 0.974
}, - "address": {
- "value": "str. ABC, Milano 20100, IT",
- "raw": "str. ABC, Milano 20100, IT",
- "confidence": 0.974,
- "country_code": "IT",
- "postal_code": "20100"
}, - "email": {
- "value": "email@company-a.com",
- "raw": "email@company-a.com",
- "confidence": 0.974
}, - "website": {
- "value": "www.company-a.com",
- "raw": "www.company-a.com",
- "confidence": 0.974
}, - "bank_details": {
- "iban": {
- "value": "IT60X0542811101000000123456",
- "raw": "IT60X0542811101000000123456",
- "confidence": 0.974
}, - "swift": {
- "value": "AAAA-BB-CC-123",
- "raw": "AAAA-BB-CC-123",
- "confidence": 0.974
}
}
}, - "buyer": {
- "name": {
- "value": "Company B",
- "raw": "Company B",
- "confidence": 0.974
}, - "business_number": {
- "value": "DE123456789",
- "raw": "DE123456789",
- "confidence": 0.974
}, - "vat_number": {
- "value": "DE123456789",
- "raw": "DE123456789",
- "confidence": 0.974
}, - "billing_address": {
- "value": "str. DCE, Berlin 10117, DE",
- "raw": "str. DCE, Berlin 10117, DE",
- "confidence": 0.974,
- "country_code": "DE",
- "postal_code": "10117"
}, - "delivery_address": {
- "value": "str. FGH, Berlin 10115, DE",
- "raw": "str. FGH, Berlin 10115, DE",
- "confidence": 0.974,
- "country_code": "DE",
- "postal_code": "10115"
}, - "email": {
- "value": "email@company-b.com",
- "raw": "email@company-b.com",
- "confidence": 0.974
}
}, - "items": [
- {
- "description": {
- "value": "Item 1",
- "raw": "Item 1",
- "confidence": 0.974
}, - "unit": {
- "value": "Kg",
- "raw": "Kg",
- "confidence": 0.974
}, - "unit_price": {
- "value": 100,
- "raw": "100,00",
- "confidence": 0.974
}, - "quantity": {
- "value": 10,
- "raw": "10",
- "confidence": 0.974
}, - "tax_amount": {
- "value": 100,
- "raw": "100",
- "confidence": 0.974
}, - "discount": {
- "value": 1,
- "raw": "1",
- "confidence": 0.974
}, - "total_price": {
- "value": 999,
- "raw": "999,00",
- "confidence": 0.974
}
}
]
}, - "meta": {
- "id": "01he6q5348xtq3df6cad1g6196",
- "action": "infrastructure-system-import",
- "version": 2,
- "created_at": "2023-11-02T18:53:29.687575Z",
- "confirmed": {
- "confirmed_at": "2024-01-08T10:37:39.656093Z",
- "status": true
}, - "status": "created",
- "direction": "outgoing",
- "link": {
- "id": "e2376749-b724-4853-af4c-94fcec2a0ceb",
}
}
}
After successfully fetching the invoice data, send a delete request to erase all invoice data.
id required | string The invoice ID. |
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
{- "id": "4707b026-21ca-449e-9b40-c8c6c0d4f404",
- "message": "Bad Request",
- "errors": [
- {
- "detail": "The 'Vendor-Software-Version' header is required."
}
]
}
Deliver the Invoys Link to the counterparty preferred communication channel and check its status.
Initiate sending of an Invoys Link to the counterparty via available delivery channels.
id required | string The Invoys link ID. |
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
application required | string The ID of the application via which the Invoys link will be sent. |
send_to required | string The email address or phone number to which the Invoys link will be sent. |
{- "application": "ba8ffbee-17c8-4bd8-aafe-9029a632a2dc",
- "send_to": "email@company-b.com"
}
{- "data": {
- "application": "ba8ffbee-17c8-4bd8-aafe-9029a632a2dc",
- "send_to": "email@company-b.com"
}, - "meta": {
- "id": "6bdd98d8-04de-40e6-b906-dda092fc12ab",
- "created_at": "2024-04-10T22:33:22.000000Z",
- "status": "created"
}
}
Get the details of an Invoys link.
id required | string The Invoys link ID. |
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
{- "data": {
- "application": "ba8ffbee-17c8-4bd8-aafe-9029a632a2dc",
- "send_to": "email@company-b.com"
}, - "meta": {
- "id": "6bdd98d8-04de-40e6-b906-dda092fc12ab",
- "created_at": "2024-04-10T22:33:22.000000Z",
- "status": "created"
}
}
Create subscriptions to receive notifications about events related to your processed documents.
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
Webhook details
url required | string The URL of the webhook endpoint. |
name | string The name of the subscription. |
events required | Array of strings Items Enum: "invoice.confirmed" "invoice.recognized" The list of events. |
{- "name": "Company Webhook",
- "events": [
- "invoice.confirmed"
]
}
{- "id": "ba8ffbee-17c8-4bd8-aafe-9129a632a2dc",
- "name": "Company Webhook",
- "events": [
- "invoice.confirmed"
], - "secret": "oquw39uNZHPBh2fU",
- "created_at": "2024-04-10T22:33:22.000000Z"
}
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
[- {
- "id": "ba8ffbee-17c8-4bd8-aafe-9129a632a2dc",
- "name": "Company Webhook",
- "events": [
- "invoice.confirmed"
], - "created_at": "2024-04-10T22:33:22.000000Z"
}
]
id required | string The ID of the subscription. |
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
Webhook details
url | string The URL of the webhook endpoint. |
name | string The name of the subscription. |
events | Array of strings Items Enum: "invoice.confirmed" "invoice.recognized" The list of events. |
{- "name": "Company Webhook",
- "events": [
- "invoice.confirmed"
]
}
{- "id": "ba8ffbee-17c8-4bd8-aafe-9129a632a2dc",
- "name": "Company Webhook",
- "events": [
- "invoice.confirmed"
], - "created_at": "2024-04-10T22:33:22.000000Z"
}
id required | string The ID of the subscription. |
Vendor-Id required | string The vendor ID. |
Vendor-Secret required | string The vendor secret. |
Vendor-Software-Version required | string The vendor software version. |
{- "id": "4707b026-21ca-449e-9b40-c8c6c0d4f404",
- "message": "Bad Request",
- "errors": [
- {
- "detail": "The 'Vendor-Software-Version' header is required."
}
]
}
X-Webhook-Secret required | string The shared secret. |
Webhook details
id required | string <uuid> The unique identifier of the event. |
event required | string Enum: "invoice.confirmed" "invoice.recognized" The event notification. |
document_id required | string <uuid> The unique identifier of the document to which the event relates. |
created_at required | string <date-time> The timestamp of the event notification. |
{- "id": "2f4a4b5d-0f28-41d3-9fe9-4ec3d8a06122",
- "event": "invoice.confirmed",
- "document_id": "9bd54aba-18b1-4194-9a66-3d52ccbc2b6e",
- "created_at": "2024-04-10T22:33:22.000000Z"
}