Getting Started

The Partner API connects your product to the Invoier marketplace. You can onboard your clients, register their customers and sell their invoices without leaving your own product.

🚧
The Partner API is in beta
Endpoints and fields may change. We will tell you before anything that you rely on changes.

1. Get access

Email [email protected] to get:

an API key, and
the base URL of the sandbox. Use the sandbox until your integration works end to end. Production is https://api.invoier.com/v1.

You are also welcome to join our Slack channel for quick support.

2. Authenticate

Send your API key in the Authorization header of every request. Bodies are JSON.

curl "$BASE_URL/api-key" \
  -H "Authorization: $API_KEY"

GET /api-key tells you what the key is allowed to do. The roles it lists decide which endpoints you can call. Account and session endpoints are for partners, while customer, invoice intent and invoice endpoints are for clients that can sell invoices.

3. The concepts

Concept	What it is
Account	A client of yours that sells invoices. It must be onboarded before it can sell.
Account session	A hosted flow, such as onboarding or KYC renewal, that you send an end user to.
Customer	The debtor that an invoice is addressed to, identified by organisation number.
Invoice intent	An invoice you are considering selling. Invoier answers with financing offers.
Invoice	The invoice you decided to sell, created from an invoice intent.
Attachment	The invoice PDF. You deliver it to an attachment target that Invoier gives you.

4. Where to go next

How it works explains the resources and how they change over time. Read it first if you want the whole picture.
Onboarding an account walks you through creating an account and sending the end user through onboarding.
Selling an invoice walks you through the four steps from customer to invoice.
Concepts: Sessions and callbacks, Invoice intents and offers and Attachments.
Pre-filling the KYC form for when you already have the KYC answers.

Conventions

Creating things is idempotent. Create endpoints return 201 for a new resource and 200 with the existing resource if it has already been created, so a retry is safe. Without an idempotencyToken, the key is derived from the content of your request, so an identical request is treated as a retry. Send your own idempotencyToken where you need to tell identical requests apart.

Pagination. List endpoints take limit (1 to 256, default 20) and pageToken. Pass the nextPageToken of a response as pageToken to get the next page.

Metadata. Most resources have a metadata object for your own data, for example your own customer number. It can have at most 25 keys, and keys starting with _ are reserved.

Timestamps and dates. Timestamps are ISO 8601. Dates are YYYY-MM-DD.

Polling, not webhooks. Resources change status in the background. There are no webhooks yet (they are planned), so poll the resource until it reaches the status you wait for. Session callbacks are browser redirects and not webhooks, see Sessions and callbacks.

Concurrent updates. When you update an account or a session, send the lastModifiedAt you last read. If the resource has changed since then you get 412 and the current resource in details.

Errors

Errors have a non-2xx status and a JSON body:

{
  "errorType": "NOT_FOUND",
  "message": "No such invoice intent"
}

errorType and details are only present for some errors.

Status	Meaning
`400`	The request is invalid, for example because the body does not match the schema, or because the resource is in a status that does not allow it. `message` says why.
`403`	Your key is invalid, or it lacks a role that the endpoint requires.
`404`	The resource does not exist, or belongs to someone else.
`409`	The resource is being updated. Try again shortly.
`412`	The resource was modified since you read it.
`5xx`	Something went wrong on our side. Try again, and contact us if it persists.