Jortt API v1.0.0-beta

Disclaimer

Introduction

Welcome to the Jortt API. This API is meant for applications that want to connect to the Jortt application.

This API is designed around the REST principles.

OAuth 2.0 is used for authentication and authorization.

The Jortt API supports Open API version 2.0 (formerly known as Swagger) for describing the API interface. Check openapi.tools for handy tooling (such a generating client libraries).

You can also download the API specification.

Connecting

Connecting your application with the Jortt API requires you to register your application as a client in our authorization server.

Please send an e-mail to support@jortt.nl to register your application and provide the following information:

Application name
Redirect URL
Required scopes

After successful registration you will receive the necessary credentials (client ID and secret) to initiate the OAuth 2.0 Authorization Code Flow to gain access.

When retrieving the initial access_token you need to pass the client_id and client_secret in the Authorization header.

Making requests

Whenever you make an HTTP request to the Jortt API, the response will contain a JSON object with (at least) either a data key (a success response) or an error key (an error response).

Please check the documentation of endpoints for the details of responses.

The access_token must be provided as an HTTP header: Authorization: Bearer YOUR_ACCESS_TOKEN.

Success response

An HTTP response with status code 200 OK or 201 Created indicates the request was successful.

Request example

curl -X GET https://api.jortt.nl/customers?query=bob -H "Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW"

Response example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "c4075eb6-2028-457e-817f-a6a8d4703fbb",
      ... more properties
    }
  ]
}

Error response

An HTTP response with status code 4xx or 5xx indicates there was an error while processing the request. The response body will contain extra information about the error.

Request example

curl -X GET https://api.jortt.nl/customers?query=x -H "Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW"

Response example

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": 422,
    "key": "invalid_params",
    "message": "The parameters are invalid (either missing, not of the correct type or incorrect format).",
    "details": [
      {
        "param": "customer_id",
        "key": "is_missing",
        "message": "is missing"
      }
    ]
  }
}

Errors

The following table describes the errors found in responses.

Code	Key	Description
`401`	`access_token.invalid`	The `access_token` is either missing or invalid.
`401`	`access_token.expired`	The `access_token` has expired. Use `refresh_token` to get a new `access_token`.
`401`	`access_token.revoked`	The `access_token` has been revoked.
`401`	`scopes.insufficient`	Insufficient permissions (read: missing scopes) to access resource. Your application probably needs more scopes.
`401`	`organization.non_existing`	The corresponding organization for your access token does not exist.
`401`	`organization.requires_paid_plan`	The corresponding organization for your access token does not have a paid plan.
`401`	`user.non_existing`	The corresponding user for your access token does not exist.
`404`	`endpoint.not_found`	Invalid or non existing endpoint.
`404`	`resource.not_found`	Requested resource cannot be found.
`405`	`resource.method_not_allowed`	The method is not allowed on this resource.
`409`	`resource.conflict`	A conflict occurred while processing the request. This can happen when two processes are trying to modify the same resource simultaneously.
`422`	`params.invalid`	The parameters are invalid (either missing, not of the correct type or incorrect format).
`422`	`operation.invalid`	The operation could not be executed on the resource.
`500`	`server.internal_error`	Internal server error. Sorry, we screwed up :-( Please try again later.
`503`	`server.maintenance`	API is temporarily offline for maintenance. Please try again later.

You can use this API according to our terms of service (PDF).

Base URL Jortt API:

https://api.jortt.nl

Authentication

OAuth2 authentication

Flow: `authorizationCode`

Authorization URL https://app.jortt.nl/oauth-provider/oauth/authorize

Token URL https://app.jortt.nl/oauth-provider/oauth/token

The authorizationCode flow is well documented on the Internet. See for instance OAuth 2.0, this article from Digital Ocean or the official RFC.

The following diagram visualises the flow we support in Jortt:

  +--------+                                           +---------------+
  |        |--(A)------- Authorization Grant --------->|               |
  |        |                                           |               |
  |        |<-(B)----------- Access Token -------------|               |
  |        |               & Refresh Token             |               |
  |        |                                           |               |
  |        |                            +----------+   |               |
  |        |--(C)---- Access Token ---->|          |   |               |
  |        |                            |          |   |               |
  |        |<-(D)- Protected Resource --| Resource |   | Authorization |
  | Client |                            |  Server  |   |     Server    |
  |        |--(E)---- Access Token ---->|          |   |               |
  |        |                            |          |   |               |
  |        |<-(F)- Invalid Token Error -|          |   |               |
  |        |                            +----------+   |               |
  |        |                                           |               |
  |        |--(G)----------- Refresh Token ----------->|               |
  |        |                                           |               |
  |        |<-(H)----------- Access Token -------------|               |
  +--------+           & Optional Refresh Token        +---------------+

Source: The OAuth 2.0 Authorization Framework

Initiate the grant (A) by applying got a access_token and refresh_token using the https://app.jortt.nl/oauth-provider/oauth/authorize. This will return the access_token and refresh_token (B). The Client should store this for later usage.
With the access_token the Client can access the resources (like Invoices, Customers) available by the Jortt API (C and D).
Whenever the access_token expires an Invalid Token Error will be returned (E and F). If this is the case the Client must request a new access_token and refresh_token using the stored refresh_token (G). The returned access_token and refresh_token should be stored by the Client for later usage.

Scopes

We defined the following scopes for accessing or modifying the various Resources.

Scope	Scope Description
`customers:read`	Read customers
`customers:write`	Create and update customers
`invoices:read`	Read invoices
`invoices:write`	Create, update and send invoices

Customers

Update Customer

PUT /customers/{customer_id}

Updates a Customer.

A Customer can either be a private person (set is_private to true) or a company (set is_private to false).

The required attributes are different for a private person than a company. See parameters documentation below for details.

Permissions

This operation requires the following OAuth2 scopes: customers:write

Parameters

Name	Description
is_private `boolean` required	Whether this Customer is a private person (`true`) or a company (`false`)
customer_name `string` required	Either a company name (when `is_private` is `false`) or a private person's full name (when `is_private` is `true`)
address_street `string`	Street and house number of the address of a Customer (required when `is_private` is `false`)
address_postal_code `string`	Postal code of the address of a Customer (required when `is_private` is `false`)
address_city `string`	City of the address of a Customer (required when `is_private` is `false`)
address_country_code `string`	Country code of a Customer in ISO 3166-1 alpha-2 format (required when `is_private` is `false`, defaults to `NL`)
address_extra_information `string`	Extra line of Customer address information
shift_vat `boolean`	Whether or not to shift the VAT for a Customer (applicable when `is_private` is `false`)
vat_number `string`	The VAT number (BTW-nummer) of a Customer (applicable when `is_private` is `false` and `shift_vat` is `true`)
coc_number `string`	The Chamber of Commerce number (KvK-nummer) of a Customer (applicable when `is_private` is `false`)
salutation `string`	The way a Customer is addressed (applicable when `is_private` is `true`) Possible values: `sir`, `madam`, `family`
initials `string`	Initials of a Customer (applicable when `is_private` is `true`)
first_name `string`	First name of a Customer (applicable when `is_private` is `true`)
last_name `string`	Last name of a Customer (applicable when `is_private` is `true`)
date_of_birth `string(date)`	Date of birth of a Customer (applicable when `is_private` is `true`)
citizen_service_number `string`	Citizen service number (BSN-nummer) of a Customer (applicable when `is_private` is `true`)
attn `string`	To the attention of
phonenumber `string`	A Customer's phone number
website `string`	A Customer's website
email `string`	E-mail address to send the Invoice to
cc_emails `string`	A comma-separated list of e-mail addresses to CC when the Invoice is sent
email_salutation `string`	Salutation used in the e-mail (template) when sending an Invoice
additional_information `string`	Extra Customer information
payment_term `integer(int32)`	Payment term for Invoices (in days, defaults to 30)
invoice_language `string`	The language in which the Invoice will be translated Possible values: `nl`, `de`, `en`, `fr`, `es`
payment_method_invoice `string`	How the Invoice can be paid. Determines the payment instructions printed on the Invoice. Choose from: `already_paid` when the Invoice has already been paid. No payment instructions will be printed on the Invoice. `pay_later` will print payment instructions on the Invoice. `direct_debit` requires a connection with Mollie. Only for Jortt Plus users. The default is `pay_later`. Possible values: `pay_later`, `direct_debit`, `already_paid`
reference `string`	Custom reference (for example the ID of a customer in an external CRM)

Code samples

# You can also use wget
curl -X PUT https://api.jortt.nl/customers/{customer_id} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

Example body values

{
  "is_private": true,
  "customer_name": "Jortt",
  "address_street": "Rozengracht 75a",
  "address_postal_code": "1012 AB",
  "address_city": "Amsterdam",
  "address_country_code": "NL",
  "address_extra_information": "2nd floor",
  "shift_vat": true,
  "vat_number": "NL000099998B57",
  "coc_number": "41202536",
  "salutation": "madam",
  "initials": "FL",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1985-04-29",
  "citizen_service_number": "123456789",
  "attn": "Finance Department",
  "phonenumber": "+31658798654",
  "website": "www.example.com",
  "email": "example@email.com",
  "cc_emails": [
    "example@email.com",
    "example2@email.com"
  ],
  "email_salutation": "Geachte mevrouw,",
  "additional_information": "this is extra info",
  "payment_term": 30,
  "invoice_language": "nl",
  "payment_method_invoice": "pay_later",
  "reference": "BX123-123"
}

Responses

Status	Meaning	Description	Schema
204	No Content	No Content	None

Get Customer by ID

GET /customers/{customer_id}

Returns a Customer by ID.

Permissions

This operation requires the following OAuth2 scopes: customers:read

Parameters

Name	Description
customer_id `string` required	Resource identifier (UUID)

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/customers/{customer_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Responses

Status	Meaning	Description	Schema
200	OK	Customer	GetCustomerResponse

Create Customer

POST /customers

Creates a Customer.

A Customer can either be a private person (set is_private to true) or a company (set is_private to false).

The required attributes are different for a private person than a company. See parameters documentation below for details.

Permissions

This operation requires the following OAuth2 scopes: customers:write

Parameters

Name	Description
is_private `boolean` required	Whether this Customer is a private person (`true`) or a company (`false`)
customer_name `string` required	Either a company name (when `is_private` is `false`) or a private person's full name (when `is_private` is `true`)
address_street `string`	Street and house number of the address of a Customer (required when `is_private` is `false`)
address_postal_code `string`	Postal code of the address of a Customer (required when `is_private` is `false`)
address_city `string`	City of the address of a Customer (required when `is_private` is `false`)
address_country_code `string`	Country code of a Customer in ISO 3166-1 alpha-2 format (required when `is_private` is `false`, defaults to `NL`)
address_extra_information `string`	Extra line of Customer address information
shift_vat `boolean`	Whether or not to shift the VAT for a Customer (applicable when `is_private` is `false`)
vat_number `string`	The VAT number (BTW-nummer) of a Customer (applicable when `is_private` is `false` and `shift_vat` is `true`)
coc_number `string`	The Chamber of Commerce number (KvK-nummer) of a Customer (applicable when `is_private` is `false`)
salutation `string`	The way a Customer is addressed (applicable when `is_private` is `true`) Possible values: `sir`, `madam`, `family`
initials `string`	Initials of a Customer (applicable when `is_private` is `true`)
first_name `string`	First name of a Customer (applicable when `is_private` is `true`)
last_name `string`	Last name of a Customer (applicable when `is_private` is `true`)
date_of_birth `string(date)`	Date of birth of a Customer (applicable when `is_private` is `true`)
citizen_service_number `string`	Citizen service number (BSN-nummer) of a Customer (applicable when `is_private` is `true`)
attn `string`	To the attention of
phonenumber `string`	A Customer's phone number
website `string`	A Customer's website
email `string`	E-mail address to send the Invoice to
cc_emails `string`	A comma-separated list of e-mail addresses to CC when the Invoice is sent
email_salutation `string`	Salutation used in the e-mail (template) when sending an Invoice
additional_information `string`	Extra Customer information
payment_term `integer(int32)`	Payment term for Invoices (in days, defaults to 30)
invoice_language `string`	The language in which the Invoice will be translated Possible values: `nl`, `de`, `en`, `fr`, `es`
payment_method_invoice `string`	How the Invoice can be paid. Determines the payment instructions printed on the Invoice. Choose from: `already_paid` when the Invoice has already been paid. No payment instructions will be printed on the Invoice. `pay_later` will print payment instructions on the Invoice. `direct_debit` requires a connection with Mollie. Only for Jortt Plus users. The default is `pay_later`. Possible values: `pay_later`, `direct_debit`, `already_paid`
reference `string`	Custom reference (for example the ID of a customer in an external CRM)

Code samples

# You can also use wget
curl -X POST https://api.jortt.nl/customers \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Example body values

{
  "is_private": true,
  "customer_name": "Jortt",
  "address_street": "Rozengracht 75a",
  "address_postal_code": "1012 AB",
  "address_city": "Amsterdam",
  "address_country_code": "NL",
  "address_extra_information": "2nd floor",
  "shift_vat": true,
  "vat_number": "NL000099998B57",
  "coc_number": "41202536",
  "salutation": "madam",
  "initials": "FL",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1985-04-29",
  "citizen_service_number": "123456789",
  "attn": "Finance Department",
  "phonenumber": "+31658798654",
  "website": "www.example.com",
  "email": "example@email.com",
  "cc_emails": [
    "example@email.com",
    "example2@email.com"
  ],
  "email_salutation": "Geachte mevrouw,",
  "additional_information": "this is extra info",
  "payment_term": 30,
  "invoice_language": "nl",
  "payment_method_invoice": "pay_later",
  "reference": "BX123-123"
}

Responses

Status	Meaning	Description	Schema
201	Created	Created	ResourceCreatedResponse

List Customers

GET /customers

Returns a list of Customers.

A Customer can be either a private person or a company.

Permissions

This operation requires the following OAuth2 scopes: customers:read

Parameters

Name	Description
query `string` required	Search query (at least 3 characters)

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/customers?query=string \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Responses

Status	Meaning	Description	Schema
200	OK	Customers	ListCustomersResponse

Invoices

Create (and optionally send) an Invoice

POST /invoices

Creates (and optionally sends) an Invoice.

When the optional send_method parameter is provided, the Invoice will also be scheduled for sending.

By polling the GET /invoices/{id} endpoint you can check if the Invoice has been sent (the returned Invoice's invoice_status attribute is then set to sent).

Permissions

This operation requires the following OAuth2 scopes: invoices:write

Parameters

Name	Description
customer_id `string` required	Resource identifier (UUID)
invoice_date `string(date)`	Date of the Invoice (determines the VAT period)
delivery_period `string(date)`	Determines the profit and loss period of this Invoice
payment_term `integer(int32)`	Optional payment term for the Invoice. Defaults to the following first present value: The `payment_term` configured on the Customer (referenced by the `customer_id` param). The `payment_term` configured on the Organization (referenced by the `access_token`). The global default payment term (30 days).
net_amounts `boolean`	Whether or not VAT is included in the `amount_per_unit` in the line item (this is typically used when invoicing a private person rather than a company)
send_method `string`	How the Invoice should be sent Possible values: `email`, `self`
introduction `string`	Comments printed on the Invoice (above the line items)
remarks `string`	Remarks printed on the Invoice (under the line items)
line_items `[object]` required	The line items of an Invoice
description `string` required	Description of the line item
units `number(double)` required	Number of units of the line item
amount_per_unit `[Amount](#schemaamount)` required	Represents a monetary Amount in Jortt.
value `number(double)`	Amount per unit of the line item
currency `string`	Currency of the line item Possible values: `EUR`
vat `integer(int64)` required	VAT rate of the line item Possible values: `21`, `9`, `0`
reference `string`	Custom reference (for example an order ID)

Code samples

# You can also use wget
curl -X POST https://api.jortt.nl/invoices \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Example body values

{
  "customer_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "invoice_date": "2020-02-23",
  "delivery_period": "2020-02-01",
  "payment_term": 14,
  "net_amounts": true,
  "send_method": "email",
  "introduction": "example",
  "remarks": "example",
  "line_items": [
    {
      "description": "this is a description example",
      "units": 3.14,
      "amount_per_unit": {
        "value": "365.00",
        "currency": "EUR"
      },
      "vat": 21
    }
  ],
  "reference": "123"
}

Responses

Status	Meaning	Description	Schema
201	Created	Created	ResourceCreatedResponse

Get Invoice by ID

GET /invoices/{id}

Returns an Invoice by ID.

Permissions

This operation requires the following OAuth2 scopes: invoices:read

Parameters

Name	Description
id `string` required	Resource identifier (UUID)

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/invoices/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Responses

Status	Meaning	Description	Schema
200	OK	Invoice	GetInvoiceResponse

Schemas

UpdateCustomer

Updates a Customer

{
  "is_private": true,
  "customer_name": "Jortt",
  "address_street": "Rozengracht 75a",
  "address_postal_code": "1012 AB",
  "address_city": "Amsterdam",
  "address_country_code": "NL",
  "address_extra_information": "2nd floor",
  "shift_vat": true,
  "vat_number": "NL000099998B57",
  "coc_number": "41202536",
  "salutation": "madam",
  "initials": "FL",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1985-04-29",
  "citizen_service_number": "123456789",
  "attn": "Finance Department",
  "phonenumber": "+31658798654",
  "website": "www.example.com",
  "email": "example@email.com",
  "cc_emails": [
    "example@email.com",
    "example2@email.com"
  ],
  "email_salutation": "Geachte mevrouw,",
  "additional_information": "this is extra info",
  "payment_term": 30,
  "invoice_language": "nl",
  "payment_method_invoice": "pay_later",
  "reference": "BX123-123"
}

Properties

Name	Description
is_private `boolean` required	Whether this Customer is a private person (`true`) or a company (`false`)
customer_name `string` required	Either a company name (when `is_private` is `false`) or a private person's full name (when `is_private` is `true`)
address_street `string`	Street and house number of the address of a Customer (required when `is_private` is `false`)
address_postal_code `string`	Postal code of the address of a Customer (required when `is_private` is `false`)
address_city `string`	City of the address of a Customer (required when `is_private` is `false`)
address_country_code `string`	Country code of a Customer in ISO 3166-1 alpha-2 format (required when `is_private` is `false`, defaults to `NL`)
address_extra_information `string`	Extra line of Customer address information
shift_vat `boolean`	Whether or not to shift the VAT for a Customer (applicable when `is_private` is `false`)
vat_number `string`	The VAT number (BTW-nummer) of a Customer (applicable when `is_private` is `false` and `shift_vat` is `true`)
coc_number `string`	The Chamber of Commerce number (KvK-nummer) of a Customer (applicable when `is_private` is `false`)
salutation `string`	The way a Customer is addressed (applicable when `is_private` is `true`) Possible values: `sir`, `madam`, `family`
initials `string`	Initials of a Customer (applicable when `is_private` is `true`)
first_name `string`	First name of a Customer (applicable when `is_private` is `true`)
last_name `string`	Last name of a Customer (applicable when `is_private` is `true`)
date_of_birth `string(date)`	Date of birth of a Customer (applicable when `is_private` is `true`)
citizen_service_number `string`	Citizen service number (BSN-nummer) of a Customer (applicable when `is_private` is `true`)
attn `string`	To the attention of
phonenumber `string`	A Customer's phone number
website `string`	A Customer's website
email `string`	E-mail address to send the Invoice to
cc_emails `string`	A comma-separated list of e-mail addresses to CC when the Invoice is sent
email_salutation `string`	Salutation used in the e-mail (template) when sending an Invoice
additional_information `string`	Extra Customer information
payment_term `integer(int32)`	Payment term for Invoices (in days, defaults to 30)
invoice_language `string`	The language in which the Invoice will be translated Possible values: `nl`, `de`, `en`, `fr`, `es`
payment_method_invoice `string`	How the Invoice can be paid. Determines the payment instructions printed on the Invoice. Choose from: `already_paid` when the Invoice has already been paid. No payment instructions will be printed on the Invoice. `pay_later` will print payment instructions on the Invoice. `direct_debit` requires a connection with Mollie. Only for Jortt Plus users. The default is `pay_later`. Possible values: `pay_later`, `direct_debit`, `already_paid`
reference `string`	Custom reference (for example the ID of a customer in an external CRM)

CreateCustomer

Creates a Customer

{
  "is_private": true,
  "customer_name": "Jortt",
  "address_street": "Rozengracht 75a",
  "address_postal_code": "1012 AB",
  "address_city": "Amsterdam",
  "address_country_code": "NL",
  "address_extra_information": "2nd floor",
  "shift_vat": true,
  "vat_number": "NL000099998B57",
  "coc_number": "41202536",
  "salutation": "madam",
  "initials": "FL",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1985-04-29",
  "citizen_service_number": "123456789",
  "attn": "Finance Department",
  "phonenumber": "+31658798654",
  "website": "www.example.com",
  "email": "example@email.com",
  "cc_emails": [
    "example@email.com",
    "example2@email.com"
  ],
  "email_salutation": "Geachte mevrouw,",
  "additional_information": "this is extra info",
  "payment_term": 30,
  "invoice_language": "nl",
  "payment_method_invoice": "pay_later",
  "reference": "BX123-123"
}

Properties

Name	Description
is_private `boolean` required	Whether this Customer is a private person (`true`) or a company (`false`)
customer_name `string` required	Either a company name (when `is_private` is `false`) or a private person's full name (when `is_private` is `true`)
address_street `string`	Street and house number of the address of a Customer (required when `is_private` is `false`)
address_postal_code `string`	Postal code of the address of a Customer (required when `is_private` is `false`)
address_city `string`	City of the address of a Customer (required when `is_private` is `false`)
address_country_code `string`	Country code of a Customer in ISO 3166-1 alpha-2 format (required when `is_private` is `false`, defaults to `NL`)
address_extra_information `string`	Extra line of Customer address information
shift_vat `boolean`	Whether or not to shift the VAT for a Customer (applicable when `is_private` is `false`)
vat_number `string`	The VAT number (BTW-nummer) of a Customer (applicable when `is_private` is `false` and `shift_vat` is `true`)
coc_number `string`	The Chamber of Commerce number (KvK-nummer) of a Customer (applicable when `is_private` is `false`)
salutation `string`	The way a Customer is addressed (applicable when `is_private` is `true`) Possible values: `sir`, `madam`, `family`
initials `string`	Initials of a Customer (applicable when `is_private` is `true`)
first_name `string`	First name of a Customer (applicable when `is_private` is `true`)
last_name `string`	Last name of a Customer (applicable when `is_private` is `true`)
date_of_birth `string(date)`	Date of birth of a Customer (applicable when `is_private` is `true`)
citizen_service_number `string`	Citizen service number (BSN-nummer) of a Customer (applicable when `is_private` is `true`)
attn `string`	To the attention of
phonenumber `string`	A Customer's phone number
website `string`	A Customer's website
email `string`	E-mail address to send the Invoice to
cc_emails `string`	A comma-separated list of e-mail addresses to CC when the Invoice is sent
email_salutation `string`	Salutation used in the e-mail (template) when sending an Invoice
additional_information `string`	Extra Customer information
payment_term `integer(int32)`	Payment term for Invoices (in days, defaults to 30)
invoice_language `string`	The language in which the Invoice will be translated Possible values: `nl`, `de`, `en`, `fr`, `es`
payment_method_invoice `string`	How the Invoice can be paid. Determines the payment instructions printed on the Invoice. Choose from: `already_paid` when the Invoice has already been paid. No payment instructions will be printed on the Invoice. `pay_later` will print payment instructions on the Invoice. `direct_debit` requires a connection with Mollie. Only for Jortt Plus users. The default is `pay_later`. Possible values: `pay_later`, `direct_debit`, `already_paid`
reference `string`	Custom reference (for example the ID of a customer in an external CRM)

ResourceCreatedResponse

The id of the created Resource wrapped in a data object.

{
  "data": {
    "id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a"
  }
}

Properties

Name	Description
data `object`
id `string`	The identifier of the created resource

GetCustomerResponse

A Customer wrapped in a data object.

{
  "data": {
    "id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
    "is_private": true,
    "customer_name": "Jortt",
    "address_street": "Rozengracht 75a",
    "address_postal_code": "1012 AB",
    "address_city": "Amsterdam",
    "address_country_code": "NL",
    "address_country_name": "Nederland",
    "address_extra_information": "2nd floor",
    "shift_vat": true,
    "vat_number": "NL000099998B57",
    "coc_number": "41202536",
    "initials": "FL",
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1985-04-29",
    "citizen_service_number": "123456789",
    "attn": "Finance Department",
    "phonenumber": "+31658798654",
    "website": "www.example.com",
    "email": "example@email.com",
    "cc_emails": [
      "example@email.com",
      "example2@email.com"
    ],
    "email_salutation": "Geachte mevrouw,",
    "additional_information": "this is extra info",
    "payment_term": 30,
    "invoice_language": "nl",
    "payment_method_invoice": "pay_later",
    "reference": "BX123-123"
  }
}

Properties

Name	Description
data Customer	Response object containing a single Customer

Customer

A Customer in Jortt. This can be a private person or a company. The is_private flag determines the type of Customer. The main reason we distinct between types of Customers is the mandatory attributes on an Invoice.

{
  "id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "is_private": true,
  "customer_name": "Jortt",
  "address_street": "Rozengracht 75a",
  "address_postal_code": "1012 AB",
  "address_city": "Amsterdam",
  "address_country_code": "NL",
  "address_country_name": "Nederland",
  "address_extra_information": "2nd floor",
  "shift_vat": true,
  "vat_number": "NL000099998B57",
  "coc_number": "41202536",
  "initials": "FL",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1985-04-29",
  "citizen_service_number": "123456789",
  "attn": "Finance Department",
  "phonenumber": "+31658798654",
  "website": "www.example.com",
  "email": "example@email.com",
  "cc_emails": [
    "example@email.com",
    "example2@email.com"
  ],
  "email_salutation": "Geachte mevrouw,",
  "additional_information": "this is extra info",
  "payment_term": 30,
  "invoice_language": "nl",
  "payment_method_invoice": "pay_later",
  "reference": "BX123-123"
}

Properties

Name	Description
id `string`	Resource identifier (UUID)
is_private `boolean`	Whether this Customer is a private person (`true`) or a company (`false`)
customer_name `string`	Either a company name (when `is_private` is `false`) or a private person's full name (when `is_private` is `true`)
address_street `string`	Street and house number of the address of a Customer (required when `is_private` is `false`)
address_postal_code `string`	Postal code of the address of a Customer (required when `is_private` is `false`)
address_city `string`	City of the address of a Customer (required when `is_private` is `false`)
address_country_code `string`	Country code of a Customer in ISO 3166-1 alpha-2 format (required when `is_private` is `false`, defaults to `NL`)
address_country_name `string`	Country name of a Customer (applicable when `is_private` is `false`, defaults to `NL`)
address_extra_information `string`	Extra line of Customer address information
shift_vat `boolean`	Whether or not to shift the VAT for a Customer (applicable when `is_private` is `false`)
vat_number `string`	The VAT number (BTW-nummer) of a Customer (applicable when `is_private` is `false` and `shift_vat` is `true`)
coc_number `string`	The Chamber of Commerce number (KvK-nummer) of a Customer (applicable when `is_private` is `false`)
initials `string`	Initials of a Customer (applicable when `is_private` is `true`)
first_name `string`	First name of a Customer (applicable when `is_private` is `true`)
last_name `string`	Last name of a Customer (applicable when `is_private` is `true`)
date_of_birth `string(date)`	Date of birth of a Customer (applicable when `is_private` is `true`)
citizen_service_number `string`	Citizen service number (BSN-nummer) of a Customer (applicable when `is_private` is `true`)
attn `string`	To the attention of
phonenumber `string`	A Customer's phone number
website `string`	A Customer's website
email `string`	E-mail address to send the Invoice to
cc_emails `string`	A comma-separated list of e-mail addresses to CC when the Invoice is sent
email_salutation `string`	Salutation used in the e-mail (template) when sending an Invoice
additional_information `string`	Extra Customer information
payment_term `integer(int32)`	Payment term for Invoices (in days, defaults to 30)
invoice_language `string`	The language in which the Invoice will be translated Possible values: `nl`, `de`, `en`, `fr`, `es`
payment_method_invoice `string`	How the Invoice can be paid. Determines the payment instructions printed on the Invoice. Choose from: `already_paid` when the Invoice has already been paid. No payment instructions will be printed on the Invoice. `pay_later` will print payment instructions on the Invoice. `direct_debit` requires a connection with Mollie. Only for Jortt Plus users. The default is `pay_later`. Possible values: `pay_later`, `direct_debit`, `already_paid`
reference `string`	Custom reference (for example the ID of a customer in an external CRM)

ListCustomersResponse

A list of Customers wrapped in a data object.

{
  "data": [
    {
      "id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
      "is_private": true,
      "customer_name": "Jortt",
      "address_street": "Rozengracht 75a",
      "address_postal_code": "1012 AB",
      "address_city": "Amsterdam",
      "address_country_code": "NL",
      "address_country_name": "Nederland",
      "address_extra_information": "2nd floor",
      "shift_vat": true,
      "vat_number": "NL000099998B57",
      "coc_number": "41202536",
      "initials": "FL",
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1985-04-29",
      "citizen_service_number": "123456789",
      "attn": "Finance Department",
      "phonenumber": "+31658798654",
      "website": "www.example.com",
      "email": "example@email.com",
      "cc_emails": [
        "example@email.com",
        "example2@email.com"
      ],
      "email_salutation": "Geachte mevrouw,",
      "additional_information": "this is extra info",
      "payment_term": 30,
      "invoice_language": "nl",
      "payment_method_invoice": "pay_later",
      "reference": "BX123-123"
    }
  ]
}

Properties

Name	Description
data [Customer]	Response object containing a list of Customers

Amount

Represents a monetary Amount in Jortt.

{
  "value": "365.00",
  "currency": "EUR"
}

Properties

Name	Description
value `number(double)`	Amount per unit of the line item
currency `string`	Currency of the line item Possible values: `EUR`

CreateInvoice

Creates (and optionally sends) an Invoice

{
  "customer_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "invoice_date": "2020-02-23",
  "delivery_period": "2020-02-01",
  "payment_term": 14,
  "net_amounts": true,
  "send_method": "email",
  "introduction": "example",
  "remarks": "example",
  "line_items": [
    {
      "description": "this is a description example",
      "units": 3.14,
      "amount_per_unit": {
        "value": "365.00",
        "currency": "EUR"
      },
      "vat": 21
    }
  ],
  "reference": "123"
}

Properties

Name	Description
customer_id `string` required	Resource identifier (UUID)
invoice_date `string(date)`	Date of the Invoice (determines the VAT period)
delivery_period `string(date)`	Determines the profit and loss period of this Invoice
payment_term `integer(int32)`	Optional payment term for the Invoice. Defaults to the following first present value: The `payment_term` configured on the Customer (referenced by the `customer_id` param). The `payment_term` configured on the Organization (referenced by the `access_token`). The global default payment term (30 days).
net_amounts `boolean`	Whether or not VAT is included in the `amount_per_unit` in the line item (this is typically used when invoicing a private person rather than a company)
send_method `string`	How the Invoice should be sent Possible values: `email`, `self`
introduction `string`	Comments printed on the Invoice (above the line items)
remarks `string`	Remarks printed on the Invoice (under the line items)
line_items `[object]` required	The line items of an Invoice
description `string` required	Description of the line item
units `number(double)` required	Number of units of the line item
amount_per_unit Amount required	Amount per unit per line item
vat `integer(int64)` required	VAT rate of the line item Possible values: `21`, `9`, `0`
reference `string`	Custom reference (for example an order ID)

GetInvoiceResponse

An Invoice wrapped in a data object.

{
  "data": {
    "id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
    "invoice_status": "draft",
    "customer_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
    "invoice_number": "202001-002",
    "invoice_date": "2020-02-23",
    "invoice_due_date": "2020-03-22",
    "invoice_delivery_period": "2020-02-01",
    "invoice_date_sent": "2020-02-23",
    "invoice_total": {
      "value": "365.00",
      "currency": "EUR"
    },
    "invoice_total_incl_vat": {
      "value": "365.00",
      "currency": "EUR"
    },
    "send_method": "email",
    "net_amounts": true,
    "invoice_marked_free_of_vat": true,
    "credited_invoice_id": "4c23005c-ccd3-4294-bde6-24c726aa8810",
    "remarks": "example",
    "introduction": "example",
    "number_of_reminders_sent": 0,
    "last_reminded_at": "2020-03-31",
    "payment_method": "pay_later",
    "customer_company_name": "Jortt",
    "customer_attn": "Finance Department",
    "customer_address_street": "Rozengracht 75a",
    "customer_address_city": "Amsterdam",
    "customer_address_postal_code": "1012 AB",
    "customer_address_country_code": "NL",
    "customer_address_country_name": "Nederland",
    "customer_address_extra_information": "2nd floor",
    "customer_vat_shifted": true,
    "customer_vat_number": "NL000099998B57",
    "customer_in_eu": true,
    "customer_reference": "BX123-123",
    "customer_mail_to": "example@email.com",
    "customer_mail_cc_addresses": [
      "example@email.com",
      "example2@email.com"
    ],
    "language": "nl",
    "line_items": [
      {
        "description": "this is a description example",
        "vat": 21,
        "amount_per_unit": {
          "value": "365.00",
          "currency": "EUR"
        },
        "total_amount_excl_vat": {
          "value": "365.00",
          "currency": "EUR"
        },
        "units": 3.14
      }
    ],
    "reference": "123"
  }
}

Properties

Name	Description
data Invoice	Response object containing a single of Invoice

Invoice

An Invoice in Jortt. The main statuses are draft and sent. When an Invoice is sent its attributes can not be changed. After the Invoice has been sent, the attributes of the referenced Customer are copied into the Invoice. So when the Customer is changed later the Invoice will still contain the attributes of the Customer at the time of sending.

{
  "id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "invoice_status": "draft",
  "customer_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "invoice_number": "202001-002",
  "invoice_date": "2020-02-23",
  "invoice_due_date": "2020-03-22",
  "invoice_delivery_period": "2020-02-01",
  "invoice_date_sent": "2020-02-23",
  "invoice_total": {
    "value": "365.00",
    "currency": "EUR"
  },
  "invoice_total_incl_vat": {
    "value": "365.00",
    "currency": "EUR"
  },
  "send_method": "email",
  "net_amounts": true,
  "invoice_marked_free_of_vat": true,
  "credited_invoice_id": "4c23005c-ccd3-4294-bde6-24c726aa8810",
  "remarks": "example",
  "introduction": "example",
  "number_of_reminders_sent": 0,
  "last_reminded_at": "2020-03-31",
  "payment_method": "pay_later",
  "customer_company_name": "Jortt",
  "customer_attn": "Finance Department",
  "customer_address_street": "Rozengracht 75a",
  "customer_address_city": "Amsterdam",
  "customer_address_postal_code": "1012 AB",
  "customer_address_country_code": "NL",
  "customer_address_country_name": "Nederland",
  "customer_address_extra_information": "2nd floor",
  "customer_vat_shifted": true,
  "customer_vat_number": "NL000099998B57",
  "customer_in_eu": true,
  "customer_reference": "BX123-123",
  "customer_mail_to": "example@email.com",
  "customer_mail_cc_addresses": [
    "example@email.com",
    "example2@email.com"
  ],
  "language": "nl",
  "line_items": [
    {
      "description": "this is a description example",
      "vat": 21,
      "amount_per_unit": {
        "value": "365.00",
        "currency": "EUR"
      },
      "total_amount_excl_vat": {
        "value": "365.00",
        "currency": "EUR"
      },
      "units": 3.14
    }
  ],
  "reference": "123"
}

Properties

Name	Description
id `string`	Resource identifier (UUID)
invoice_status `string`	The status of an Invoice Possible values: `draft`, `sent`
customer_id `string`	Resource identifier (UUID)
invoice_number `string`	The generated unique Invoice number for this Invoice (only set when an Invoice is sent)
invoice_date `string(date)`	Date of the Invoice (determines the VAT period)
invoice_due_date `string(date)`	When the Invoice should be paid
invoice_delivery_period `string(date)`	Determines the profit and loss period of this Invoice
invoice_date_sent `string(date)`	When the Invoice was sent
invoice_total Amount	Total amount of the Invoice excluding VAT
invoice_total_incl_vat Amount	Total amount of the Invoice including VAT
send_method `string`	How the Invoice should be sent Possible values: `email`, `self`
net_amounts `boolean`	Whether or not VAT is included in the `amount_per_unit` in the line item (this is typically used when invoicing a private person rather than a company)
invoice_marked_free_of_vat `boolean`	Whether or not an Invoice is marked as having no VAT
credited_invoice_id `string`	Resource identifier (UUID) of the credited Invoice
remarks `string`	Remarks printed on the Invoice (under the line items)
introduction `string`	Comments printed on the Invoice (above the line items)
number_of_reminders_sent `integer(int32)`	Number of reminders sent to the Customer
last_reminded_at `string(date)`	When the last reminder was sent to the Customer
payment_method `string`	How the Invoice can be paid. Determines the payment instructions printed on the Invoice. Choose from: `already_paid` when the Invoice has already been paid. No payment instructions will be printed on the Invoice. `pay_later` will print payment instructions on the Invoice. `direct_debit` requires a connection with Mollie. Only for Jortt Plus users. The default is `pay_later`. Possible values: `pay_later`, `direct_debit`, `already_paid`
customer_company_name `string`	Either a company name (when `is_private` is `false`) or a private person's full name (when `is_private` is `true`)
customer_attn `string`	To the attention of
customer_address_street `string`	Street and house number of the address of a Customer (required when `is_private` is `false`)
customer_address_city `string`	City of the address of a Customer (required when `is_private` is `false`)
customer_address_postal_code `string`	Postal code of the address of a Customer (required when `is_private` is `false`)
customer_address_country_code `string`	Country code of a Customer in ISO 3166-1 alpha-2 format (required when `is_private` is `false`, defaults to `NL`)
customer_address_country_name `string`	Country name of a Customer (applicable when `is_private` is `false`, defaults to `NL`)
customer_address_extra_information `string`	Extra line of Customer address information
customer_vat_shifted `boolean`	Whether or not to shift the VAT for a Customer (applicable when `is_private` is `false`)
customer_vat_number `string`	The VAT number (BTW-nummer) of a Customer (applicable when `is_private` is `false` and `shift_vat` is `true`)
customer_in_eu `boolean`	Whether or not the Customer is in the EU (at the time of sending the Invoice)
customer_reference `string`	Custom reference (for example the ID of a customer in an external CRM)
customer_mail_to `string`	E-mail address to send the Invoice to
customer_mail_cc_addresses `string`	A comma-separated list of e-mail addresses to CC when the Invoice is sent
language `string`	The language in which the Invoice will be translated Possible values: `nl`, `de`, `en`, `fr`, `es`
line_items [LineItem]	line items of the invoice
reference `string`	Custom reference (for example an order ID)

LineItem

A line item of an Invoice. The amount can be including or excluding VAT. This is determined by the net_amounts attribute in the Invoice this line item belongs to.

{
  "description": "this is a description example",
  "vat": 21,
  "amount_per_unit": {
    "value": "365.00",
    "currency": "EUR"
  },
  "total_amount_excl_vat": {
    "value": "365.00",
    "currency": "EUR"
  },
  "units": 3.14
}

Properties

Name	Description
description `string`	Description of the line item
vat `integer(int64)`	VAT rate of the line item Possible values: `21`, `9`, `0`
amount_per_unit Amount	Amount of the line item
total_amount_excl_vat Amount	Amount of the line item
units `number(double)`	Number of units of the line item

Error

{
  "code": 422,
  "key": "params.invalid",
  "message": "The parameters are invalid (either missing, not of the correct type or incorrect format).",
  "details": [
    {
      "key": "is_missing",
      "message": "is missing",
      "param": "customer_id"
    }
  ]
}

Properties

Name	Description
code `integer(int32)`	HTTP response status code of the error Possible values: `401`, `404`, `405`, `409`, `422`, `500`, `503`
key `string`	A machine readable (and constant) key describing the error Possible values: `access_token.invalid`, `access_token.expired`, `access_token.revoked`, `scopes.insufficient`, `organization.non_existing`, `organization.requires_paid_plan`, `user.non_existing`, `endpoint.not_found`, `resource.not_found`, `resource.method_not_allowed`, `resource.conflict`, `params.invalid`, `operation.invalid`, `server.internal_error`, `server.maintenance`
message `string`	A human readable message describing the error
details [ErrorDetail]	A list of details for the error (can be empty)

ErrorDetail

{
  "key": "is_missing",
  "message": "is missing",
  "param": "customer_id"
}

Properties

Name	Description
key `string`	A machine readable (and constant) key describing the error detail
message `string`	A human readable message describing the error detail
param `string`	The path of the param that is faulty (can be absent)

Jortt API v1.0.0-beta

Disclaimer

Introduction

Connecting

Making requests

Success response

Request example

Response example

Error response

Request example

Response example

Errors

Authentication

OAuth2 authentication

Flow: authorizationCode

Scopes

Customers

Update Customer

Permissions

Parameters

Responses

Get Customer by ID

Permissions

Parameters

Responses

Create Customer

Permissions

Parameters

Responses

List Customers

Permissions

Parameters

Responses

Invoices

Create (and optionally send) an Invoice

Permissions

Parameters

Responses

Get Invoice by ID

Permissions

Parameters

Responses

Schemas

UpdateCustomer

Properties

CreateCustomer

Properties

ResourceCreatedResponse

Properties

GetCustomerResponse

Properties

Customer

Properties

ListCustomersResponse

Properties

Amount

Properties

CreateInvoice

Properties

GetInvoiceResponse

Properties

Invoice

Properties

LineItem

Properties

Error

Properties

ErrorDetail

Properties

Flow: `authorizationCode`