Invoys logo
API docs by Redocly

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

Content type
application/json
Example
{
  • "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.

Responses

Request samples

Content type
application/json
{
  • "company_name": "Acme",
  • "name": "John Doe",
  • "email": "john.doe@acme.com",
  • "country": "RO"
}

Response samples

Content type
application/json
{}

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

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

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
Value: "delivery"

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

Content type
application/json
{
  • "applications": [
    ]
}

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

Content type
application/json
{
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "1c3ed75b-204f-448e-a302-fb4da6e98ba1",
  • "connected_at": "2023-06-04T12:22:23Z",
  • "status": "confirmed",
  • "is_active": true,
  • "config": {
    },
  • "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

Content type
application/json
{
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "1c3ed75b-204f-448e-a302-fb4da6e98ba1",
  • "connected_at": "2023-06-04T12:22:23Z",
  • "status": "confirmed",
  • "is_active": true,
  • "config": {
    },
  • "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

Content type
application/json
{
  • "id": "4707b026-21ca-449e-9b40-c8c6c0d4f404",
  • "message": "Bad Request",
  • "errors": [
    ]
}

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

Content type
application/json
{}

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

Content type
application/json
[]

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.

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.

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.

total_price
string

Total price for the quantity of the item.

Responses

Request samples

Content type
application/json
{
  • "direction": "outgoing",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {}
}

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

Content type
application/json
{
  • "data": {
    },
  • "meta": {}
}

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

Content type
application/json
{
  • "id": "4707b026-21ca-449e-9b40-c8c6c0d4f404",
  • "message": "Bad Request",
  • "errors": [
    ]
}