Single-Invoice.co

Single-Invoice.co Developer Hub

Comprehensive guides and documentation to help you get started with the Single-Invoice.co API as quickly as possible. If you get stuck, please ask for help in support!

Get Started

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 in France, as well as the rest of Europe, and soon, the United States.

At a Glance

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

  1. First, search for the two companies involved in the invoice - the buyer and supplier.
  2. Once you've found the companies, you can request a quote for a cover to insure the invoice.
  3. If you're happy with the quote, you can accept it by activating the cover, protecting the transaction.
  4. 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.

Before you can begin, you will need to register an API account. Accounts are currently created in a disabled state; after you've created your account, it will be need to be reviewed before you'll be able to login and create a Coverage API key to issue other calls.

Accounts can be created through our Developer Portal.

Sandbox environment

We recommend testing first in our Sandbox environment. You can create accounts in the Sandbox on our Sandbox 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 approved, you'll be able to create a Coverage API key, which allows access to the various Coverage methods.

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. Once a coverage policy has been issued, you can also use the API to manage the policy.

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 testing 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.armadill.io/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.armadill.io/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.armadill.io/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 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.armadill.io/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; upon submitting the required documentation to our claims team we'll pay out the value of the cover.

By notifying Single-Invoice.co, future coverage pricing will be adjusted based on the timeliness of payments by transactors, resulting in a constantly-improving model ensuring we can offer the best prices for insurance.

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


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.