Overview

Single-Invoice.co, powered by Euler Hermes, provides a simple API you can use to insure the payment of invoices and transactions. In addition to providing credit insurance, Single-Invoice.co gives you access to an extensive database of information about companies mainly in Europe, North America and Asia-Pacific.

At a Glance

The flow to cover an invoice through the API is quite simple:

First, search for the two companies involved in the invoice - the buyer and supplier.
Once you've found the companies, you can request a quote for a cover to insure the invoice.
If you're happy with the quote, you can accept it by activating the cover, protecting the transaction.
Finally, if you've been paid, you can settle the cover - and if not, you can file a claim.

That's it! For more detail, please read on.

Registering an Account.

Step 1:
To register an account you need to go on our demo environment . Once you entered the details about your company, you'll receive a confirmation mail. This means you have registered an account to our demo environnement. The account is fully functional and active.

Step 2:
You can now test the API's and integrate them in your systems. Once this is done and the policy has been signed. We will migrate your account to production.

📘
Demo environment
We recommend testing first in our Demo environment. You can create accounts in the Demo on our Demo Developer Portal.
Note that the API endpoint for the Sandbox is: https://api-demo.single-invoice.co
More information about the Sandbox environment is available here.

Creating an API key

Single-Invoice.co uses API keys for authentication. Once you sign up, you'll automatically have an Account Management API key available, which allows you to manipulate your account via the various API calls (see the 'Accounts' section for the full list of these calls).

📘
A quick note about authentication
All authenticated requests to Single-Invoice.co require an API key and must be submitted over HTTPS.

After your account is created, default packages are automatically associated to it. Those packages include API keys needed to authenticate when performing different API calls.

API keys can be created programmatically or requested through the Developer Portal - see the Create API Key manual page for details on this process.

Insuring an Invoice

Single-Invoice.co provides an API that lets you insure invoices between two parties, referred to in our API as "companies" or transactors.

Before you can insure an invoice, you need the IDs of the companies.

Getting information about a company

Let’s get information about Acme Industries, an imaginary company in France that will be the buyer in your invoice.

The first step is to search the Single-Invoice.co database to find its record - it's Single-Invoice.co ID.

📘
Single-Invoice.co IDs
Each company has an Single-Invoice.co ID that does not change. The Single-Invoice.co ID is required for all coverage methods.
Please note, however, that Single-Invoice.co IDs will be different between different environments (for example, our Demo environment and our Production environment will have different IDs for the same company).

Once you've found the company, you can use its ID to create a coverage policy.

Querying Single-Invoice.co

To find Acme Industries, we’ll search by SIREN code.

For your seller, Ajax Inc, assume we already have its ID (but if we don't, we just search for it in the same way that we found the buyer). For more information about finding companies, please see the various Companies methods that are available.

Note that before you can send the request, you need to add your Coverage API key to the header.

//using http://unirest.io/java.html
import com.mashape.Unirest;

HttpRequest jsonRequest = Unirest.get("https://api.single-invoice.co/v2.0/transactors/{countrycode}/{service}/{id}")
  .routeParam("countrycode", "fr")
  .routeParam("service", "siren")
  .routeParam("id", "953539907")
  .header("accept", "application/json");

'use strict';

//using http://unirest.io/nodejs.html
let unirest = require('unirest');

let countrycode = 'fr';
let service = 'siren';
let id = '953539907';
let request = unirest.get(`https://api.single-invoice.co/v2.0/transactors/${countrycode}/${service}/${id}`);

<?php
// Example assumes Composer is in use with GuzzleHttp as the API library.
require_once("vendor/autoload.php");
use GuzzleHttp\Client;

$api_base_uri = 'https://api.single-invoice.co/v2.0';

// Create a client and provide a base URL
$client = new Client([ 
	'timeout' 	=> 8.0,
	'verify'	=> true,
	'debug'		=> false
]);

try
{
	$response = $client->request('GET', $api_base_uri."/transactor/FR/SIREN/455171751", [
		'headers' => [ 'apikey' => 'm4C1ckYebAU1Z2XNDgPCLdrKd7A7HXi0Gw4XdG2JCBuF6Vua0jduHFJ027Iycn1s' ],
	]);

	// Check the status code returned by the call
	$statusCode = $response->getStatusCode();

	// Get the data
	$data = json_decode($response->getBody(), true);

}
catch (GuzzleHttp\Exception\ClientException $e) {
    $response = $e->getResponse();
    $responseBodyAsString = $response->getBody()->getContents();
}

// Example assumes the packages request and request-promise have been installed (npm install request request-promise)
var rp = require('request-promise');

var apiBaseUri = 'https://api.single-invoice.co/v2.0';
var apikey = 'QSGLZoNInZ6mPTcO78EDNmQjgAO65B0uLwYO61DQpHpdyfOm6LsLL4zr95J97iIp';

rp({
  method: 'GET',
  uri: apiBaseUri + '/transactor/FR/SIRET/43564652534',
  qs: {
    apikey: apikey
  },
  json: true
})
  .then(function (res) {
    // request succeeded, the result is available in the res object
    console.log(res);
  })
  .catch(function (err) {
    // request failed, the error is available in the err object
    console.log(err);
  });

Understanding Company Search Results

The resulting JSON data contains information about the imaginary company, Acme Industries:

{
  "id": "6d568a15-f99c-4b4b-9143-fbda98b0b32e",
  "name": "Acme Industries",
  "address": {
    "type": "main",
    "city": "Paris",
    "countrycode": "FR",
    "postalcode": "1000",
    "statecode": null,
    "streetname" : "Rue de Fake", 
    "streetnumber": "12"
	},
	"phonenumber": "+33 5 55 55 55 55",
	"legalFormCode": "BVBA"
}

Covering an Invoice

Now that you have the ID of the buyer, Acme, and the seller, Ajax, you can request a coverage policy for the transaction.

To request a policy, you make a POST request to the Request Quote endpoint with the following information:

the Single-Invoice.co IDs of the buyer and supplier
the total amount due
the currency
the date the invoice was issued
the date when the invoice is due
an invoice number (optional)

<?php
// Example assumes Composer is in use with GuzzleHttp as the API library.
require_once("vendor/autoload.php");
use GuzzleHttp\Client;

$api_base_uri = 'https://api.single-invoice.co/v2.0';

// Create a client and provide a base URL
$client = new Client([ 
	'timeout' 	=> 8.0, 
	'verify'	=> true,
	'debug'		=> true
]);

try
{
	$apikey = "ZTIlHrC0eoRDpAGLgqsF6bJzxBAiapgQiQFUlWuuqK3FtVd3TepzE9w7UdrZhjSA";
	
	$response = $client->request('POST', $api_base_uri."/coverage", [
		'headers' => [ 'apikey' => $apikey ],
		'json' => 	[
						'sellerid' => 'c3773f78-b180-fd47-17b3-600a150d617a', 
						'buyerid' => 'f5f82c66-de95-c933-43f1-bd0a2327ce09', 
						'invoice' => [ 
										"amount" =>  100000.0,
										"currency" =>  "eur",
										"dueAt"  =>  "2016-10-10",
										"issuedAt"  =>  "2016-08-10",
              			"number" => "1414715" // optional
									]
					]
	]);

	// Check the status code returned by the call
	$statusCode = $response->getStatusCode();

	// Get the data
	$data = json_decode($response->getBody(), true);
}
catch (GuzzleHttp\Exception\ClientException $e) {
  $response = $e->getResponse();
	$responseBodyAsString = $response->getBody()->getContents();
}

// Example assumes the packages request and request-promise have been installed (npm install request request-promise)
var rp = require('request-promise');

var apiBaseUri = 'https://api.single-invoice.co/v2.0';
var apikey = 'najiEw6gSDCivkuPwjXsMsQWPaX8xX4pGB6NRCbqXLPBCd9PFVfm65wwO4vo6JtX';

rp({
  method: 'POST',
  uri: apiBaseUri + '/coverage',
  qs: {
    apikey: apikey,
  },
  body: {
    sellerid : "a6a51b39-761d-f449-64b8-27fd9fff0796",
    buyerid : "bbccd3f1-3efb-a53d-741e-b308133f91ca",
    invoice : {
      amount: 100000.0,
      currency: "eur",
      dueAt : "2016-10-10",
      issuedAt : "2016-08-10"
    }
  },
  json: true
})
  .then(function (res) {
    // request succeeded, the result is available in the res object
    console.log(res);
  })
  .catch(function (err) {
    // request failed, the error is available in the err object
    console.log(err);
  });

The resulting JSON data contains the terms of the policy, including:

Policy ID: a GUID-style identifer that serves as a unique ID for this quote.
Status: whether or not the policy has been accepted or rejected
Coverage details: the amount and currency of the coverage.
General details about the quote, including invoice details and the identifiers for the two transactors.

See the Request Quote documentation for more detail about the return options.

{
    "id": "41175eed-3d2b-a552-cc85-128b7ea371ed",
    "status": "Pending",
    "coverage": {
        "amount": 6.15,
        "currency": "eur",
    },
    "sellerId": "bd1172e2-141c-4be4-8700-6b785556a9b7",
    "buyerId": "bd1172e2-141c-4be4-8700-6b785556a9b7",
    "invoice": {
        "Amount": 1000,
        "Currency": "gbp",
        "DueAt": "2016-10-30T00:00:00Z",
        "IssuedAt": "2016-08-31T00:00:00Z",
        "Number": "1414715"
    }
}

After requesting a policy, you can Activate or Reject it.

🚧
Cover Activation
To actually insure your invoice, you must Activate the cover.
If a cover is not Activated, the insurance will not be in place. Quotes for covers will automatically expire after a set time period (currently dependent on your policy).

Dealing with Covers

Based on the terms, you accept the cover, by calling the Activate endpoint. Once the cover has been accepted, the invoice is insured under the terms of the policy we have with you.

Acme, being a reputable company, paid their invoice on time. Once the invoice is paid, you notify Single-Invoice.co that the coverage policy has been settled successfully with the Settle endpoint.

If you're dealing with a company that fails to pay on time, however, you may want to file a claim using the Claim endpoint. At this point the claims process will start and we will be submitting the required documentation to our claims & collections team.

Next steps

Single-Invoice.co provides APIs to manage the entire life cycle of a coverage policy. For more information about policy life cycle, see the COVERAGES LIFE CYCLE endpoints:

Overview

At a Glance

Registering an Account.

📘
Demo environment

Creating an API key

📘
A quick note about authentication

Insuring an Invoice

Getting information about a company

📘
Single-Invoice.co IDs

Querying Single-Invoice.co

Understanding Company Search Results

Covering an Invoice

🚧
Cover Activation

Dealing with Covers

Next steps

At a Glance

Registering an Account.

📘Demo environment

Creating an API key

📘A quick note about authentication

Insuring an Invoice

Getting information about a company

📘Single-Invoice.co IDs

Querying Single-Invoice.co

Understanding Company Search Results

Covering an Invoice

🚧Cover Activation

Dealing with Covers

Next steps

📘
Demo environment

📘
A quick note about authentication

📘
Single-Invoice.co IDs

🚧
Cover Activation