Introduction

Welcome to the Incassomanager API Documentation. On this page we will try to explain to you the basic ways and principles for using our api.

What do you need to do for using this api?

  1. Register your account at https://incassomanager.nl
  2. Create your company profile at https://incassomanager.nl/company/add
  3. Download your api key at https://incassomanager.nl/company

Remember! Every company that you create has its own api-key.


API Usage

Our api accepts json requests:

Content-Type: application/json

You need to send your API Key as a HTTP header with every request you are trying to make (see the sample PHP class).

X-Auth-Token: your-authentication-token

<?php

// include the Api php class
include 'path/to/Api.php';

// create the Api class instance
$api = new Api('https://api.incassomanager.nl','your-api-key');
            

Debtors

Debtors are the persons or companies that did not pay their invoice. Any dossier that you want to create needs to be connected to a debtor.


List debtors

Use this method to retreive a list of debtors that you have already created in our system.

The response will look like this:

{
    'debtors' => [
        [ debtor number 1 ],
        [ debtor number 2 ],
    ],
    'pager' => [
        'next'  => '/debtor?page=1', // null if there is no next page available
        'pages' => 2 // (int) the total amount of pages
    ]
}


// List debtors
if($api->get('/debtor')) {
    print_r($api->response);
} else {
    print_r($api->error);
}
            

Create debtor

Possible errors

  • Invalid debtor information
    The messages field contains specific error information


// define the debtor information in an array
$debtor = [
    'company'         => 'The Company',
    'reference'       => '1',   // your internal reference
    'type'            => 'company', // company OR person
    'email'           => 'email@address.com',
    'contact'         => 'Contact person',
    'phone'           => '(012)3456789',
    'coc_number'      => 'COC',
    'vat_number'      => 'VAT',
    'bank_number'     => 'IBAN',
    'address_line1'   => 'Street address 123',
    'address_line2'   => '',
    'address_zipcode' => '1234AA',
    'address_city'    => 'City name',
];

// Post debtor to our api
if($api->post('/debtor', $debtor)) {
    print_r($api->response->debtor);
} else {
    print_r($api->error);
    print_r($api->response->messages);
}
            

Update debtor

Use this method to update the information that you have on a debtor, to keep our database as up-to-date as possible.

Possible errors

  • Invalid debtor
    When the debtor does not exists in our database
  • Invalid debtor information
    The messages field contains specific error information


// define the debtor information in an array
$debtor = [
    'company'         => 'The Company (updated)',
    'reference'       => '1',
    'type'            => 'company',
    'email'           => 'email@address.com',
    'contact'         => 'Contact person',
    'phone'           => '(012)3456789',
    'coc_number'      => 'COC',
    'vat_number'      => 'VAT',
    'bank_number'     => 'IBAN',
    'address_line1'   => 'Street address 123',
    'address_line2'   => '',
    'address_zipcode' => '1234AA',
    'address_city'    => 'City name',
];

// Patch debtor to our api
if($api->patch('/debtor/' . $debtor['id'], $debtor)) {
    print_r($api->response->debtor);
} else {
    print_r($api->error);
    print_r($api->response->messages);
}
            

Get a specific debtor

Use this method to retrieve a specific debtor that you have already created in our system.

The response will look like this:

{
    'debtor' => [
        'id' => 1,
        ...
    ]
}

Possible errors

  • Invalid debtor
    When the debtor does not exists in our database


// List debtors
if($api->get('/debtor')) {
    print_r($api->response);
} else {
    print_r($api->error);
}
            

Dossiers

The dossier is what this system is all about. A dossier is connected to a single debtor, and can contain multiple invoices.


Dossier states

This method will give you a list of possible dossier states and their meaning.

The response will look like this:

{
    "statuses": {
        "PRE_DEMAND": {
            "name": "Pre-incasso",
            "closed": 0
        },
        "FIRST_DEMAND": {
            "name": "Eerste aanmaning",
            "closed": 0
        },
        "SECOND_DEMAND": {
            "name": "Tweede aanmaning",
            "closed": 0
        },
        "ANNOUNCE_COURT": {
            "name": "Aankondiging rechtsmaatregelen",
            "closed": 0
        },
        "ANNOUNCE_SUBPENA": {
            "name": "Aankondiging dagvaarding",
            "closed": 0
        },
        "PARTIAL_PAYMENT": {
            "name": "Deelbetaling",
            "closed": 0
        },
        "INVOICE_PAYMENT": {
            "name": "Hoofdsom voldaan \\/ aanspraak incassokosten",
            "closed": 0
        },
        "INVOICE_PAYMENT_DEMAND": {
            "name": "Laatste aanmaning R&I",
            "closed": 0
        },
        "PAYMENT_ARRANGEMENT": {
            "name": "Betalingsregeling",
            "closed": 0
        },
        "CLOSED_PRE_DEMAND": {
            "name": "Vordering gesloten na pre-incasso",
            "closed": 1
        },
        "CLOSED_NO_PROVISION": {
            "name": "Teruggetrokken zonder provisie",
            "closed": 1
        },
        "CLOSED_CREDITOR": {
            "name": "Gesloten in opdracht klant",
            "closed": 1
        },
        "CLOSED_NON_DEMANDABLE": {
            "name": "Niet incasseerbaar",
            "closed": 1
        },
        "CLOSED_PAYMENT_TRACE": {
            "name": "Betalingstracering",
            "closed": 1
        },
        "CLOSED_CREDIT": {
            "name": "Creditering",
            "closed": 1
        },
        "CLOSED_PARTIAL": {
            "name": "Deelvordering geincasseerd restant niet incasseerbaar",
            "closed": 1
        },
        "CLOSED_NO_FEE": {
            "name": "Factuurbedrag voldaan, kosten niet incasseerbaar",
            "closed": 1
        },
        "CLOSED_FEE": {
            "name": "Factuurbedrag inclusief R&I voldaan",
            "closed": 1
        }
    }
}


// List dossier states
if ($api->get('/dossier/status')) {
    print_r($api->response);
} else {
    print_r($api->error);
}
            

List dossiers

This method will give you a paged overview of your dossiers.

The response will look like this:

{
    'dossiers' => [
        { dossier object },
        { dossier object }
    ],
    'pager' => [
        'next'  => '/dossier?page=1', // null if there is no next page available
        'pages' => 2 // (int) the total amount of pages
    ]
}

You can use the value in `next` to fetch the next page of dossiers.



// List dossiers
if($api->get('/dossier')) {
    print_r($api->response);
} else {
    print_r($api->error);
}
            

Create dossier

To create a dossier you need to have the following information:

  • Debtor ID
  • Test: Is the dossier a test dossier or not?
    • true: The dossier will be handled by the system
    • false: The dossier will NOT be handled, only displayed
  • Status: you can create a dossier with 2 statuses
    • PRE_DEMAND: If you did not yet send a sommation letter
    • FIRST_DEMAND: If you already send a sommation letter
  • Invoice information:
    • number: your internal reference
    • amount: the invoice amount (in cents)
    • payment: the payed amount (in cents)
    • date_invoice:
    • date_expiry:

Possible errors:

  • Invalid dossier information
    The messages field contains specific error information
  • Invalid status
    The status can only be 'PRE_DEMAND' or 'FIRST_DEMAND'
  • Invalid debtor
    You can only use a debtor that is created by the used creditor
  • Invalid invoice information
    The messages field contains specific error information


// Define the debtor id (this needs to exist in our database)
$debtor = 1;

// Define the dossier
$dossier = [
    'status'    => 'PRE_DEMAND', // PRE_DEMAND OR FIRST_DEMAND
    'debtor'   => $debtor, // The id of your debtor
    'test'      => true, // Is the dossier a test dossier, or not?
    'invoices' => [
        [
            'number' => 1500,   // your invoice number (can be text)
            'amount' => 15000,  // the amount, in cents
            'payment' => 0,     // the payed amount, in cents
            'date_invoice' => '2014-12-12', // invoice date, YYYY-MM-DD
            'date_expiry' => '2014-12-24', // expiry date, YYYY-MM-DD
        ],
        [
            'number' => 2500,
            'amount' => 25050,
            'payment' => 1050,
            'date_invoice' => '2014-12-12',
            'date_expiry' => '2014-12-24',
        ],
    ]
];

// Create the dossier
if ($api->post('/dossier', $dossier)) {
    print_r($api->response);
} else {
    print_r($api->error);
    print_r($api->response->messages);
}
            

Get dossier

This method will give you the details of a specific dossier.

The response will look like this:

{
  "dossier": {
    "id": ,
    "test": false,
    "code": 2014010001,
    "debtor_id": 1,
    "invoices": [
      {
        "number": "2014-0001",
        "amount": 13.37,
        "payment": 0,
        "interest": 0,
        "date_invoice": "2014-01-01",
        "date_expiry": "2014-01-24"
      }
    ],
    "status": "CLOSED_FEE",
    "date": 20140130
  }
}


// List dossiers
if($api->get('/dossier/1')) {
    print_r($api->response);
} else {
    print_r($api->error);
}