NAV Navbar
cURL

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:

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:

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

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)