Jortt API v1.0.0

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.

Test with Postman app

The Run in Postman button imports and opens the Jortt collection of API endpoints directly in your Postman app. Ready to create your first customer and invoice via the API.

To get an Access token, edit the Jortt API collection, go to the Authorization tab and use the Get New Access Token button.

Connecting

Connecting your application with the Jortt API requires you to register your application as a client in our authorization server. We support the following OAuth 2.0 grant types:

• Authorization code (for third party apps, for example a webshop)
• Client credentials (for your own app)

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

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

Authorization code grant type

The authorization_code grant type should be used by third party applications (for example a webshop) that can be used by any Jortt administration. If you are developing an application just for your own administration, you must use the client credentials grant type.

The following links describe the authorization_code grant type in detail:

• OAuth.net
• Article from Digital Ocean
• Official RFC

For the authorization_code grant type, you don't necessarily need access to a Jortt account (although it may be handy for testing). You can always sign up for a free Jortt account.

In order to use the authorization_code grant type, please send an e-mail to support@jortt.nl to register your application and provide the following information:

• Application name
• Redirect URL
• Required scopes

Getting a Jortt adminstration's (read: user's) consent

Your application first needs to decide which permissions it is requesting, then send the user to a browser to get their permission. To begin the authorization flow, the application constructs a URL like the following and open a browser to that URL.

curl https://app.jortt.nl/oauth-provider/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=YOUR_SCOPES&state=RANDOM_STRING

When the user visits this URL, it will present them with a prompt asking if they would like to authorize your application's request.

If the user approves the request, Jortt will redirect the browser back to the redirect_uri specified by your application, adding a code to the query string along with the provided state parameter.

Obtaining an access token

For example:

curl -X POST -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" -d "grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI" https://app.jortt.nl/oauth-provider/oauth/token

Would respond with:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "YOUR_SCOPES",
  "created_at": 1587717832
}

Refreshing a token

For example:

curl -X POST -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" -d "grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN" https://app.jortt.nl/oauth-provider/oauth/token

Would respond with:

{
  "access_token": "YOUR_NEW_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "YOUR_NEW_REFRESH_TOKEN",
  "scope": "YOUR_SCOPES",
  "created_at": 1587717832
}

Client credentials grant type

The client_credentials grant type should be used by applications that you've built solely for your own administration (the application is bound to the administration that created it). If you are developing an application that should be accessible for all Jortt administrations (for example a webshop), you must use the authorization code grant type.

The following links describe the client_credentials grant type in detail:

• OAuth.net
• Article from Digital Ocean
• Official RFC

You will need to have access to a Jortt account, and register your application.

Obtaining an access token

For example:

curl -X POST -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" -d "grant_type=client_credentials&scope=YOUR_SCOPES" https://app.jortt.nl/oauth-provider/oauth/token

Would respond with:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "YOUR_SCOPES",
  "created_at": 1588331418
}

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/c4075eb6-2028-457e-817f-a6a8d4703fbb -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 POST https://api.jortt.nl/customers -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.

Rate limiting

In order to ensure fair performance of our API we have rate limits in place. This limit is set to 10 requests per second.

Pagination

Fetching all objects of a resource can be convenient. At the same time, returning too many objects at once can be unpractical from a performance perspective.

Doing so might be too much work for the Jortt API to generate, or for your system to process.

For this reason in the case of a request that should return a list of objects, the Jortt API only returns a subset of the requested set of objects. In other words, the Jortt API chops the result of a certain API method call into pages you are able to programmatically scroll through.

The maximum number of objects returned per page is 100.

In those cases, a successful response body will contain a data key and a _links key with extra information to be able to paginate. links

For example:

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

Would respond with:

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

{
  "data": [
    {
      "id": "c4075eb6-2028-457e-817f-a6a8d4703fbb",
      ... more properties
    }
    {
      "id": "d453034d-6a33-44b3-8d5f-f962beeeb956",
      ... more properties
    }
    ... more objects
  ]
  "_links": {
      "self": {
        "href": "https://api.jortt.nl/customers?query=bob?page=1",
        "type": "application/json"
      },
      "previous": null,
      "next": {
        "href": "https://api.jortt.nl/customers?query=bob?page=2",
        "type": "application/json"
      },
      "documentation": {
        "href": "https://developer.jortt.nl/#pagination",
        "type": "application/json"
      },
  }
}

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

Base URL Jortt API:

• https://api.jortt.nl

Authentication

OAuth 2.0 Authorization Code

Flow: authorizationCode

Learn how to connect your application using the Authorization Code grant type.

Scopes

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

OAuth 2.0 Client Credentials

Flow: clientCredentials

Learn how to connect your application using the Client Credentials grant type.

Scopes

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

Resources

v2

Operations about v2s

List Invoices v2

GET /v2/invoices

If the query is null (e.g GET /invoices), it will retrieve all Invoices ordered by created_at. Otherwise if a query is passed (e.g GET /invoices?query=foo), it will search and list only the Invoices matching the query, ordered by created_at. If the invoice_status is null (e.g GET /invoices), it will retrieve all Invoices ordered by created_at. Otherwise if a invoice_status is passed (e.g GET /invoices?invoice_status=draft), it will search and list only the Invoices matching the invoice_status with status draft, ordered by created_at. .

Returns a list of Invoices

Permissions

This operation requires the following OAuth2 scopes: invoices:read

Parameters

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/v2/invoices \
  -H 'Accept: application/json'

Responses

Get Invoice by ID v2

GET /v2/invoices/{id}

Returns an Invoice by ID.

Permissions

This operation requires the following OAuth2 scopes: invoices:read

Parameters

Code samples

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

Responses

Invoices

Create (and optionally send) an Invoice V2

POST /v2/invoices

When the optional send_method is not provided, the Invoice will be created as a Draft.

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 otherwise it will be draft). .

Creates (and optionally sends) an Invoice V2

Permissions

This operation requires the following OAuth2 scopes: invoices:write

Parameters

Code samples

# You can also use wget
curl -X POST https://api.jortt.nl/v2/invoices \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Example body values

{
  "customer_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "invoice_date": "2020-02-23",
  "tradename_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "label_ids": [
    "string"
  ],
  "delivery_period": "2020-02-01",
  "delivery_period_end": "2020-02-01",
  "payment_term": 14,
  "net_amounts": true,
  "send_method": "email",
  "introduction": "example",
  "remarks": "example",
  "payment_method": "pay_later",
  "line_items": [
    {
      "description": "this is a description example",
      "quantity": {
        "amount": "string",
        "currency": "string"
      },
      "amount": {
        "amount": "string",
        "currency": "string"
      },
      "vat": {
        "value": "0.21",
        "category": "exempt"
      },
      "ledger_account_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a"
    }
  ],
  "discounts": [
    {
      "description": "this is a description example",
      "percentage": 21
    }
  ],
  "reference": "123",
  "sold_via_platform": true
}

Responses

Edit Invoice V2

PUT /v2/invoices/{id}

Edits an invoice, provided said invoice has not been finalized. NOTE: You may receive unexpected errors if any data on the invoice is invalid. When correcting invalid data only the relevant fields should be filled. .

Edits an Invoice V2

Permissions

This operation requires the following OAuth2 scopes: invoices:write

Parameters

Code samples

# You can also use wget
curl -X PUT https://api.jortt.nl/v2/invoices/{id} \
  -H 'Content-Type: application/json'

Example body values

{
  "customer_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "invoice_date": "2020-02-23",
  "tradename_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "label_ids": [
    "string"
  ],
  "delivery_period": "2020-02-01",
  "delivery_period_end": "2020-02-01",
  "payment_term": 14,
  "net_amounts": true,
  "send_method": "email",
  "introduction": "example",
  "remarks": "example",
  "payment_method": "pay_later",
  "line_items": [
    {
      "description": "this is a description example",
      "quantity": {
        "amount": "string",
        "currency": "string"
      },
      "amount": {
        "amount": "string",
        "currency": "string"
      },
      "vat": {
        "value": "0.21",
        "category": "exempt"
      },
      "ledger_account_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a"
    }
  ],
  "discounts": [
    {
      "description": "this is a description example",
      "percentage": 21
    }
  ],
  "reference": "123"
}

Responses

Get Invoice by ID

GET /invoices/{id}

Returns an Invoice by ID.

Permissions

This operation requires the following OAuth2 scopes: invoices:read

Parameters

Code samples

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

Responses

Edit Invoice

PUT /invoices/{id}

Edits an invoice, provided said invoice has not been finalized. NOTE: This operation will overwrite existing invoice data for all fields, fields that are not supplied will be nulled. .

Edits an Invoice

Permissions

This operation requires the following OAuth2 scopes: invoices:write

Parameters

Code samples

# You can also use wget
curl -X PUT https://api.jortt.nl/invoices/{id} \
  -H 'Content-Type: application/json'

Example body values

{
  "customer_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "invoice_date": "2020-02-23",
  "tradename_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "label_ids": [
    "string"
  ],
  "delivery_period": "2020-02-01",
  "delivery_period_end": "2020-02-01",
  "payment_term": 14,
  "net_amounts": true,
  "send_method": "email",
  "introduction": "example",
  "remarks": "example",
  "payment_method": "pay_later",
  "invoice_marked_free_of_vat": true,
  "line_items": [
    {
      "description": "this is a description example",
      "number_of_units": "3.14",
      "amount_per_unit": {
        "value": "365.00",
        "currency": "EUR"
      },
      "vat": 21,
      "vat_percentage": "21.0",
      "ledger_account_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
      "units": "string"
    }
  ],
  "discounts": [
    {
      "description": "this is a description example",
      "percentage": 21
    }
  ],
  "reference": "123"
}

Responses

Delete Invoice by ID

DELETE /invoices/{id}

Deletes an Invoice by ID.

Permissions

This operation requires the following OAuth2 scopes: invoices:write

Parameters

Code samples

# You can also use wget
curl -X DELETE https://api.jortt.nl/invoices/{id}

Responses

Set invoice labels

PUT /invoices/{id}/set_labels

Sets the labels for a given invoice .

Sets the labels for a given invoice

Permissions

This operation requires the following OAuth2 scopes: invoices:write

Parameters

Code samples

# You can also use wget
curl -X PUT https://api.jortt.nl/invoices/{id}/set_labels \
  -H 'Content-Type: application/json'

Example body values

[
  {
    "label_ids": [
      "string"
    ]
  }
]

Responses

Creates (and optionally sends) a credit Invoice

POST /invoices/{id}/credit

When the optional send_method is not provided, the Invoice will be created as a Draft.

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 been sent (the returned Invoice's invoice_status attribute is then set to sent otherwise it will be draft). .

Creates (and optionally sends) a credit Invoice

Permissions

This operation requires the following OAuth2 scopes: invoices:write

Parameters

Code samples

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

Example body values

{
  "send_method": "email"
}

Responses

List Invoices

GET /invoices

If the query is null (e.g GET /invoices), it will retrieve all Invoices ordered by created_at.

Otherwise if a query is passed (e.g GET /invoices?query=foo), it will search and list only the Invoices matching the query, ordered by created_at.

If the invoice_status is null (e.g GET /invoices), it will retrieve all Invoices ordered by created_at.

Otherwise if a invoice_status is passed (e.g GET /invoices?invoice_status=draft), it will search and list only the Invoices matching the invoice_status with status draft, ordered by created_at. .

Returns a list of Invoices

Permissions

This operation requires the following OAuth2 scopes: invoices:read

Parameters

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/invoices \
  -H 'Accept: application/json'

Responses

Create (and optionally send) an Invoice

POST /invoices

When the optional send_method is not provided, the Invoice will be created as a Draft.

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 otherwise it will be draft). .

Creates (and optionally sends) an Invoice

Permissions

This operation requires the following OAuth2 scopes: invoices:write

Parameters

Code samples

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

Example body values

{
  "customer_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "invoice_date": "2020-02-23",
  "tradename_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
  "label_ids": [
    "string"
  ],
  "delivery_period": "2020-02-01",
  "delivery_period_end": "2020-02-01",
  "payment_term": 14,
  "net_amounts": true,
  "send_method": "email",
  "introduction": "example",
  "remarks": "example",
  "payment_method": "pay_later",
  "line_items": [
    {
      "description": "this is a description example",
      "units": 3.14,
      "number_of_units": "3.14",
      "amount_per_unit": {
        "value": "365.00",
        "currency": "EUR"
      },
      "vat": 21,
      "vat_percentage": "21.0",
      "ledger_account_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a"
    }
  ],
  "discounts": [
    {
      "description": "this is a description example",
      "percentage": 21
    }
  ],
  "reference": "123",
  "sold_via_platform": true
}

Responses

Download Invoice PDF

GET /invoices/{id}/download

Only returns a URL for sent invoices. Will fail otherwise.

Note: The returned URL expires after 10 minutes. .

Returns a URL from which the invoice PDF can be downloaded.

Permissions

This operation requires the following OAuth2 scopes: invoices:read

Parameters

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/invoices/{id}/download \
  -H 'Accept: application/pdf'

Responses

Get next possible invoice number

GET /invoices/{id}/next_possible_invoice_number

Returns the next possible invoice number.

Permissions

This operation requires the following OAuth2 scopes: invoices:read

Parameters

Code samples

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

Responses

Get line item suggestions

GET /invoices/{id}/line_item_suggestions

Returns a list of suggested line items for a given invoice based on the given query. The invoice must have an associated customer or 404 is returned. .

Returns a list of suggested line items

Permissions

This operation requires the following OAuth2 scopes: invoices:read

Parameters

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/invoices/{id}/line_item_suggestions?query=string \
  -H 'Accept: application/json'

Responses

Send Invoice

POST /invoices/{id}/send

Sends an invoice by the method indicated in the params. If email is selected additional parameters must be provided as indicated. .

Sends an Invoice

Permissions

This operation requires the following OAuth2 scopes: invoices:write

Parameters

Code samples

# You can also use wget
curl -X POST https://api.jortt.nl/invoices/{id}/send \
  -H 'Content-Type: application/json'

Example body values

{
  "send_method": "email",
  "email_address_customer": "string",
  "mail_subject": "string",
  "mail_body": "string",
  "send_copy_to_me": true,
  "cc_addresses": [
    "string"
  ],
  "attachment_ids": [
    "string"
  ],
  "attachment_mime_types": [
    "string"
  ]
}

Responses

Get send settings

GET /invoices/{id}/send_settings

Returns the current send settings for the invoice.

Permissions

This operation requires the following OAuth2 scopes: invoices:read

Parameters

Code samples

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

Responses

Copy an Invoice

POST /invoices/{id}/copy

Creates an unsent copy of a sent invoice. .

Copies an Invoice

Permissions

This operation requires the following OAuth2 scopes: invoices:write

Parameters

Code samples

# You can also use wget
curl -X POST https://api.jortt.nl/invoices/{id}/copy \
  -H 'Accept: application/json'

Responses

Customers

Get vat percentages for a Customer by ID V2

GET /v2/customers/{customer_id}/vat-percentages

Returns vats that are valid on today's date for a Customer by ID.

Permissions

This operation requires the following OAuth2 scopes: customers:read

Parameters

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/v2/customers/{customer_id}/vat-percentages \
  -H 'Accept: application/json'

Responses

List Customers

GET /customers

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

If the query is null (e.g GET /customers), it will retrieve all Customers in alphabetical order of customer_name.

Otherwise if a query is passed (e.g GET /customers?query=foo), it will search and list only the Customers matching the query, ordered alphabetically on customer_name`. .

Returns a list of Customers

Permissions

This operation requires the following OAuth2 scopes: customers:read

Parameters

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/customers \
  -H 'Accept: application/json'

Responses

Create Customer

POST /customers

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. .

Creates a Customer

Permissions

This operation requires the following OAuth2 scopes: customers:write

Parameters

Code samples

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

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",
  "default_label_id": "57aab2d0-16b8-013d-3d2c-42742b204134",
  "default_ledger_account_id": "61a5b600-16bc-013d-3d2d-42742b204134",
  "default_discount_description": "this is a description example",
  "default_discount_percentage": 21
}

Responses

Get Customer by ID

GET /customers/{customer_id}

Returns a Customer by ID.

Permissions

This operation requires the following OAuth2 scopes: customers:read

Parameters

Code samples

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

Responses

Update Customer

PUT /customers/{customer_id}

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. .

Updates a Customer

Permissions

This operation requires the following OAuth2 scopes: customers:write

Parameters

Code samples

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

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",
  "default_label_id": "57aab2d0-16b8-013d-3d2c-42742b204134",
  "default_ledger_account_id": "61a5b600-16bc-013d-3d2d-42742b204134",
  "default_discount_description": "this is a description example",
  "default_discount_percentage": 21
}

Responses

Delete a Customer

DELETE /customers/{customer_id}

No required attributes to be passed.

This call will delete a customer. Then the Customer deleted attribute will be true. .

Delete a Customer

Permissions

This operation requires the following OAuth2 scopes: customers:write

Parameters

Code samples

# You can also use wget
curl -X DELETE https://api.jortt.nl/customers/{customer_id}

Responses

Get Customer's details by ID

GET /customers/{customer_id}/extra_details

Returns a Customer's details by ID.

Permissions

This operation requires the following OAuth2 scopes: customers:read

Parameters

Code samples

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

Responses

Get vat percentages for a Customer by ID

GET /customers/{customer_id}/vat-percentages

Returns vat percentages that are valid on today's date for a Customer by ID.

Permissions

This operation requires the following OAuth2 scopes: customers:read

Parameters

Code samples

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

Responses

Send direct debit authorization to a Customer

POST /customers/{customer_id}/direct_debit_mandate

No required attributes to be passed.

This call will send an e-mail to the customer with a request for an authorization payment, typically 1 or 2 cents, in order to be able to direct debit the customer. Only when the customer pays the authorization payment the direct debit for this customer is enabled. If so the Customer mollie_direct_debit_status will be mollie_direct_debit_accepted and it will have a mollie_mandate_id. .

Send direct debit authorization to a Customer

Permissions

This operation requires the following OAuth2 scopes: customers:write

Parameters

Code samples

# You can also use wget
curl -X POST https://api.jortt.nl/customers/{customer_id}/direct_debit_mandate

Responses

Set Customer Archived

PUT /customers/{customer_id}/set_archived

This call will set the archived status on a customer. Archived customers act as though deleted, but can be unarchived at a later point .

Sets the archived status for a customer

Permissions

This operation requires the following OAuth2 scopes: customers:write

Parameters

Code samples

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

Example body values

{
  "archived": true
}

Responses

Tradenames

List tradenames

GET /tradenames

A tradename is the name under which your business trades. The tradename is often the same as the name in your company's deed of incorporation, but it can also be different. A business can, for instance, use different tradenames for different activities.

GET /tradenames it will retrieve all Tradenames in alphabetical order of company_name. .

Returns a list of tradenames

Permissions

This operation requires the following OAuth2 scopes: organizations:read

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/tradenames \
  -H 'Accept: application/json'

Responses

Ledger Accounts

List Invoice Ledger Accounts

GET /ledger_accounts/invoices

Returns the list of Ledger Accounts that can be used to categorize Line Items on an Invoice for in your Profit and Loss report. .

Permissions

This operation requires the following OAuth2 scopes: invoices:write

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/ledger_accounts/invoices \
  -H 'Accept: application/json'

Responses

getV1LedgerAccountsInvoicesDefault

GET /v1/ledger_accounts/invoices/default

.

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/v1/ledger_accounts/invoices/default

Responses

getLedgerAccountsInvoicesDefault

GET /ledger_accounts/invoices/default

.

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/ledger_accounts/invoices/default

Responses

Labels

List labels

GET /labels

GET /labels will retrieve all Labels in alphabetical order of description. .

Returns a list of labels

Permissions

This operation requires the following OAuth2 scopes: organizations:read

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/labels \
  -H 'Accept: application/json'

Responses

Create a Label

POST /labels

POST /labels Will create a label and return a representative uuid. .

Create a label

Permissions

This operation requires the following OAuth2 scopes: organizations:write

Parameters

Code samples

# You can also use wget
curl -X POST https://api.jortt.nl/labels \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Example body values

{
  "description": "My Label"
}

Responses

Organizations

Get the organization associated with the api credentials

GET /organizations/me

Get the current Organization.

Permissions

This operation requires the following OAuth2 scopes: organizations:read

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/organizations/me \
  -H 'Accept: application/json'

Responses

Loonjournaalposten

List Loonjournaalposten

GET /loonjournaalposten

If the year is null (e.g GET /payroll/loonjournaalposten), it will retrieve all Loonjournaalposten ordered by period_date.

Otherwise if a year is passed (e.g GET /payroll/loonjournaalposten?year=2022), it will search and list only the Loonjournaalposten matching the year, ordered by period_date. .

Returns a list of Loonjournaalposten

Permissions

This operation requires the following OAuth2 scopes: payroll:read

Parameters

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/loonjournaalposten \
  -H 'Accept: application/json'

Responses

Create a Loonjournaalpost

POST /loonjournaalposten

POST /loonjournaalposten Will create a Loonjournaalpost and return a representative uuid. .

Create a Loonjournaalpost

Permissions

This operation requires the following OAuth2 scopes: payroll:write

Parameters

Code samples

# You can also use wget
curl -X POST https://api.jortt.nl/loonjournaalposten \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Example body values

{
  "period_date": "2023-10-01",
  "bruto_loon": {
    "value": "365.00",
    "currency": "EUR"
  },
  "werkgeversdeel_sociale_lasten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "werkgeversdeel_pensioenkosten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "reservering_vakantiegeld": {
    "value": "365.00",
    "currency": "EUR"
  },
  "reservering_eindejaarsuitkering": {
    "value": "365.00",
    "currency": "EUR"
  },
  "onbelaste_reiskostenvergoedingen": {
    "value": "365.00",
    "currency": "EUR"
  },
  "onbelaste_vergoedingen_gericht_vrijgesteld": {
    "value": "365.00",
    "currency": "EUR"
  },
  "onbelaste_vergoedingen_wkr": {
    "value": "365.00",
    "currency": "EUR"
  },
  "declaraties_algemeen": {
    "value": "365.00",
    "currency": "EUR"
  },
  "declaraties_kantoorkosten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "declaraties_lunch_en_diner_representatiekosten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "declaraties_reiskosten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "declaraties_auto_en_transportkosten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "declaraties_verkoopkosten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "eindheffing_wkr": {
    "value": "365.00",
    "currency": "EUR"
  },
  "netto_inhoudingen": {
    "value": "365.00",
    "currency": "EUR"
  },
  "afdrachtvermindering_speur_en_ontwikkelingswerk": {
    "value": "365.00",
    "currency": "EUR"
  },
  "te_betalen_nettolonen": {
    "value": "365.00",
    "currency": "EUR"
  },
  "te_betalen_sociale_lasten_loonbelasting": {
    "value": "365.00",
    "currency": "EUR"
  },
  "te_betalen_pensioenpremies": {
    "value": "365.00",
    "currency": "EUR"
  },
  "te_betalen_vakantiegeld": {
    "value": "365.00",
    "currency": "EUR"
  },
  "te_betalen_eindejaarsuitkering": {
    "value": "365.00",
    "currency": "EUR"
  },
  "te_betalen_loonbeslag": {
    "value": "365.00",
    "currency": "EUR"
  }
}

Responses

Update a Loonjournaalpost

PUT /loonjournaalposten/{loonjournaalpost_id}

Update a Loonjournaalpost by ID .

Update a Loonjournaalpost

Permissions

This operation requires the following OAuth2 scopes: payroll:write

Parameters

Code samples

# You can also use wget
curl -X PUT https://api.jortt.nl/loonjournaalposten/{loonjournaalpost_id} \
  -H 'Content-Type: application/json'

Example body values

{
  "bruto_loon": {
    "value": "365.00",
    "currency": "EUR"
  },
  "werkgeversdeel_sociale_lasten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "werkgeversdeel_pensioenkosten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "reservering_vakantiegeld": {
    "value": "365.00",
    "currency": "EUR"
  },
  "reservering_eindejaarsuitkering": {
    "value": "365.00",
    "currency": "EUR"
  },
  "onbelaste_reiskostenvergoedingen": {
    "value": "365.00",
    "currency": "EUR"
  },
  "onbelaste_vergoedingen_gericht_vrijgesteld": {
    "value": "365.00",
    "currency": "EUR"
  },
  "onbelaste_vergoedingen_wkr": {
    "value": "365.00",
    "currency": "EUR"
  },
  "declaraties_algemeen": {
    "value": "365.00",
    "currency": "EUR"
  },
  "declaraties_kantoorkosten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "declaraties_lunch_en_diner_representatiekosten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "declaraties_reiskosten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "declaraties_auto_en_transportkosten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "declaraties_verkoopkosten": {
    "value": "365.00",
    "currency": "EUR"
  },
  "eindheffing_wkr": {
    "value": "365.00",
    "currency": "EUR"
  },
  "netto_inhoudingen": {
    "value": "365.00",
    "currency": "EUR"
  },
  "afdrachtvermindering_speur_en_ontwikkelingswerk": {
    "value": "365.00",
    "currency": "EUR"
  },
  "te_betalen_nettolonen": {
    "value": "365.00",
    "currency": "EUR"
  },
  "te_betalen_sociale_lasten_loonbelasting": {
    "value": "365.00",
    "currency": "EUR"
  },
  "te_betalen_pensioenpremies": {
    "value": "365.00",
    "currency": "EUR"
  },
  "te_betalen_vakantiegeld": {
    "value": "365.00",
    "currency": "EUR"
  },
  "te_betalen_eindejaarsuitkering": {
    "value": "365.00",
    "currency": "EUR"
  },
  "te_betalen_loonbeslag": {
    "value": "365.00",
    "currency": "EUR"
  }
}

Responses

Delete a Loonjournaalpost

DELETE /loonjournaalposten/{loonjournaalpost_id}

No required attributes to be passed.

This call will delete a loonjournaalpost. .

Delete a Loonjournaalpost

Permissions

This operation requires the following OAuth2 scopes: payroll:write

Parameters

Code samples

# You can also use wget
curl -X DELETE https://api.jortt.nl/loonjournaalposten/{loonjournaalpost_id}

Responses

Reports

Dashboard invoices

GET /reports/summaries/invoices

Gets summarized Invoice data intended for dashboard display. Summaries reflect invoices for the current year, grouped by payment status. .

Returns a summary of invoices for the current year

Permissions

This operation requires the following OAuth2 scopes: reports:read

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/reports/summaries/invoices \
  -H 'Accept: application/json'

Responses

Dashboard btw

GET /reports/summaries/btw

Gets a list summarized BTW period data intended for dashboard display. .

Returns a list of summarized btw periods

Permissions

This operation requires the following OAuth2 scopes: reports:read

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/reports/summaries/btw \
  -H 'Accept: application/json'

Responses

Dashboard balance

GET /reports/summaries/balance

Return organization balances for dashboard display. Balances presented are reflective of the current date. .

Returns key organization balances for the current date

Permissions

This operation requires the following OAuth2 scopes: reports:read

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/reports/summaries/balance \
  -H 'Accept: application/json'

Responses

Dashboard profit and loss

GET /reports/summaries/profit_and_loss

Gets a summarized report for profit and loss this year up until the current date. .

Returns a summary of profit and loss for the current year

Permissions

This operation requires the following OAuth2 scopes: reports:read

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/reports/summaries/profit_and_loss \
  -H 'Accept: application/json'

Responses

Dashboard cash and bank

GET /reports/summaries/cash_and_bank

Returns summaries of all organization bank accounts, liquid assets and cash balances intended for dashboard display. .

Returns a summary of bank accounts, cash and liquid assets

Permissions

This operation requires the following OAuth2 scopes: reports:read

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/reports/summaries/cash_and_bank \
  -H 'Accept: application/json'

Responses

Inbox

Upload receipt

POST /inbox/images

A simple endpoint where one can upload images to jortt, typically used to upload receipts. .

Upload images to jortt

Permissions

This operation requires the following OAuth2 scopes: inbox:write

Parameters

Code samples

# You can also use wget
curl -X POST https://api.jortt.nl/inbox/images \
  -H 'Content-Type: application/json'

Example body values

[
  {
    "images": [
      "string"
    ]
  }
]

Responses

Projects

List Projects

GET /projects

Returns a paginated list of projects ordered by creation date. 10 items are provided per page .

Returns a list of Projects

Permissions

This operation requires the following OAuth2 scopes: invoices:read

Parameters

Code samples

# You can also use wget
curl -X GET https://api.jortt.nl/projects \
  -H 'Accept: application/json'

Responses