Invoys Public API (v1.0)

E-mail: support@invoys.io Terms of Service

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.

Introduction

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.

Invoice Management

The Accounts Payable module of Invoys API facilitates the automation of invoice processing by leveraging advanced Optical Character Recognition (OCR) technology. This solution allows you to extract invoice data, and securely deliver them to your destination system. Invoys supports multiple file types, including PDF, DOCX, PNG, JPG/JPEG and TXT.

Invoys Link

For streamlining the Accounts Receivable process, Invoys provides powerful tools to automate the generation and delivery of invoices. The API facilitates the creation of Invoys Links, which can be delivered to your counterparties through their preferred communication channels, including Slack, WhatsApp, Telegram, Email, and more. Instant notifications on invoice status changes keep you informed in real-time, enabling proactive and responsive actions.

Sequence diagrams

Below are presented the sequence diagrams of interaction between your system and Invoys API.

Invoice Management

Below is presented the sequence diagram of interaction between your system and Invoys API for operating the invoice data.

Managed Applications

Below is presented the sequence diagram of interaction between your system and Invoys API for managing the applications connected through Invoys.

API status

Returns the system status of the Invoys Public API service.

Check API status.

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Responses

Response samples

200
400
401

Content type

application/json

Example

Service is up

{"status": "UP"
}

Company

Create a company profile to establish secure connection between Invoys and your destination system.

Create a new company

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Request Body schema: application/json
required

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.

Responses

Request samples

Payload

Content type

application/json

{"company_name": "Acme",
"name": "John Doe",
"email": "john.doe@acme.com",
"country": "RO",
"primary_color": "#FFA500",
"logo_url": "https://companyA.com/logo.jpg"
}

Response samples

201
400
401
422

Content type

application/json

{"message": "Created",
"company_id": "09dcc7ac-ffd0-4eed-bdb3-3e6d7fdaab19",
"client_id": "9a76d0e8-a761-4da9-bad8-c364ec3274ff",
"client_secret": "S6iIcz5zfBVZFsb7ZOSnKEGwbasqonvF47NUHRoa",
"redirect_url": "https://app.invoys.io/vendor/connect?session_id=qNla8khPcLQElryA0NcYyzeGGaVYovcG8PCTRvqL"
}

Update existing company

Authorizations:

bearerAuth

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Request Body schema: application/json
required

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.

Responses

Request samples

Payload

Content type

application/json

{"primary_color": "#FFA500",
"logo_url": "https://companyA.com/logo.jpg"
}

Response samples

200
400
401
422

Content type

application/json

{"message": "Created",
"company_id": "09dcc7ac-ffd0-4eed-bdb3-3e6d7fdaab19",
"primary_color": "#FFA500",
"logo_url": "https://companyA.com/logo.jpg"
}

Get access token

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Request Body schema: application/x-www-form-urlencoded
required

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'

Responses

Response samples

200
400
401
422

Content type

application/json

{"token_type": "Bearer",
"expires_in": 31622400,
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlNhbXBsZSB0b2tlbiIsImlhdCI6MTUxNjIzOTAyMn0.8HfuypQb9AyJZnaOTtBtxt2bReHjJskMyIRrfUUpQKM"
}

Get connectivity status

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.

Authorizations:

bearerAuth

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Responses

Response samples

200
400
401

Content type

application/json

{"company_status": "unregistered",
"system_consent_status": "unconfirmed"
}

Application

Manage company's applications.

Get list of available applications

Get the full list of available applications for a company.

Authorizations:

bearerAuth

query Parameters

category	string Enum: "delivery" "import" Category of applications.
email	string Email of the counterparty user.
company_name	string Company name of the counterparty.

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Responses

Response samples

200
400
401

Content type

application/json

{"applications": [{"id": "6dd33f77-3906-48fa-ac54-a1379a26d369",
"name": "Invoice Recognition",
"logo": "https://app.invoys.io/img/applications/recognition.svg",
"status": "activated",
"consent_id": "64598398-198b-4aa8-9bb8-b3d26ed329a2",
"category": "import"
},
{"id": "741e17a6-0126-41bb-9896-8698d3512b9f",
"name": "Email",
"logo": "https://app.invoys.io/img/applications/email.svg",
"status": "default",
"category": "delivery"
}
]
}

App Redirect

Get the redirect URL to the App Redirect UI where the user can activate notification channels.

Authorizations:

bearerAuth

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Request Body schema: application/json
required

return_url

string <url>

The URL where the user will be redirected after finalizing the interaction with the App Redirect.

Responses

Request samples

Payload

Content type

application/json

{"return_url": "https://client-app.com"
}

Response samples

200
400
401
422

Content type

application/json

{"redirect_url": "https://app.invoys.io/appstore?token=12|nLVIZrI1wR9Kd8zZBLsvHhF8mMjWeDdKw2rNbc3A96d2a75d&return_url=https://client-app.com"
}

Activate an application

Create the consent to activate a specific application for a company.

Authorizations:

bearerAuth

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Request Body schema: application/json
required

object

The additional configuration relevant for activated application.

trusted_emails

Array of strings

The list of trusted email addresses from which Invoys will accept messages for providing the "Invoice Recognition" service.

Responses

Request samples

Payload

Content type

application/json

{"config": {"trusted_emails": ["email1@email.com",
"email2@email.com",
"email3@email.com"
]
}
}

Response samples

201
400
401
422

Content type

application/json

{"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 an application

Update the configuration for a company's specific application that was activated.

Authorizations:

bearerAuth

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Request Body schema: application/json
required

required

object

The additional configuration relevant for activated application.

trusted_emails

Array of strings

The list of trusted email addresses from which Invoys will accept messages for providing the "Invoice Recognition" service.

Responses

Request samples

Payload

Content type

application/json

{"config": {"trusted_emails": ["email1@email.com",
"email2@email.com",
"email3@email.com"
]
}
}

Response samples

200
400
401
422

Content type

application/json

{"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"
}

Deactivate an application

Revoke the consent to deactivate the specified application for the company.

Authorizations:

bearerAuth

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Responses

Response samples

400
401

Content type

application/json

{"id": "4707b026-21ca-449e-9b40-c8c6c0d4f404",
"message": "Bad Request",
"errors": [{"detail": "The 'Vendor-Software-Version' header is required."
}
]
}

Upload

Upload documents to securely extract data via OCR technology.

Upload a document

Upload a document to be processed via OCR.

Authorizations:

bearerAuth

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Request Body schema: multipart/form-data
required

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.

Responses

Response samples

200
400
401
422

Content type

application/json

{"status": "processing",
"id": "52857f07-72e5-493d-9153-52e30c2d8719",
"created_at": "2024-04-06T10:48:50.966234Z",
"document_url": "http://invoys.io/v1/invoices/52857f07-72e5-493d-9153-52e30c2d8719"
}

Invoice

Create an invoice, get recognized invoice data and delete after successfully fetching all needed data.

Get list of invoices

Get full list of processed invoices under the established connection.

Authorizations:

bearerAuth

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Responses

Response samples

200
400
401

Content type

application/json

[{"id": "a9321020-93ba-45c1-8d26-1528427de127",
"created_at": "2024-02-20T23:03:10.000000Z",
"invoice_url": "https://api.invoys.io/v1/invoices/01he6q5348xtq3df6cad1g6196"
},
{"id": "b629775d-72d2-4b4f-8e4a-23af9f3b42c8",
"created_at": "2024-02-21T20:46:32.000000Z",
"invoice_url": "https://api.invoys.io/v1/invoices/01hejegqdqd9cjt3xb7dfww3c4"
}
]

Create an invoice

Create an invoice record along with associated Invoys link.

Authorizations:

bearerAuth

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Request Body schema: application/json
required

direction

required

string

Enum: "incoming" "outgoing"

The direction of the invoice.
Incoming Invoice - refers to the document received by the organization from a counterparty on the basis of a purchased services or goods. In this case the organization is the 'buyer'.
Outgoing Invoice - refers to the document issued by the organization towards a counterparty on the basis of purchased services or goods. In this case the organization is the 'seller'.

required

object

Container for the invoice data.

required

object

Details of the invoice.

number required	string The actual invoice number.
issuing_date	string <date> Date when the invoice was issued in ISO 8601 format.
due_date required	string <date> Due date for payment of the invoice in ISO 8601 format.
total_amount required	string <number> Total amount of the invoice.
subtotal_amount	string <number> Subtotal amount of the invoice.
tax_amount	string <number> Tax amount of the invoice.
currency_code	string^[A-Z]{3}$ Currency code of the invoice amount.

required

object

Details of the seller (issuer) of the invoice.

name required	string The name of the seller.
business_number	string The business number of the seller.
vat_number	string The VAT number of the seller.
	object Seller's address.
email	string <email> Seller's email address.
website	string Seller's website URL.
	object Seller's bank details.

required

object

Details of the buyer (recipient) of the invoice.

name required	string Buyer's name.
business_number	string Buyer's business number.
vat_number	string Buyer's VAT number.
	object Buyer's billing address.
	object Buyer's delivery address.
email required	string <email> Buyer's email address.

required

Array of objects non-empty

List of items in the invoice.

Array (non-empty)

description	string Item description details.
code	string Code of the item.
date	string <date> Date of the item.
unit	string Unit of measurement for the item.
unit_price	string Unit price of the item.
quantity	string Quantity of the item.
tax_amount	string <number> Tax amount of the item.
discount	string <number> Discount amount of the item.
total_price	string Total price for the quantity of the item.

Responses

Request samples

Payload

Content type

application/json

{"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"
}
]
}
}

Response samples

201
400
401
422

Content type

application/json

{"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,
"original_file": "https://s3.eu-central-1.amazonaws.com/invoys-inbox/processed/21ssvfug71bvo7nh_invoice.pdf",
"created_at": "2023-11-02T18:53:29.687575Z",
"confirmed": {"review_url": "https://app.invoys.io/invoices/review/663a2ebb-8694-45c3-b78e-31c443bb0b7f",
"confirmed_at": "2024-01-08T10:37:39.656093Z",
"status": true
},
"status": "created",
"direction": "outgoing",
"link": {"id": "e2376749-b724-4853-af4c-94fcec2a0ceb",
"url": "https://app.invoys.io/link/e2376749-b724-4853-af4c-94fcec2a0ceb"
}
}
}

Get an invoice data

Get detailed information for a specific invoice which was processed.

Authorizations:

bearerAuth

path Parameters

id

required

string

The invoice ID.

query Parameters

include_raw

boolean

The indicator to return the raw data in the response.

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Responses

Response samples

200
400
401

Content type

application/json

{"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,
"original_file": "https://s3.eu-central-1.amazonaws.com/invoys-inbox/processed/21ssvfug71bvo7nh_invoice.pdf",
"created_at": "2023-11-02T18:53:29.687575Z",
"confirmed": {"review_url": "https://app.invoys.io/invoices/review/663a2ebb-8694-45c3-b78e-31c443bb0b7f",
"confirmed_at": "2024-01-08T10:37:39.656093Z",
"status": true
},
"status": "created",
"direction": "outgoing",
"link": {"id": "e2376749-b724-4853-af4c-94fcec2a0ceb",
"url": "https://app.invoys.io/link/e2376749-b724-4853-af4c-94fcec2a0ceb"
}
}
}

Update status of an invoice

Update the status for a specific invoice.

Authorizations:

bearerAuth

path Parameters

id

required

string

The invoice ID.

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Request Body schema: application/json
required

status

required

string

Enum: "paid" "partially_paid"

The status of the invoice.

Responses

Request samples

Payload

Content type

application/json

{"status": "paid"
}

Response samples

400
401

Content type

application/json

{"id": "4707b026-21ca-449e-9b40-c8c6c0d4f404",
"message": "Bad Request",
"errors": [{"detail": "The 'Vendor-Software-Version' header is required."
}
]
}

Delete an invoice

After successfully fetching the invoice data, send a delete request to erase all invoice data.

Authorizations:

bearerAuth

path Parameters

id

required

string

The invoice ID.

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Responses

Response samples

400
401

Content type

application/json

{"id": "4707b026-21ca-449e-9b40-c8c6c0d4f404",
"message": "Bad Request",
"errors": [{"detail": "The 'Vendor-Software-Version' header is required."
}
]
}

Invoys Link

Deliver the Invoys Link to the counterparty preferred communication channel and check its status.

Send the Invoys link

Initiate sending of an Invoys Link to the counterparty via available delivery channels.

Authorizations:

bearerAuth

path Parameters

id

required

string

The Invoys link ID.

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Request Body schema: application/json
required

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.

Responses

Request samples

Payload

Content type

application/json

{"application": "ba8ffbee-17c8-4bd8-aafe-9029a632a2dc",
"send_to": "email@company-b.com"
}

Response samples

200
400
401
422

Content type

application/json

{"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 Invoys link

Get the details of an Invoys link.

Authorizations:

bearerAuth

path Parameters

id

required

string

The Invoys link ID.

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Responses

Response samples

200
400
401
422

Content type

application/json

{"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"
}
}

Webhooks

Create subscriptions to receive notifications about events related to your processed documents.

Create a new subscription

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Request Body schema: application/json
required

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.

Responses

Request samples

Payload

Content type

application/json

{"url": "https://example.com/company/webhook/endpoint",
"name": "Company Webhook",
"events": ["invoice.confirmed"
]
}

Response samples

201
400
401
422

Content type

application/json

{"id": "ba8ffbee-17c8-4bd8-aafe-9129a632a2dc",
"url": "https://example.com/company/webhook/endpoint",
"name": "Company Webhook",
"events": ["invoice.confirmed"
],
"secret": "oquw39uNZHPBh2fU",
"created_at": "2024-04-10T22:33:22.000000Z"
}

Get the list of created subscriptions

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Responses

Response samples

200
400
401
422

Content type

application/json

[{"id": "ba8ffbee-17c8-4bd8-aafe-9129a632a2dc",
"url": "https://example.com/company/webhook/endpoint",
"name": "Company Webhook",
"events": ["invoice.confirmed"
],
"created_at": "2024-04-10T22:33:22.000000Z"
}
]

Update an existing subscription

path Parameters

id

required

string

The ID of the subscription.

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Request Body schema: application/json
required

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.

Responses

Request samples

Payload

Content type

application/json

{"url": "https://example.com/company/webhook/endpoint",
"name": "Company Webhook",
"events": ["invoice.confirmed"
]
}

Response samples

200
400
401
422

Content type

application/json

{"id": "ba8ffbee-17c8-4bd8-aafe-9129a632a2dc",
"url": "https://example.com/company/webhook/endpoint",
"name": "Company Webhook",
"events": ["invoice.confirmed"
],
"created_at": "2024-04-10T22:33:22.000000Z"
}

Delete a subscription

path Parameters

id

required

string

The ID of the subscription.

header Parameters

Vendor-Id required	string The vendor ID.
Vendor-Secret required	string The vendor secret.
Vendor-Software-Version required	string The vendor software version.

Responses

Response samples

400
401
422

Content type

application/json

{"id": "4707b026-21ca-449e-9b40-c8c6c0d4f404",
"message": "Bad Request",
"errors": [{"detail": "The 'Vendor-Software-Version' header is required."
}
]
}

Callback with event notification

header Parameters

X-Webhook-Secret

required

string

The shared secret.

Request Body schema: application/json
required

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.

Responses

Request samples

Payload

Content type

application/json

{"id": "2f4a4b5d-0f28-41d3-9fe9-4ec3d8a06122",
"event": "invoice.confirmed",
"document_id": "9bd54aba-18b1-4194-9a66-3d52ccbc2b6e",
"created_at": "2024-04-10T22:33:22.000000Z"
}

Invoys Public API (v1.0)

Introduction

Invoice Management

Invoys Link

Sequence diagrams

Invoice Management

Managed Applications

API status

Check API status.

header Parameters

Responses

Response samples

Company

Create a new company

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Update existing company

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get access token

header Parameters

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Response samples

Get connectivity status

Authorizations:

header Parameters

Responses

Response samples

Application

Get list of available applications

Authorizations:

query Parameters

header Parameters

Responses

Response samples

App Redirect

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Activate an application

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Update an application

Authorizations:

header Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Deactivate an application

Authorizations:

header Parameters

Responses

Response samples

Upload

Upload a document

Authorizations:

header Parameters

Request Body schema: multipart/form-datarequired

Responses

Response samples

Invoice

Get list of invoices

Authorizations:

header Parameters

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: multipart/form-data
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required