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
Suggest Edits

Register

Registers a new account allowing you to use the Single-Invoice.co API.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api-demo.single-invoice.co/v2/account/register

Body Params

email
string
required

The email address for the new acccount.

password
string
required

Password for the new account.

firstname
string

The name for the account holder.

lastname
string

Surname for the account holer.

company
string

The name of the company registering the account.

industry
string

The industry that the company is in (factoring, B2B marketplaces, etc).

phone
string

Contact phone number.

address
string

Physical address for correspondence.

This method allows users to create new API accounts on Single-Invoice.co, providing access to the other methods with in the API, including getting quotes, searching for companies, and manipulating coverages.

When an account is registered, an email containing a verification link will be sent to the email address provided as a first step.

Once the email address has been verified, our internal account team will review the provided information and then approve the account.

After the account has been approved, you will be provided with access to the API key management, which will allow you to create an API key to access the full range of functionality provided by the API.

<?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' 	=> 4.0,
	'verify'	=> true,
	'debug'		=> true
]);

try
{
  // POST the account creation request with the required parameters
  $response = $client->request('POST', $api_base_uri."/Account/Register", [
    'json' 	=> 	[ 
            'email' => 'test@example.com',
            'password' => 'examplePassword123!'
          ] 
  ]);

  // 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';

rp({
  method: 'POST',
  uri: apiBaseUri + '/Account/Register',
  body: {
    Email: 'test@example.com',
    Password: '123456789',
    FirstName: 'Bob',
    LastName: 'Smith',
    Company: 'Bob Corporation',
    Industry: 'factoring',
    Phone: '+44-7500-000-000',
    Address: 'Grand Boulevard, 7th, Great-town',
    SIREN: '123456789'
  },
  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);
  })
;
A binary file was returned

You couldn't be authenticated

{ 'Message' : 'A verification email has been sent to: test@example.com' }
{ 'Message' : 'This email exists already.' }
{ 'Message' : 'Bad authentication information error.' }
 
Suggest Edits

Update Account

Update the details of an Single-Invoice.co account.

 
put/account

Body Params

email
string
required

The email address for the acccount.

password
string
required

Password for the account.

firstname
string

The name for the account holder.

lastname
string

The surname for the account holder.

company
string

The name of the company registering the account.

phone
string

Contact phone number.

address
string

Physical address for correspondence.

Headers

apikey
string
required

Your Account Management API Key, in the HTTP request headers.

This method allows users to update their Single-Invoice.co user account record. Only the fields that you want to update need to be submitted.

If the update is successful, the full record will be returned as a JSON response, including the updates.

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

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

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

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

try
{
  // PUT the account creation request with the required parameters
  $response = $client->request('PUT', $api_base_uri."/Account", [
    'header' => [ 'apikey' => '4hVoCZbHptjhz1NaWvekZeXltKPOL2EzZf6DxuAd1BTiHAbx1DYCogPaZGj0CS5a
  ' ],
    'json' 	=> 	[ 
            'email' => 'test@example.com',
            'password' => 'examplePassword123!',
            'Phone' => '+44-7500-000-000'
          ] 
  ]);

  // 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 = 'l5497gqJ5FaKGxIm0uQOYkVYn2HiAxr7strDNxpz8GIT8G7tgnN5n4JKsqFBmmXx';

rp({
  method: 'PUT',
  uri: apiBaseUri + '/Account',
  headers: {
    apikey: apikey
  },
  body: {
    FirstName: 'Bob',
    LastName: 'Smith',
    Phone: '+44-7500-000-000',
    Company: 'Bob Corporation',
    Address: 'Grand Boulevard, 7th, Great-town',
    SIREN: '123456789'
  },
  json: true
})
  .then(function (res) {
    // request succeeded, the result is available in the res object
  })
  .catch(function (err) {
    // request failed, the error is available in the err object
  })
;

A binary file was returned

You couldn't be authenticated

{
    "Id": 4817517,
    "Email": "test@example.com",
    "Packages": {
        "Account": [
            "8v32JuRR06wVV9YPc7gssWMGCRdmq1DElQLNDVZwWBijURhzAAFURbDIFb3aq16K",
          ]
    }
    "FirstName": 'Updated Test',
    "LastName": 'Updated Example',
    "Company": 'Updated Example.com',
    "Phone": '+44-7500-000-000',
    "Address": '123 Test Street, London, UK',
    "SIREN": null,
    "Roles": "User",
    "Active": true
}
{ 'Message' : 'This email exists already.' }
{ 'Message' : 'Bad authentication information error.' }
 
Suggest Edits

Login

Login to the Single-Invoice.co API.

 
post/account/login

Body Params

email
string
required

Account email address

password
string
required

Account password.

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

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

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

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

try 
{
	$response = $client->request('POST', $api_base_uri."/Account/Login", [
		'json' 	=> 	[ 
						'email' => 'test@example.com',
						'password' => 'dsj19jfdnnm134419ahf'
					] 
		]);

	// 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();
}
using System;
using System.Collections.Generic;
using System.Text;
using System.Threading.Tasks;
using System.Net.Http;
using System.Net.Http.Headers;

namespace Armadillio_Test
{
    class Login
    {
        public string email { get; set; }
        public string password { get; set; }
    }

    class UserDetails
    {
        public string Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public string Company { get; set; }
        public string Phone { get; set; }
        public string Address { get; set; }
        public string SIREN { get; set; }
        public string Roles { get; set; }
        public string Active { get; set; }
    }

    class Program
    {
        static void Main()
        {
            RunAsync().Wait();
        }

        static async Task RunAsync()
        {
            using (var client = new HttpClient())
            {
                client.BaseAddress = new Uri("https://api-demo.single-invoice.co/v2.0/");
                client.DefaultRequestHeaders.Accept.Clear();
                client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

                // make the POST request with the suppled variables serialised into JSON
                var loginrun = new Login() { email = "test@example.com", password = "r3lK0nFHYelG" };
                HttpResponseMessage response = await client.PostAsJsonAsync("Account/Login", loginrun);

                if (response.IsSuccessStatusCode)
                {
                    // Deserialise the JSON response
                    UserDetails user = await response.Content.ReadAsAsync<UserDetails>();

                    // Display the account details
                    Console.WriteLine(user.Id);
                    Console.WriteLine(user.FirstName + " " + user.LastName) ;
                    Console.WriteLine(user.Company);
                    Console.WriteLine(user.Phone);
                    Console.WriteLine(user.Address);
                    Console.WriteLine(user.SIREN);
                    Console.WriteLine(user.Roles);
                    Console.WriteLine(user.Active);
                }
                else
                {
                    // Handle the error code.
                    Console.WriteLine((int)response.StatusCode);
                    Console.WriteLine(response.StatusCode);
                }
            }
        }
    }
}
// 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';

rp({
  method: 'POST',
  uri: apiBaseUri + '/account/login',
  json: {
    email: 'test@example.com',
    password: 'exampleSecurePassword123!@#'
  }
})
  .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);
  })
;
A binary file was returned

You couldn't be authenticated

{
    "Id": 4817517,
    "Email": "test@example.com",
    "Packages": {
        "Account": [
		"8v32JuRR06wVV9YPc7gssWMGCRdmq1DElQLNDVZwWBijURhzAAFURbDIFb3aq16K",
          ]
    }
    "firstname": 'Updated Test',
    "lastname": 'Updated Example',
    "company": 'Updated Example.com',
    "phone": '+44-7500-000-000',
    "address": '123 Test Street, London, UK',
  	"industry" : null,
    "roles": "User",
    "active": true
}
{
  "options.Password" : 
  { 
    "_errors" : [
    	{ 
      	"<Exception>k__BackingField" : null,
      	"<ErrorMessage>k__BackingField" : "The Password field is required."
      }
    ],
    	"<Value>k__BackingField":null
  }
}
{ 
	"Code" : 401,
	"Message" : "Username or password incorrect."
}
 
Suggest Edits

Create API Key

Request a new API key.

 
post/account/key

Body Params

package
string
required

The type of key to request. Valid options are 'Account' or 'Coverage'.

Headers

apikey
string
required

Your API key for account management.

This method allows you to request a new API key with which you can access the API.

This method is called with your default API key (the 'Account Management API key') as a query parameter; it will return your full Account object with the new key listed.

There are two types of API keys:

  • "Account" keys, referred to here as Account Management API keys, which are used for calling account-related functions.
  • "Coverage" keys, for calling coverage methods like searching, requesting a quote or activating coverage.
{
  "package" : "Coverage"
}
<?php
require_once("vendor/autoload.php");
use GuzzleHttp\Client;

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

try 
{
	// POST the account creation request with the required parameters
	$response = $client->request('POST', $api_base_uri."/account/key", [
		'headers' => [ 'apikey' => $apikey_account ],
		'json' 	=> 	[ 
						'package' => "Coverage",
					],
	]);

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

	// Get the data
	$data = json_decode($response->getBody(), true);
	print json_encode($data, JSON_PRETTY_PRINT);
}
catch (GuzzleHttp\Exception\ClientException $e) {
    $response = $e->getResponse();
    $responseBodyAsString = $response->getBody()->getContents();
    print $responseBodyAsString;
}
A binary file was returned

You couldn't be authenticated

{
    "Id": 4817517,
    "Email": "test@example.com",
    "ApiKeys": [
        "PsDW6SRVd4TXRdm69sPXEcdYDMRV1ZXX6z8X7ZU9iBb7Wf2qlUlPJP9U0Wend",
      	"MmozazEzajJrMmozMmtqZGRkIiwibmFtZSI6IkpvaG4gRG9lIiwiY1fac1X4"
    ],
    "FirstName": 'Test',
    "LastName": 'Example',
    "Company": 'Example.com',
    "Phone": '+44-7500-000-000',
    "Address": '123 Test Street, London, UK',
    "SIREN": null,
    "Roles": "User",
    "Active": true
}
{
	'Message' : 'Authorization has been denied for this request.'
}
 
Suggest Edits

Reset Password

Start the password resetting process in the event of a lost or forgotten password.

 
post/account/reset

Query Params

email
string
required

In the event that you've lost or forgotten your password, calling the Reset Password endpoint will send an email to the submitted address containing instructions on how to reset it.

The email will include a link that, when followed, will allow the user to enter a new password, overriding the old one.

It is important to note that the security of API account ultimately rests with that of the email account - anyone with access to the email account will potentially have access to all your account functionality.

curl --request POST \
  --url 'http://example.com/account/reset?email=email'
var request = require("request");

var options = { method: 'POST',
  url: 'http://example.com/account/reset',
  qs: { email: 'email' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://example.com/account/reset?email=email")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "http://example.com/account/reset?email=email");

xhr.send(data);
import requests

url = "http://example.com/account/reset"

querystring = {"email":"email"}

response = requests.request("POST", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{ 
  'Message' : 'An email has been sent to test@example.com with instructions on how to reset your password.' 
}
{ 'Message' : 'Invalid email address' }
 
Suggest Edits

Delete API Key

Deletes an API key from your account.

 
delete/account/key/id

Path Params

id
string
required

The API key to delete.

Headers

apikey
string
required

Your Application API Key, in the HTTP request headers.

This method allows you to remove an assigned API key from your account.

Note that any code running that is using a deleted API key will fail as it will no longer be authorised for use.

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

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

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

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

try 
{
	$response = $client->request('DELETE', $api_base_uri."/Account/Key/Mi1PnUbJbtpo4ThKv67AhNihkvNK39FtchJrsCOyYk7CWQYnhirvSIdv6M2Vhor3", [
		'headers' => [ 'apikey' => 'wFrRGRmdNz2Gax4GidpDLXmwwLVnyI5mWEBD7V50b30vnY7DkOhDoLVEq4eMtHla' ],
	]);

	// 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();
}
A binary file was returned

You couldn't be authenticated

{
    "Id": 471,
    "Email": "test@example.com",
    "Packages": {
        "Account": [
            "MmozazEzajJrMmozMmtqZGRkIiwibmFtZSI6IkpvaG4gRG9lIiwiY1fac1X4"
        ]
    },
    "FirstName": "Test",
    "LastName": "Example",
    "Company": "Example.com",
    "Phone": "+44-7500-000-000",
    "Address": "123 Test St, London",
    "SIREN": null,
    "Roles": "User",
    "Active": true
}
 
Suggest Edits

Search Company By SIC ID

Returns information about a company by Single-Invoice.co ID. This company ID does not change.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api-demo.single-invoice.co/v2/transactor/id

Path Params

id
string
required

The Single-Invoice.co ID for a given transactor

This method will search the Single-Invoice.co database for a company with the provided Single-Invoice.co (SIC) ID.

If the search is successful, the endpoint will return JSON containing general identifying information about the transactor (including company name, address and phone number).

curl -X GET \
  https://api-demo.single-invoice.co/v2//transactor/9432824c-afc3-4f52-a04c-e4662f6e4766 \
  -H 'Postman-Token: df49b09e-0e96-4ab0-b03b-ba025247e0e8' \
  -H 'apikey: YOURAPIKEY' \
  -H 'cache-control: no-cache'
import requests

url = "https://api-demo.single-invoice.co/v2//transactor/9432824c-afc3-4f52-a04c-e4662f6e4766"

payload = ""
headers = {
    'apikey': "YOURAPIKEY",
    'cache-control': "no-cache",
    'Postman-Token': "a9a327bf-81f1-4b4d-8c57-870a1e88aff2"
    }

response = requests.request("GET", url, data=payload, headers=headers)

print(response.text)
GET /v2/transactor/9432824c-afc3-4f52-a04c-e4662f6e4766 HTTP/1.1
Host: api-demo.single-invoice.co
apikey: YOURAPIKEY
cache-control: no-cache
Postman-Token: effc609d-39e1-4145-91ec-67da7a48f35f
A binary file was returned

You couldn't be authenticated

{
    "Id": "9432824c-afc3-4f52-a04c-e4662f6e4766",
    "Name": "35° EAST",
    "Address": {
        "StreetNumber": "1",
        "StreetName": "PL DES SAISONS",
        "PostCode": "92048",
        "City": "COURBEVOIE",
        "StateCode": "92",
        "CountryCode": "FR",
        "Type": "main"
    },
    "PhoneNumber": null,
    "LegalFormCode": "SAS",
    "ExternalIds": [
        {
            "ExternalId": "85889366",
            "ExternalService": "eulerid"
        },
        {
            "ExternalId": "493467609",
            "ExternalService": "SIREN"
        },
        {
            "ExternalId": "FAKE85889366",
            "ExternalService": "FAKE"
        }
    ]
}
{
	"message" : "Missing parameters",
  "docUrl": "https://armadill.io/docs/errors#section-missing_param"
}
{
	"message" : "Bad authentication information",
  "docUrl": "http://docs.armadill.io/docs/errors#section-bad-authentication-information"
}
{
	"message" : "Resource not found",
  "docUrl": "https://armadill.io/docs/errors#section-resource_not_found"
}
{
	"message" : "Expired date stamp",
  "docUrl": "https://armadill.io/docs/authentication"
}
 
Suggest Edits

Search Company By External ID

Returns information about a company specified by an external service type and an external service ID

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api-demo.single-invoice.co/v2/transactor/countrycode/service/id

Path Params

countrycode
string
required

Country code for the service.

service
string
required

The external service identifer code (for example, SIREN or SIRET)

id
string
required

The ID of the transactor in an external system

This method allows you to search the Single-Invoice.co company database to find a transactor through a variety of "external IDs". This will allow you to discover their Single-Invoice.co ID, which will in turn allow you to obtain quotes for coverage.

An external ID is typically the unique ID in some sort of company registry - for example, French companies each have a unique SIREN code.

Searching via Euler Hermes ID

For users that are famililar with searching via the Euler Hermes ID, these are accessible with the service listing type 'eulerid' (e.g., http://api.single-invoice.co/v2.0/transactor/:countrycode/eulerid/:id).

A list of the supported registry services is made available through the Services Listing endpoint.

The endpoint takes three inputs:

  • Country code: the country in which the company resides
  • Service: the service identifier (as noted in the Services Listing)
  • Id: the identifier for the external service

If the search is successful, the endpoint will return JSON containing general identifying information about the transactor (including company name, address and phone number).

curl -X GET \
  https://api-demo.single-invoice.co/v2/transactor/fr/SIREN/493467609 \
  -H 'Postman-Token: fcddc97a-06db-41f7-8068-578922f0f70d' \
  -H 'apikey: YOURAPIKEY' \
  -H 'cache-control: no-cache'
import requests

url = "https://api-demo.single-invoice.co/v2/transactor/fr/SIREN/493467609"

payload = ""
headers = {
    'apikey': "YOURAPIKEY",
    'cache-control': "no-cache",
    'Postman-Token': "c4dd3cf4-2182-405b-bcca-c21472f936af"
    }

response = requests.request("GET", url, data=payload, headers=headers)

print(response.text)
GET /v2/transactor/fr/SIREN/493467609 HTTP/1.1
Host: api-demo.single-invoice.co
apikey: YOURAPIKEY
cache-control: no-cache
Postman-Token: 56d12f35-54df-4e93-822d-a9a8ac435490
A binary file was returned

You couldn't be authenticated

{
    "Id": "9432824c-afc3-4f52-a04c-e4662f6e4766",
    "Name": "35° EAST",
    "Address": {
        "StreetNumber": "1",
        "StreetName": "PL DES SAISONS",
        "PostCode": "92048",
        "City": "COURBEVOIE",
        "StateCode": "92",
        "CountryCode": "FR",
        "Type": "main"
    },
    "PhoneNumber": null,
    "LegalFormCode": "SAS",
    "ExternalIds": [
        {
            "ExternalId": "85889366",
            "ExternalService": "eulerid"
        },
        {
            "ExternalId": "493467609",
            "ExternalService": "SIREN"
        },
        {
            "ExternalId": "FAKE85889366",
            "ExternalService": "FAKE"
        }
    ]
}
{
	"message" : "Missing parameters",
  "docUrl": "https://armadill.io/docs/errors#section-missing_param"
}
{
	"message" : "Bad authentication information",
  "docUrl": "http://docs.armadill.io/docs/errors#section-bad-authentication-information"
}
{
	"message" : "Resource not found",
  "docUrl": "https://armadill.io/docs/errors#section-resource_not_found"
}
{
	"message" : "Expired date stamp",
  "docUrl": "https://armadill.io/docs/authentication"
}
 
Suggest Edits

List Country Codes

Provides a list of all the support countries along with their ISO ISO 3166-1 alpha-2 country code.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api-demo.single-invoice.co/v2/lookups/countries

This will return a JSON-formatted list of all the countries along with their two letter county code as defined by ISO 3166-1 alpha-2 - for example, France is "FR" and the United Kingdom is "GB".

These codes are typically used when searching for transactors. This method can (for example) be used to populate a dropdown of countries in a search form. (The contents are not expected to change so it should be safe to locally cache these values for long periods of time.)

curl -X GET \
  https://api-demo.single-invoice.co/v2/lookups/countries \
  -H 'apikey: YOURAPIKEY' \
  -H 'cache-control: no-cache'
import requests

url = "https://api-demo.single-invoice.co/v2/lookups/countries"

payload = ""
headers = {
    'apikey': "YOURAPIKEY",
    'cache-control': "no-cache",
    }

response = requests.request("GET", url, data=payload, headers=headers)

print(response.text)
GET /v2/lookups/countries? HTTP/1.1
Host: api-demo.single-invoice.co
apikey: YOURAPIKEY
cache-control: no-cache

A binary file was returned

You couldn't be authenticated

[
    {
        "CountryCode": "AD",
        "CountryLabel": "Andorra"
    },
  	...
    {
        "CountryCode": "ZW",
        "CountryLabel": "Zimbabwe"
    }
]
{"Message":"Authorization has been denied for this request."}
 
Suggest Edits

List company external IDs available for the search

Provides a list of codes for supported company external ID lookup services (e.g., SIREN, SIRET, DUNS number).

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api-demo.single-invoice.co/v2/lookups/services

This method will provide a complete listing of the code identifiers for the various systems that provide a unique identifier for companies. For example, France has the SIREN and SIRET numbers.

These codes are typically used when searching for transactors. This method can (for example) be used to populate a dropdown of identifiers in a search form.

Searching via Euler Hermes ID

For users that are famililar with searching via the Euler Hermes ID, these are accessible with the service listing type 'eulerid' (e.g., http://api.single-invoice.co/v2.0/transactor/:countrycode/eulerid/:id).

curl -X GET \
  https://api-demo.single-invoice.co/v2/lookups/services \
  -H 'apikey: YOURAPIKEY' \
  -H 'cache-control: no-cache'
import requests

url = "https://api-demo.single-invoice.co/v2/lookups/services"

payload = ""
headers = {
    'apikey': "YOURAPIKEY",
    'cache-control': "no-cache"
    }

response = requests.request("GET", url, data=payload, headers=headers)

print(response.text)
GET /v2/lookups/services? HTTP/1.1
Host: api-demo.single-invoice.co
apikey: YOURAPIKEY
cache-control: no-cache
A binary file was returned

You couldn't be authenticated

[
    {
        "IdentifierCode": "CRO",
        "IdentifierCountry": "GB",
        "IdentifierLabel": "CRO number"
    },
  				//[ extra rows removed intentionally]
    {
        "IdentifierCode": "SIREN",
        "IdentifierCountry": "FR",
        "IdentifierLabel": "SIREN number"
    },

]
{"Message":"Authorization has been denied for this request."}
 
Suggest Edits

Get Company External IDs

Returns information about a company specified by an external service type and an external service ID

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api-demo.single-invoice.co/v2/transactor/id/externalids

Path Params

id
string
required

The Single-Invoice.co ID for a given transactor

This method allows you to retrieve the External IDs that are linked to a specific Single-Invoice.co company.

It will return an array of items including the ID, service code, and country code for each linked External ID.

An External ID is typically the unique ID in some sort of company registry - for example, French companies each have a unique SIREN code.

Note that a list of the supported service codes is available with the Services Listing endpoint.

curl -X GET \
  https://api-demo.single-invoice.co/v2/transactor/9432824c-afc3-4f52-a04c-e4662f6e4766/externalids \
  -H 'apikey: YOURAPIKEY' \
  -H 'cache-control: no-cache'
import requests

url = "https://api-demo.single-invoice.co/v2/transactor/9432824c-afc3-4f52-a04c-e4662f6e4766/externalids"

payload = ""
headers = {
    'apikey': "YOURAPIKEY",
    'cache-control': "no-cache"
    }

response = requests.request("GET", url, data=payload, headers=headers)

print(response.text)
GET /v2/transactor/9432824c-afc3-4f52-a04c-e4662f6e4766/externalids HTTP/1.1
Host: api-demo.single-invoice.co
apikey: YOURAPIKEY
cache-control: no-cache
A binary file was returned

You couldn't be authenticated

[
    {
        "Id": "85889366",
        "Service": "eulerid",
        "CountryCode": "FR"
    },
    {
        "Id": "493467609",
        "Service": "SIREN",
        "CountryCode": "FR"
    },
    {
        "Id": "FAKE85889366",
        "Service": "FAKE",
        "CountryCode": "FR"
    }
]
{
  "Code":5001,
  "Message":"Company not found.",
  "Description":null,"DocUrl":"TBD"
}
{
	"message" : "Expired date stamp",
  "docUrl": "https://armadill.io/docs/authentication"
}
{
	"code":400,
  "message":"The value 'zzz' is not valid for Guid.",
  "docUrl":"https://singleinvoice.co/docs/errors#section-missing_param"
}
 
Suggest Edits

Request SIC Company Creation by External Id

Request the creation of a company in case the company search didn't return the SICID of a company but returned one of its external IDs.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api-demo.single-invoice.co/v2/company

Body Params

body
object
required

JSON containing the external Id of the company (Service and Id) and county code

 

In order to be able to request a cover on an invoice, both SICIDs sellerId and buyerId need to be provided in the request.

When performing a company search, if the company is known in our system the API will return its SICID but if not, an empty SICID in the format "00000000-0000-0000-0000-000000000000" is returned and in that case this service can be called to created the company.

The company creation service will be done in 2 steps:

  1. Request the company creation in SIC for a specific External Id (the endpoint on this page) .
    The API will start the asynchronous company creation process and return a request confirmation Id.

  2. Check the progress of the creation request and retrieve the SICID of the newly created company

  3. If the company is graded and created in SIC, it’s SICID is returned
  4. If the company is not yet created in SIC, a pending status is returned
{
	"ExternalId":{
"Service":"COCCH"	
"Id": "CH-550.1.037.847-1"
},
"CountryCode":"CH"
}


A binary file was returned

You couldn't be authenticated

{
	“ConfirmationId”:"141571966",
	“ExternalId”: {
		“Id”:"CH-550.1.037.847-1",
		“Service”: "COCCH"
	},
	“CountryCode”:"CH"
}
{
	“Code”: 5001,
	“Message”: “Company not found.”,
	“HttpStatusCode”: 404
}
{
	“Code”: 5003,
	“Message”: “Company already exists.”,
	“HttpStatusCode”: 409
}
 
Suggest Edits

Check SIC Company Creation

This endpoint checks the status of a SIC company creation request

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api-demo.single-invoice.co/v2/company/confirmationId

Path Params

confirmationId
string
required

Confirmation Id returned by the Request SIC Company Creation endpoint

If the company is graded and created in SIC the company SICID, Name, Address, Phone Number and Legal Form code are returned.
If the company is not yet created in SIC, an error is returned.

curl --request GET \
  --url https://api-demo.single-invoice.co/v2/company/confirmationId
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-demo.single-invoice.co/v2/company/confirmationId' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-demo.single-invoice.co/v2/company/confirmationId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-demo.single-invoice.co/v2/company/confirmationId");

xhr.send(data);
import requests

url = "https://api-demo.single-invoice.co/v2/company/confirmationId"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "Id": "6d568a15-f99c-4b4b-9143-fbda98b0b32e",
    "Name": "ACME INC",
    "Address": {
        "StreetNumber": "1",
        "StreetName": "EXAMPLE STREET",
        "PostCode": "92048",
        "City": "PARIS",
        "StateCode": "92",
        "CountryCode": "FR"
    },
    "PhoneNumber": "+33415175815",
    "LegalFormCode": "SA16"
} 
{
	“Code”: 5002,
	“Message”: “A company creation request has already been made and the creation is still in progress.”,
	“HttpStatusCode”: 409
}
 
Suggest Edits

Get company Group Head

Returns the group head of a company

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api-demo.single-invoice.co/v2/id/grouphead

Path Params

id
string
required

SIC ID of the company to retrieve the group head from.

 
curl -X GET \
  https://api-demo.single-invoice.co/v2/transactor//grouphead \
  -H 'apikey: YOURAPIKEY' \
  -H 'cache-control: no-cache'
import requests

url = "https://api-demo.single-invoice.co/v2/transactor//grouphead"

payload = ""
headers = {
    'apikey': "YOURAPIKEY",
    'cache-control': "no-cache"
    }

response = requests.request("GET", url, data=payload, headers=headers)

print(response.text)
GET /v2/transactor//grouphead HTTP/1.1
Host: api-demo.single-invoice.co
apikey: YOURAPIKEY
cache-control: no-cache
A binary file was returned

You couldn't be authenticated

[
    {
        "GroupHead": {
            "Id": "09fc0c0e-f3f6-451d-99c0-2810a7da0796",
            "Name": "HGA Vertriebs GmbH",
            "Address": {
                "StreetNumber": null,
                "StreetName": "Im Klosterfeld 1",
                "PostCode": "56182",
                "City": "Urbar",
                "StateCode": "56",
                "CountryCode": "DE",
                "Type": null
            },
            "PhoneNumber": "00492619882350",
            "LegalFormCode": "GMBH"
        },
        "UpdatedAt": "2017-12-13T11:01:40Z"
    }
]
 
Suggest Edits

Create Company

Creates a company in the case it has not been returned by the company search.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api-demo.single-invoice.co/v2/company/creation

Body Params

company
object
 
company.name
string
required

The name of the company to search for. Name can contain special characters but must be URL encoded. (255 char.)

company.address
object
 
company.address.streetNumber
string

Street number of the company's address (16 char.)

company.address.streetName
string
required

Street name of the company's address (64 char.)

company.address.postCode
string
required

Post code of the company's address (32 char.)

company.address.city
string
required

City of the company's address (64 char.)

company.address.stateCode
string

State code of the company's address (32 char.)

company.address.countryCode
string
required

The ISO_3166-1_alpha-2 country code.

company.phoneNumber
string

Phone number of the company (32 char.)

company.legalFormCode
string

Legal form code of the company (32 char.)

company.externalId
string
required

Unique external identifier used to identify the company.

company.externalService
string
required

Type of external identifier used to identify the company (e.g. SIREN, RNHK, ...)

This service is used by clients in Hong Kong to create seller companies that were not identified in our system through the company search in order request cover.

Authentication

This service requires an API KEY of the package COMPANYCREATION.

curl -X POST \
  https://api-demo.single-invoice.co/v2/company/creation \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: d7591e8a-c6e3-43e3-b635-46a43dbb1153' \
  -H 'apikey: YOURAPIKEY' \
  -H 'cache-control: no-cache' \
  -d '{
"Company" : {
	"Name" : "D&J Industries (Hong Kong) Company Limited",
	"Address" : {
		"StreetNumber": "2-6",
		"StreetName": "KinHong St,Room706,FvrIndstCntr2",
		"PostCode": "NA",
		"City": "Kwai Chung,New Territories,Hong Kong",
		"StateCode": null,
		"CountryCode": "HK"
	},
"PhoneNumber": "",
"LegalFormCode": "254M",
"ExternalId": "1492871",
"ExternalService": "RNHK"
}
}'
import requests

url = "https://api-demo.single-invoice.co/v2/company/creation"

payload = "{\n\"Company\" : {\n\t\"Name\" : \"D&J Industries (Hong Kong) Company Limited\",\n\t\"Address\" : {\n\t\t\"StreetNumber\": \"2-6\",\n\t\t\"StreetName\": \"KinHong St,Room706,FvrIndstCntr2\",\n\t\t\"PostCode\": \"NA\",\n\t\t\"City\": \"Kwai Chung,New Territories,Hong Kong\",\n\t\t\"StateCode\": null,\n\t\t\"CountryCode\": \"HK\"\n\t},\n\"PhoneNumber\": \"\",\n\"LegalFormCode\": \"254M\",\n\"ExternalId\": \"1492871\",\n\"ExternalService\": \"RNHK\"\n}\n}"
headers = {
    'apikey': "YOURAPIKEY",
    'Content-Type': "application/json",
    'cache-control': "no-cache",
    'Postman-Token': "89c5e1ad-33a2-46b2-8462-57cd12e19a07"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
POST /v2/company/creation HTTP/1.1
Host: api-demo.single-invoice.co
apikey:YOURAPIKEY
Content-Type: application/json
cache-control: no-cache
Postman-Token: ca0ce11c-5134-4650-90b7-3042411b783c
{
"Company" : {
	"Name" : "D&J Industries (Hong Kong) Company Limited",
	"Address" : {
		"StreetNumber": "2-6",
		"StreetName": "KinHong St,Room706,FvrIndstCntr2",
		"PostCode": "NA",
		"City": "Kwai Chung,New Territories,Hong Kong",
		"StateCode": null,
		"CountryCode": "HK"
	},
"PhoneNumber": "",
"LegalFormCode": "254M",
"ExternalId": "1492871",
"ExternalService": "RNHK"
}
}------WebKitFormBoundary7MA4YWxkTrZu0gW--
A binary file was returned

You couldn't be authenticated

{
    "id": "7b3037ac-de31-4ec7-95ba-dd9f59ecfa1f",
    "name": "D&J Industries (Hong Kong) Company Limited",
    "address": {
        "streetNumber": "2-6",
        "streetName": "KinHong St,Room706,FvrIndstCntr2",
        "postCode": "NA",
        "city": "Kwai Chung,New Territories,Hong Kong",
        "stateCode": null,
        "countryCode": "HK",
        "type": "main"
    },
    "phoneNumber": "",
    "legalFormCode": "254M",
    "externalIds": [
        {
            "externalId": "1492871",
            "externalService": "RNHK"
        }
    ]
}
 
Suggest Edits

Request Quote

Gets a new quote for a given buyer, seller and invoice. The buyer, seller and invoice details are specified as JSON in the request body.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api-demo.single-invoice.co/v2/coverage

Body Params

sellerId
string
required

Seller ID - the Single-Invoice.co transactor ID of the seller/supplier

buyerId
string
required

Buyer ID - the Single-Invoice.co transactor ID of the buyer

invoice
object
 
invoice.amount
string
required

Invoice amount - two decimal number representing the total amount on the invoice requiring coverage

invoice.currency
string
required

Invoice currency - the three letter abbrevation for the invoice currency (e.g., "eur" for Euros, "gbp" for pounds sterling, "usd" for US dollars)

invoice.dueAt
string
required

Invoice due date - the date the invoice is due for payment, as an ISO 8601 timestamp

invoice.issuedAt
string
required

Invoice issue date - the date the invoice was issued, as an ISO 8601 timestamp

invoice.number
string
required

Invoice number - the reference of the invoice to cover (non mandatory to request a quote but mandatory to a activate it)

The Request Quote endpoint provides the means for users to obtain insurance coverage quotes for invoices.

Dealing with daylight saving

Please note that when dealing with dates, the timezone may need special attention as changes to daylight savings time may affect the overall quote duration.

Once these are submitted to the endpoint via a POST request, Single-Invoice.co will provide a quote response, which will include information about whether or not the quote was accepted and the pricing (see the "Results" section above for a sample response).

The 'status' field in the response will inform the user as to the outcome of the request. The two most important values for this field after issuing a request for a quote are "Pending" and "Rejected". (There are other values for this field; please see the Get Cover By ID page for a full list of the status types.)

Pricing in the Sandbox

Please note that if you're using our Sandbox environment for development or testing, the pricing returned in our Sandbox environment may not be reflective or indicative of the true pricing, or availability of coverage. Quotes in the Sandbox environment are not binding.

Pending

The "Pending" result means that Single-Invoice.co is able to provide coverage for this particular invoice. The cost of the coverage is also supplied with the response.

Users then will evaluate the cost based on their requirements and decide whether or not to proceed. Quotes are valid for a set period (dictated by your policy); at any time during this period they can be accepted (or rejected) by the user. After the period, the quote will automatically be expired by the system and will no longer be available; a new quote will need to be made for the invoice.

If the user is happy with the quote and wishes to proceed, the next step is to Activate the coverage. Alternatively, if coverage is not required for this invoice, the Reject method would be used.

Output field
Description

currency

Currency of the policy

quotedAt

Quotation timestamp showing what time the quote was delivered

duration

The period of coverage (in days) that is being offered. Typically, coverage is calculated to the invoice due date. For example, coverage starting today and due tomorrow would return a duration of 2

bpsperday

The rate we are offering for insurance in "basis points per day"

coverPrice

The total cost of the coverage (inclusive of any fees and taxes). coverPrice is calculated from the bpsperday rate: coverPrice = coverage.bpsperday/10000 x invoice.Amount x coverage.duration

serviceFeeRate

Service fee on insurance rate excluding VAT

serviceFee

Service fee on insurance amount excluding VAT

serviceFeeVatRate

VAT rate applied on the service fee

serviceFeeVatAmount

VAT amount applied on the service fees

collectionFeeRate

Collection fee rate excluding VAT

collectionFeeAmount

Collection fee amount excluding VAT

collectionFeeVatRate

VAT rate applied on the collection fee

collectionFeeVatAmount

VAT amount applied on the collection fee

vat

VAT amount applied on the service fees (deprecated: duplicate of serviceFeeVatAmount)

insuranceTaxAmount

Insurance tax amount

insuranceTaxRate

Insurance tax rate

Rejected

The "Rejected" result means that Single-Invoice.co cannot provide coverage for the supplied invoice.

If an invoice is marked as rejected, it will also include a new "rejectedby" field in the coverage section with the name of the rejecting party. If it's rejected by the API, this field will typically be "Single-Invoice.co", but if it's rejected by the user it will be simply be "User".

curl -X POST \
  https://api-demo.single-invoice.co/v2/coverage \
  -H 'Content-Type: application/json' \
  -H 'apikey: YOURAPIKEY' \
  -H 'cache-control: no-cache' \
  -d '{
	"sellerId":"69433b40-8e8b-4cb2-99a4-b57158e19ad2",
	"buyerId":"c7ec4a56-9a9f-4c10-a833-08d3286e3dc6",
	"invoice":{
		"amount":2000,
		"currency":"eur",
		"dueAt":"2019-04-25T14:23:21.811Z",
		"issuedAt":"2019-03-16T15:23:21.811Z",
		"number":"001"
	}
}'
import requests

url = "https://api-demo.single-invoice.co/v2/coverage"

payload = "{\n\t\"sellerId\":\"69433b40-8e8b-4cb2-99a4-b57158e19ad2\",\n\t\"buyerId\":\"c7ec4a56-9a9f-4c10-a833-08d3286e3dc6\",\n\t\"invoice\":{\n\t\t\"amount\":2000,\n\t\t\"currency\":\"eur\",\n\t\t\"dueAt\":\"2019-04-25T14:23:21.811Z\",\n\t\t\"issuedAt\":\"2019-03-16T15:23:21.811Z\",\n\t\t\"number\":\"001\"\n\t}\n}"
headers = {
    'Content-Type': "application/json",
    'apikey': "YOURAPIKEY",
    'cache-control': "no-cache"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
POST /v2/coverage? HTTP/1.1
Host: api-demo.single-invoice.co
Content-Type: application/json
apikey: YOURAPIKEY
cache-control: no-cache
{
	"sellerId":"69433b40-8e8b-4cb2-99a4-b57158e19ad2",
	"buyerId":"c7ec4a56-9a9f-4c10-a833-08d3286e3dc6",
	"invoice":{
		"amount":2000,
		"currency":"eur",
		"dueAt":"2019-04-25T14:23:21.811Z",
		"issuedAt":"2019-03-16T15:23:21.811Z",
		"number":"001"
	}
}------WebKitFormBoundary7MA4YWxkTrZu0gW--
A binary file was returned

You couldn't be authenticated

{
    "id": "9dce097a-2193-4a34-87c7-86096d8a2574",
    "status": "Pending",
    "coverage": {
        "currency": "EUR",
        "quotedAt": "2019-03-26T15:23:23Z",
        "duration": 31,
        "bpsperday": 0.116129032,
        "coverPrice": 0.72,
        "serviceFeeRate": 0.2,
        "serviceFee": 0.11,
        "serviceFeeVatRate": 0.2,
        "serviceFeeVatAmount": 0.02,
        "collectionFeeRate": 0,
        "collectionFeeAmount": 0,
        "collectionFeeVatRate": 0.2,
        "collectionFeeVatAmount": 0,
        "vat": 0.02,
        "insuranceTaxAmount": 0.05,
        "insuranceTaxRate": 0.09
    },
    "sellerId": "69433b40-8e8b-4cb2-99a4-b57158e19ad2",
    "buyerId": "c7ec4a56-9a9f-4c10-a833-08d3286e3dc6",
    "invoice": {
        "Amount": 2000,
        "Currency": "eur",
        "DueAt": "2019-04-25T14:23:21Z",
        "IssuedAt": "2019-03-16T15:23:21Z",
        "Number": "001"
    }
}
{
  "message" : "Bad policy reuqest data",
  "docUrl": "https://armadill.io/docs/errors#section-bad-policy-request"
}
{
	"message" : "Expired date stamp",
  "docUrl": "https://creditshield.io/docs/authentication"
}
{
    "Code": 5001,
    "Message": "Company not found.",
    "Description": null,
    "DocUrl": "TBD"
}
 
Suggest Edits

Get Cover By ID

Returns information about a Coverage policy, including a list of transaction IDs identifying policy status changes.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api-demo.single-invoice.co/v2/coverage/id

Path Params

id
string
required

The Coverage ID

Use Get by Get by Single-Invoice.co ID to retrieve information on the buyer and seller.

Coverage Status

Each coverage policy has an associated status:

  • active - indicates the policy is currently active
  • settled - indicates a policy was settled successfully and is no longer needed. It is not possible to activate a settled policy.
  • cancelled - indicates the policy has been cancelled. It is not possible to activate a cancelled policy.
  • rejected - indicates the policy has been rejected. It is not possible to activate a rejected policy.
  • pending - indicates the policy is pending activation.
  • expired - indicates the policy has expired. It is not possible to activate an expired policy.
  • overdue - indicates the policy has been declared overdue and a claim has been filed.
  • claimed - indicates the policy's claim was successful

Each policy also contains a list of transactions that have occurred in the lifecycle of this policy. They include:

  • activated -indicates that the policy was activated
  • resolved -indicates the policy was resolved
  • cancelled -indicates the policy was cancelled
  • rejected -indicates the policy was rejected
curl --request GET \
  --url https://api-demo.single-invoice.co/v2/coverage/id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api-demo.single-invoice.co/v2/coverage/id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-demo.single-invoice.co/v2/coverage/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api-demo.single-invoice.co/v2/coverage/id");

xhr.send(data);
import requests

url = "https://api-demo.single-invoice.co/v2/coverage/id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "Id": "653ba175-f5e2-4889-9ebc-4b0b369b6f39",
    "Status": "Rejected",
    "RejectedBy": "User",
    "Coverage": {
        "Amount": 211.5,
        "Currency": "gbp",
        "RejectedAt": "2016-08-12T10:07:16Z"
    },
    "SellerId": "fdb3990c-b34e-4790-8233-b79358349e6c",
    "BuyerId": "b7663697-6c94-42b2-a11a-d842aa5ccdfa",
    "Invoice": {
        "Amount": 97322.02,
        "Currency": "gbp",
        "DueAt": "2016-10-10T00:00:00Z",
        "IssuedAt": "2016-08-10T00:00:00Z",
        "Number": null
    }
}
{
	"message" : "Missing parameters",
  "docUrl": "https://armadill.io/docs/errors#section-missing_param"
}
{
	"message" : "Bad authentication information",
  "docUrl": "http://docs.armadill.io/docs/errors#section-bad-authentication-information"
}
{
	"message" : "Resource not found",
  "docUrl": "https://armadill.io/docs/errors#section-resource_not_found"
}
{
	"message" : "Expired date stamp",
  "docUrl": "https://armadill.io/docs/authentication"
}
 
Suggest Edits

Get All Covers

Returns all covers for the current customer.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api-demo.single-invoice.co/v2/coverage?status=status&from=from&to=to&page=page

Query Params

status
string

The status to filter against. Values are "pending", "active", "cancelled", "expired" and "rejected"

from
date

An ISO 8601 datestamp indicating the start date to filter against

to
date

An ISO 8601 datestamp indicating the end date to filter against

page
int32

The page number to return, if there are more than 50 results

This method allows you to retrieve a list of all the coverages that are associated with your account.

This will include a complete list of every coverage, including quotes that have not be activated.

The list can be filtered based on the following parameters

  • Page: Current page to use for pagination of results. Page numbers start at 0.

The following filters are not yet implemented but will be available in a future update:

  • Status: filter based on a specific status (e.g., "pending" will list all coverages that have not yet been activated or rejected)
  • From: filter coverages starting from this date, supplied as an ISO 8601 timestamp
  • To: filter coverages up to this date, supplied as an ISO 8601 timestamp

Use the By ID API to retrieve information on the buyer and seller.

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

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

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

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

try
{
	$apikey = "7Rtcnaj5adqzGFt6AINktPN8Ywjv7m2uUp5zJ9wiubaP7NuAunHT9j6e5SHqPV1g";
	
	$response = $client->request('GET', $api_base_uri."/coverage", [
		'query' => [ 'page' => 0 ],  // handle page number as required
		'headers' => [ 'apikey' => $apikey ],
	]);

	// 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();

	// handle $responseBodyAsString;
}
A binary file was returned

You couldn't be authenticated

[
    {
        "id": "cb5d8b38-6abb-79dc-da78-b222fdc112c9",
        "status": "Pending",
        "coverage": {
            "amount": 5.37,
            "currency": "gbp"
        },
        "sellerId": "d4c4a3ab-c6e3-0f46-f9c7-ce28456c6d31",
        "buyerId": "6ca0192c-fe45-d083-2421-d429f1fe17f0",
        "invoice": {
            "Amount": 3360,
            "Currency": "gbp",
            "DueAt": "2016-10-01T00:00:00Z",
            "IssuedAt": "2016-09-01T00:00:00Z",
            "Number": null
        }
    },
    {
        "id": "5a13b9c5-86aa-8f5c-61bc-ef5b9ed2f35b",
        "status": "Pending",
        "coverage": {
            "amount": 38.7,
            "currency": "gbp"
        },
        "sellerId": "86ca88bf-8364-cf72-6798-10babd267fb9",
        "buyerId": "51650a5c-424f-0fe5-8153-f6663905bbae",
        "invoice": {
            "Amount": 4500,
            "Currency": "gbp",
            "DueAt": "2016-10-01T00:00:00Z",
            "IssuedAt": "2016-09-01T00:00:00Z",
            "Number": null
        }
    }
]
{
	"message" : "Bad authentication information",
  "docUrl": "http://docs.armadill.io/docs/errors#section-bad-authentication-information"
}
{
	"message" : "Expired date stamp",
  "docUrl": "https://armadill.io/docs/authentication"
}
 
Suggest Edits

Update Quote

Updates some of the quote parameters such as the invoice amount, issue date and due date.

 

Header Auth

 Authentication is required for this endpoint.
patchhttps://api-demo.single-invoice.co/v2/coverage/id

Path Params

id
string
required

The quote ID to update

Body Params

body
object
required

JSON containing the quote attributs to update: amount, dueAt, issueAt, Number.

 

This service is not activated by default. It's provided to customers who don't have the invoice final details at the time of quote.

It can happen for some market places, when the invoices of the products sold are not created by the sellers at the time of the order but instead at the time of delivery. In that case, some changes on the amount, issue date and due date can occur between the order and the delivery requiring the quote to be updated prior to activation.

When the quote is updated the API checks:

  • That the new invoice amount, if provided, is equal or lower than the one at quote time. If not an exception is returned.
  • That the cover duration, if new issue and/or due dates are provided, is equal or lower than the one at quote time. If not an error is returned.
<?php

HttpRequest::methodRegister('PATCH');
$request = new HttpRequest();
$request->setUrl('https://ehda-rel-proxy.azurewebsites.net/v2/coverage/871d188b-b7ee-482f-991e-5cbf697e023c');
$request->setMethod(HttpRequest::HTTP_METH_PATCH);

$request->setHeaders(array(
  'Postman-Token' => 'c2141a77-7e6b-4718-b2b2-75493c99f67c',
  'cache-control' => 'no-cache',
  'Content-Type' => 'application/json',
  'apikey' => 'lT0i45cXthhPCvJFoo9RBu0Lk1dEFGlSqGuMcWZBClZHFbBzc1RhKvOGZ6Wc'
));

$request->setBody('{
	"invoice":{
		"amount": 1500,
	    "dueDate": "2019-02-19T08:56:20.582Z",
	    "issuedDate": "2019-01-30T08:56:20.582Z"	
	}
    
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
PATCH /v2/coverage/871d188b-b7ee-482f-991e-5cbf697e023c HTTP/1.1
Host: ehda-rel-proxy.azurewebsites.net
apikey: lT0i45cXthhPCvJFoo9RBu0Lk1dEFGlSqGuMcWZBClZHFbBzc1RhKvOGZ6Wc
Content-Type: application/json
cache-control: no-cache
Postman-Token: 8908ecc3-3b5b-4dd7-9030-8af9718efd2f
{
	"invoice":{
		"amount": 1500,
	    "dueDate": "2019-02-19T08:56:20.582Z",
	    "issuedDate": "2019-01-30T08:56:20.582Z"	
	}
    
}------WebKitFormBoundary7MA4YWxkTrZu0gW--
curl -X PATCH \
  https://ehda-rel-proxy.azurewebsites.net/v2/coverage/871d188b-b7ee-482f-991e-5cbf697e023c \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 6c0d3dc7-bb09-48fc-92af-b09e44da66eb' \
  -H 'apikey: lT0i45cXthhPCvJFoo9RBu0Lk1dEFGlSqGuMcWZBClZHFbBzc1RhKvOGZ6Wc' \
  -H 'cache-control: no-cache' \
  -d '{
	"invoice":{
		"amount": 1500,
	    "dueDate": "2019-02-19T08:56:20.582Z",
	    "issuedDate": "2019-01-30T08:56:20.582Z"	
	}
    
}'
A binary file was returned

You couldn't be authenticated

{
  "id":"871d188b-b7ee-482f-991e-5cbf697e023c",
  "status":"Pending",
  "coverage":{
    "currency":"EUR",
    "quotedAt":"2019-01-10T08:56:11Z",
    "duration":29,
    "bpsperday":2.9540229885057471264367816093,
    "coverPrice":12.85,
    "serviceFee":2.77,
    "vat":0.46
  },
  "sellerId":"b4d3ea48-5281-4dc9-971b-6e96f08b8ab2",
  "buyerId":"5c0541c0-bde8-40a7-a6b5-63584ac006be",
  "invoice":{
    "Amount":1500,
    "Currency":"eur",
    "DueAt":"2019-02-19T08:55:43Z",
    "IssuedAt":"2019-01-21T08:55:43Z",
    "Number":"001"
  }
}
{"Code":1033,"Message":"Cover amount at activation should be equal or lower than the one at quote.","Description":null,"DocUrl":""}
{"Code":1029,"Message":"Cover duration of the quote cannot be higher than the maximum cover duration allowed by the policy.","Description":null,"DocUrl":""}
 
Suggest Edits

Activate Cover

Activates a cover by ID.

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api-demo.single-invoice.co/v2/coverage/id/activate

Path Params

id
string
required

The ID of coverage policy to activate

This method allows activation of a coverage, based on a particular quote.

The quote must be in 'Pending' status to be approved.

Once a quote is approved, insurance coverage is granted subject to the conditions of your policy.

Make sure you confirm activation was successful!

Note that under most circumstances, any quote in Pending stage will be able to be Activated.

However, it is critical to check that a quote was successfully Activated in order to make sure that you are correctly covered for an invoice. The simplest way to do this is to check the response JSON and make sure that the Status has correctly been set to Activated.

This will ensure that you can be made aware of any problems with the Activation - for example, if network problems or temporary issues with the API prevent you from successfully activating.

Note: once a cover has been activated it cannot be Rejected or "de-activated".

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

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

// Sandbox environment endpoint
$api_base_uri = 'https://api-demo.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 = "kCQXGoD48U3wUc5sRx19bLAgQESH2dFgA4nkHJiZ3a9IufN8hu5QqPINRN";
  $quoteid = "25bdc1f1-8659-9a25-17f9-6cfd668bb2a1";
	
	$response = $client->request('PUT', $api_base_uri."/coverage/$quoteid/activate", [
		'headers' => [ 'apikey' => $apikey ],
	]);

	// 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();
}
curl -H "apikey: CdF49I89tjCSoYHXh9tCXQxzNuY1C4oJM4SS7q1c" -H "Content-Type: application/json" -X PUT https://api-demo.single-invoice.co/v2.0/coverage/b37239eb-3f85-86ec-6433-d8f61c480dc4/activate -v 
A binary file was returned

You couldn't be authenticated

{
    "Id": "9a3342f9-f8d2-1486-af35-ebb905e85833",
    "Status": "Activated",
    "Coverage": {
        "Amount": 216.77,
        "Currency": "eur",
        "ActivatedAt": "2016-08-12T14:08:24Z"
    },
    "SellerId": "9a292f83-0cc6-71d9-4b86-ae9cbc4c42bd",
    "BuyerId": "758a537e-6dca-1b4a-b604-77c82199d922",
    "Invoice": {
        "Amount": 100000,
        "Currency": "eur",
        "DueAt": "2016-10-10T00:00:00Z",
        "IssuedAt": "2016-08-10T00:00:00Z",
        "Number": "Invoice_001"
    }
}
{
	"message" : "Resource not found",
  "docUrl": "https://armadill.io/docs/errors#section-resource_not_found"
}
{
	"message" : "Bad authentication information",
  "docUrl": "http://docs.armadill.io/docs/errors#section-bad-authentication-information"
}
{
	"message" : "Missing parameters",
  "docUrl": "https://armadill.io/docs/errors#section-missing_param"
}
{
	"message" : "Expired date stamp",
  "docUrl": "https://armadill.io/docs/authentication"
}
{
	"message" : "Can not activate policy",
  "docUrl": "https://armadill.io/docs/errors#section-could_not_activate"
}
 
Suggest Edits

Claim Cover [not yet implemented]

Initiates a claim against a coverage policy.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api-demo.single-invoice.co/v2/claims/:coverid/attachments

Path Params

id
string
required

The cover ID the claim request is for.

The claim endpoint allows you to upload the standard claims form PDF.

This endpoint is still under development; claims are currently processed through a workflow outside of the API as we finalise the new, improved, API-driven claims process.

The PDF should be filled out with all the required information and then uploaded as a file (via the usual POST-based multipart upload mechanism).

Once the form has been successfully uploaded, it will be delivered to the claims team and the claims process will begin.

Claims Form

The claims process is currently still under active development; the process various slightly from country to country and as a result some customisation may be required depending on your region.

The claims process described here is for policies based in France.

The French claims form is available download here.

File attachment rules:

  • filename must not only include letters, numbers, _ and a single "." character for the extension
  • filename must not be longer than 30 characters
  • file should be between 1kb and 2MB
  • file type must be PDF
<?php
// Example assumes Composer is in use with GuzzleHttp as the API library.
require_once("vendor/autoload.php");
use GuzzleHttp\Client;

require_once("functions.php");

$quoteid = "191050c8-587b-e2b3-84a5-eeeb6789e02c"; // your cover ID here

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


try
{
	$response = $client->request('POST', $api_base_uri."/claims/$quoteid/attachments", [
		'headers' => [ 'apikey' => "84wHaba2AmfyobvB2M91uIU8d6YOcw6nT" ], // your API key
		'multipart' => [
			[
				'name'     => 'file',
				'contents' => file_get_contents("claimtest.pdf"),
				'filename' => "claimtest.pdf"
			],
		],
	]);

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

	$data = json_decode($response->getBody(), true);
	print json_encode($data, JSON_PRETTY_PRINT);
}
catch (GuzzleHttp\Exception\ClientException $e) {
    $response = $e->getResponse();
    $responseBodyAsString = $response->getBody()->getContents();
	
	print "EXCEPTION: response is: \n";
	print $responseBodyAsString;
}
A binary file was returned

You couldn't be authenticated

{
    "id": "191050c8-587b-e2b3-84a5-eeeb6789e02c",
    "status": "Claimed",
    "coverage": {
        "currency": "EUR",
        "quotedAt": "2017-01-24T09:28:53Z",
        "duration": 60,
        "bpsperday": 0.05170435
    },
    "sellerId": "606262ca-7d40-09f7-d46b-57cf519e29fd",
    "buyerId": "a53b0670-e152-4177-971b-ddf4835195d5",
    "invoice": {
        "Amount": 1111,
        "Currency": "EUR",
        "DueAt": "2017-03-24T09:28:53Z",
        "IssuedAt": "2017-01-24T09:28:53Z",
        "Number": "TEST1497346133"
    }
}
{
	"message" : "Missing parameters",
  "docUrl": "https://armadill.io/docs/errors#section-missing_param"
}
{
	"message" : "Resource not found",
  "docUrl": "https://armadill.io/docs/errors#section-resource_not_found"
}
{
	"message" : "Bad authentication information",
  "docUrl": "http://docs.armadill.io/docs/errors#section-bad-authentication-information"
}
{
	"message" : "Expired date stamp",
  "docUrl": "https://armadill.io/docs/authentication"
}
 
Suggest Edits

Declare Late Payment [not yet implemented]

Notifies Single-Invoice.co that a payment of an invoice will be late

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api-demo.single-invoice.co/v2/coverage/id/late

Path Params

id
string
required

The ID of coverage policy to mark as late

Body Params

newDate
date

The new date, if known, of the expected payment. Date is an ISO 8601 datetime

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

curl --request PUT \
  --url https://api-demo.single-invoice.co/v2/coverage/id/late
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api-demo.single-invoice.co/v2/coverage/id/late' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-demo.single-invoice.co/v2/coverage/id/late")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api-demo.single-invoice.co/v2/coverage/id/late");

xhr.send(data);
import requests

url = "https://api-demo.single-invoice.co/v2/coverage/id/late"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
   "transactionId" : "8d568a15-f99c-4b4b-9143-fbda98b0b32e" 
}
{
	"message" : "Resource not found",
  "docUrl": "https://armadill.io/docs/errors#section-resource_not_found"
}
{
	"message" : "Bad authentication information",
  "docUrl": "http://docs.armadill.io/docs/errors#section-bad-authentication-information"
}
{
	"message" : "Missing parameters",
  "docUrl": "https://armadill.io/docs/errors#section-missing_param"
}
{
	"message" : "Expired date stamp",
  "docUrl": "https://armadill.io/docs/authentication"
}
{
	"message" : "Could not mark as late",
  "docUrl": "https://armadill.io/docs/errors#section-could_not_mark_late"
}
 
Suggest Edits

Reject Cover

Rejects a coverage policy.

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api-demo.single-invoice.co/v2/coverage/id/reject

Path Params

id
string
required

The ID of coverage policy to reject

This method allows rejection of a coverage, based on a particular quote ID.

The quote must be in 'Pending' status to be rejected.

On successful reject, the API will return the quote information as JSON, including the update status and two new fields:

  • rejectedby: a field indicating that it was the User who rejected this policy
  • rejectedat: the time that the user rejected the policy

Once the quote has been rejected, it's status cannot be changed - rejected quotes cannot be activated, for example. The quote must be re-requested and the new quote must be activated (note that the pricing may change between the quotes being issued).

Only covers in the Pending state can be rejected.

curl --request PUT \
  --url https://api-demo.single-invoice.co/v2/coverage/id/reject
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api-demo.single-invoice.co/v2/coverage/id/reject' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api-demo.single-invoice.co/v2/coverage/id/reject")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api-demo.single-invoice.co/v2/coverage/id/reject");

xhr.send(data);
import requests

url = "https://api-demo.single-invoice.co/v2/coverage/id/reject"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": "30e89f63-f1ae-4f01-49fb-6784b5ac77a4",
    "status": "Rejected",
    "rejectedBy": "User",
    "coverage": {
        "amount": 6.21,
        "currency": "gbp",
        "rejectedAt": "2016-09-02T12:20:31Z"
    },
    "sellerId": "c56edfd7-f739-8636-770e-28d75cca312a",
    "buyerId": "076cd9f7-b9cf-f39f-cfac-29b8a8a2efca",
    "invoice": {
        "Amount": 2500,
        "Currency": "gbp",
        "DueAt": "2016-09-30T00:00:00Z",
        "IssuedAt": "2016-08-31T00:00:00Z",
        "Number": null
    }
}
{
	"message" : "Missing parameters",
  "docUrl": "https://armadill.io/docs/errors#section-missing_param"
}
{
	"message" : "Resource not found",
  "docUrl": "https://armadill.io/docs/errors#section-resource_not_found"
}
{
	"message" : "Bad authentication information",
  "docUrl": "http://docs.armadill.io/docs/errors#section-bad-authentication-information"
}
{
	"message" : "Expired date stamp",
  "docUrl": "https://armadill.io/docs/authentication"
}
{"code":409,"message":"Cannot reject a cover with status : Rejected","docUrl":null}
 
Suggest Edits

Settle Cover

Settles a coverage policy, returning the details of the coverage upon success.

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api-demo.single-invoice.co/v2/coverage/id/settle

Path Params

id
string
required

The ID of coverage policy to settle

Body Params

settledat
string

Date and time the invoice was settled at (ISO 8601 timestamp)

This method allows settling of a cover, and should be used once your invoice has been paid in full.

The quote must be in 'Activated' status to be approved.

Once a cover has been settled, it is no longer insured.

You can pass an optional 'settledat' parameter as the JSON body to this endpoint, specifying the date (in ISO 8601 timestamp format) that the invoice was settled. If this parameter is not present, it will use the time that the request was received as the settlement date.

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

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

// Sandbox environment endpoint
$api_base_uri = 'https://api-demo.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 = "FuRLaw2qhCNslfg2em0Wfs8lftfYBUp37HfjalQXzNMIHxaNmvAVWd8jfApGD8v";
  $quoteid = "25bdc1f1-8659-9a25-17f9-6cfd668bb2a1";
	
	$response = $client->request('PUT', $api_base_uri."/coverage/$quoteid/settle", [
		'headers' => [ 'apikey' => $apikey ],
    'json' => [
						"settledat" => "2017-01-18T16:03:28Z" // this section is optional; if not passed,
      																						// the current time will be used.
			]    
	]);

	// 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();
}
A binary file was returned

You couldn't be authenticated

{
    "id": "05bb2466-3115-95dc-3f35-4664cae5f3dc",
    "status": "Settled",
    "coverage": {
        "currency": "EUR",
        "bpsperday": 1.123333333,
        "serviceFee": 13.63,
    },
    "sellerId": "ada2c9ee-9d1b-e8b4-01ec-d84fa5ef576a",
    "buyerId": "1233b55b-6feb-d755-3aa0-3d502e5eb31b",
    "invoice": {
        "Amount": 10000,
        "Currency": "EUR",
        "DueAt": "2016-12-06T00:00:00Z",
        "IssuedAt": "2016-11-23T11:03:28Z"
    }
}
{
	"message" : "Missing parameters",
  "docUrl": "https://docs.single-invoice.co/docs/errors#section-missing_param"
}
{
	"message" : "Resource not found",
  "docUrl": "https://docs.single-invoice.codocs.single-invoice.co/docs/errors#section-resource_not_found"
}
{
	"message" : "Bad authentication information",
  "docUrl": "http://docs.single-invoice.co/docs/errors#section-bad-authentication-information"
}
 
Suggest Edits

Getting Started

This page will help you get started with Single Invoice Cover.

 

This is where you show your users how to set it up. You can use code samples, like this:

$http.post('/someUrl', data).success(successCallback);

alert('test');

Try dragging a block from the right to see how easy it is to add more content!