NAV
HTTP cURL

Introduction

Welcome to the new version of our API reference. Don't hesitate to share your feedback to tech@hokodo.co

Hokodo provides a simple API to insure invoices against the risk of late or non payment. This API will help you access credit scores and insurance, for multiple use cases, including B2B merchants, B2B marketplaces, and other types of B2B platforms such as accounting, invoicing, CRM, etc.

Hokodo APIs are organized around REST, with predictable, resource-oriented URLs, and use HTTP response codes to indicate API errors.

Our API expects incoming data to be valid JSON objects with requests containing the header Content-Type: application/json, unless explicitly stated otherwise.

All responses of the API, including errors, are in JSON, except for some endpoints returning PDF documents, Excel files or CSV files, that will be clearly indicated as such.

You can view request/response examples in the dark area to the right, and you can switch between raw representation and curl command with tabs in the top right.

The base URL of the API in the sandbox (see environments) is https://api-sandbox.hokodo.co/v1/

Authorization

To authentify pass the correct header with each request:

GET /v1/me HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/me/ \
  --header "Authorization: Token <your_api_key>"

Make sure to replace <your_api_key> with your API key from https://sandbox.hokodo.co.

Use your secret key in your API requests. You can manage your keys in your Developer dashboard. Be sure to keep your key secure and do not share it in publicly-accessible areas, such as GitHub, in your client-side Javascript code, etc.

Authorization to the API is done by providing the key in Authorization header preceded by Token keyword. The API key can also be provided as user with no password through HTTP Basic Auth.

All API requests must be made over HTTPS. Calls made over plain HTTP or without proper authentication will fail.

Testing the API

Please make sure to test your integration thoroughly in our sandbox before going live. After registering, you will be given your test API keys. Those are safe to use for development. When you are ready, make sure to replace those keys with live ones.

While testing, the API will not return real pricing and insurance results. If you want to simulate how well we can cover your clients, please do not hesitate to get in touch with our team at partner-support@hokodo.co.

API versioning

The API is in version v1. Your feedback is most appreciated for any improvement.

Backwards compatible changes are made regularly to improve the API. You can find the changelog in the partner dashboard.

Pagination

For example to get 10 transactions starting with the 51st transaction:

GET /v1/transactions/?limit=10&offset=50 HTTP/1.1
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/transactions/?limit=10&offset=50 \
  --header "Authorization: Token <your_api_key>"

The answer is a JSON looking like this:

{
    "count": 95,  # Total number of transactions
    "next": "http://api-sandbox.hokodo.co/v1/transactions/?limit=10&offset=60",
    "previous": null,
    "results": [
        {
            ... # 51st transaction in the list
        },
        {
            ... # 52nd transaction in the list
        },
        ...
    ]
}

The API returns paginated results, for list endpoints where the response might contain many items in a large list. By default, the number of items returned is 25.

You can control the page size and position by using the query parameters limit and offset. limit controls the number of items displayed, offset the index of the first item of the list, starting from 0. The defaults if no value is passed are thus offset=0 and limit=25.

See examples on the right.

Expansion

For example let's consider the following request:

GET /v1/quotes/quo-kEFDnwu8cnkETeagWAcqF4 HTTP/1.1
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/quotes/quo-kEFDnwu8cnkETeagWAcqF4 \
  --header "Authorization: Token <your_api_key>"

It's returning the following JSON response (compacted for the example):

{
    "url": "http://api-sandbox.hokodo.co/v1/quotes/quo-kEFDnwu8cnkETeagWAcqF4",
    "id": "quo-kEFDnwu8cnkETeagWAcqF4",
    "transaction": "trns-TiehJCGZmFRkKoL8NsM3d6",
    "client": "co-7QCHuTN5AJycwX7iw9ofW2",
    "status": "accepted",
    "policy": "pol-EGmUpq4GjeAGJfVXTb2A5Z",
    ...  # Other quote fields
}

We can use expand=policy,client for example:

GET /v1/quotes/quo-kEFDnwu8cnkETeagWAcqF4?expand=policy,client HTTP/1.1
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/quotes/quo-kEFDnwu8cnkETeagWAcqF4?expand=policy,client \
  --header "Authorization: Token <your_api_key>"

As a response we get:

{
    "url": "http://api-sandbox.hokodo.co/v1/quotes/quo-kEFDnwu8cnkETeagWAcqF4",
    "id": "quo-kEFDnwu8cnkETeagWAcqF4",
    "transaction": "trns-TiehJCGZmFRkKoL8NsM3d6",
    "client": {
        "url": "https://api-sandbox.hokodo.co/v1/companies/co-7QCHuTN5AJycwX7iw9ofW2",
        "id": "co-7QCHuTN5AJycwX7iw9ofW2",
        "country": "GB",
        "name": "Hokodo Ltd",
        "address": "20-22 Wenlock Road, London, England, N1 7GU",
        "city": "London",
        "postcode": "N1 7GU",
        ...  # Other client field
    },
    "status": "accepted",
    "policy": {
        "url": "http://api-sandbox.hokodo.co/v1/policies/pol-EGmUpq4GjeAGJfVXTb2A5Z",
        "id": "pol-EGmUpq4GjeAGJfVXTb2A5Z",
        "status": "active",
        "created": "2018-10-31T10:55:34.580940Z",
        "documents": [],
        "collection": null
    },
    ...  # Other quote fields
}

The API returns some items as API identifiers. The designated resource can be expanded, meaning that the identifier is replaced in the response with a dictionary representing the resource itself. You can control which field is expanded using the query parameter expand. Expected value is a comma separated list of field names.

Note: At the moment, only read requests can use expansion. You can't use resource expansion for requests where you create and modify resources.

See examples on the right.

Environments

Test environment (aka Sandbox)

Register at: https://sandbox.hokodo.co
API base URL: https://api-sandbox.hokodo.co/v1/

This is the test environment for our API clients, where you can integrate your own software with our API without consequences. It will always run the same version(s), expect the same request format and return the same response format as the production environment.

Data such as prices or underwriting decisions will not be real however, and no insurance is provided. Non-sensitive data, such as companies search, will be as close as possible to the production data.

Production

Apply at: https://www.hokodo.co/contact
API base URL: https://api.hokodo.co/v1/

This is the live, production environment, where:

Data formats

Countries

Requests

  • customer countries
GET /v1/countries/customer HTTP/1.1
curl --request GET \
    --url https://api-sandbox.hokodo.co/v1/countries/customer
  • debtor countries
GET /v1/countries/debtor HTTP/1.1
curl --request GET \
    --url https://api-sandbox.hokodo.co/v1/countries/debtor

Response

200 Ok
Content-Type: application/json
[
  {
    "code": "GB",
    "name": "United Kingdom"
  },
  {
    "code": "FR",
    "name": "France"
  }
]

Where a country input field is required by the API, you can use either the ISO 3166-1 alpha-2 code or the country's name. See below on how to obtain a full list of accepted countries.

Obtain a list of valid countries for a customer.

Obtain a list of valid countries for a debtor.

Dates and times

When a date, or date and time field is required by the API, it is expected in ISO 8601 notation, for example:

Type Format Example
Date yyyy-mm-dd 2018-10-31
Datetime yyyy-mm-ddThh:mm:ss.ffffff 2018-10-31T16:53:00.12345
Datetime UTC yyyy-mm-ddThh:mm:ss.ffffffZ 2018-10-31T16:53:00.12345Z

For invoice issue and due dates for example, there is no time associated and the API expects only a date, no time nor timezone. Be careful if you are internally converting a datetime with timezone to a date, e.g. 2018-10-31T00:00:00+02:00 could become 2018-10-30T22:00:00Z when converted to UTC and then 2018-10-30 in the request to the API, which wouldn't fit the user input.

Currencies

When a currency field is used by the API, it is an ISO 4217 code, such as GBP, EUR or USD.

Decimals

When a money amount is expected or returned by the API, it is a Decimal number presented as a string, e.g. "-50.00". The API usually presents monetary amounts with 2 decimal places, quantities - with 3 decimal places, and other amounts with 6 decimal places.

Companies

Companies register on your platform, and may themselves fill in information about third-party companies. To work with these, we need to properly identify them first.

Companies endpoints

Company object

{
  "url": "https://api-dev.hokodo.co/v1/companies/co-bqRyKAGaFrEEN8JMjWJiqk",
  "id": "co-bqRyKAGaFrEEN8JMjWJiqk",
  "name": "Hokodo Ltd",
  "creation_date": "2018-02-20",
  "status": "Active",
  "legal_form": "Private limited with share capital",
  "accounts_type": "SMALL",
  "country": "GB",
  "address": "35 Kingsland Road, London, E2 8AA",
  "city": "London",
  "postcode": "E2 8AA",
  "email": "",
  "phone": "",
  "sectors": [
    {
      "system": "SIC2007",
      "code": "64999"
    },
    {
      "system": "SIC2007",
      "code": "62012"
    },
    {
      "system": "SIC2007",
      "code": "66220"
    }
  ],
  "identifiers": [
    {
      "idtype": "reg_number",
      "country": "GB",
      "value": "11215527"
    }
  ]
}
field type description
url string API endpoint to access the company
id string(uuid) API unique identifier for the company
name string Company name
creation_date date Date of inception of the company
status string Current status of the company. You are generally interested about Active or ACT companies
legal_form string Legal form of the company. The list of possible legal forms varies from country to country.
accounts_type string /!\ TODO /!\
country country Registered address: country code
address string Registered address: full postal address
city string Registered address: city name
postcode string Registered address: postcode
email string Contact email address for the company
phone string Contact phone number for the company
sectors list The list of sectors the company operate in.
sectors[*][system] string The system of reference to interprete the code (SIC2007 in UK, NAF_2008 in FR)
sectors[*][code] string Sector code in the given system
identifiers list The list of official identifiers know for this company
identifiers[*][id_type] string The type of identifier (reg_number for a registration number, lei for an indentifier of the Global LEI System, vat_number for a tax identifier)
identifiers[*][country] country Country in which the identifier is relevant when it applies. Can be blank.
identifiers[*][value] string Identifier

Request

POST /v1/companies/search HTTP/1.1
Content-Type: application/json

{
  "name": "Hokodo Ltd",
  "country": "GB"
}
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/companies/search \
  --header "Content-Type: application/json"
  --data-binary "{
    \"name\": \"Hokodo Ltd\",
    \"country\": \"GB\"
}"

Responses

  • regular response
200 OK
Content-Type: application/json
{
  "matches": [
    {
      "url": "https://api-sandbox.hokodo.co/v1/companies/co-EWzoaRqbvsdq8FW7dB6evL",
      "id": "co-EWzoaRqbvsdq8FW7dB6evL",
      "country": "GB",
      "name": "HOKODO LTD",
      "address": "35 Kingsland Road, London, United Kingdom, E2 8AA",
      "city": "London",
      "postcode": "E2 8AA",
      "legal_form": "",
      "sectors": [],
      "creation_date": "2018-02-20",
      "identifiers": [
        {
          "idtype": "reg_number",
          "country": "GB",
          "value": "11215527"
        }
      ],
      "email": "",
      "phone": "",
      "status": "Undefined",
      "accounts_type": null,
      "confidence": null
    },
    {
      "url": "https://api-sandbox.hokodo.co/v1/companies/co-JbTDrzejAhRafYrKSFEGi4",
      "id": "co-JbTDrzejAhRafYrKSFEGi4",
      "country": "GB",
      "name": "Hokodo Services Ltd",
      "address": "35 Kingsland Road, London, E2 8AA",
      "city": "London",
      "postcode": "E2 8AA",
      "legal_form": "Private limited with share capital",
      "sectors": [],
      "creation_date": "2018-05-09",
      "identifiers": [
        {
          "idtype": "reg_number",
          "country": "GB",
          "value": "11351988"
        }
      ],
      "email": "",
      "phone": "",
      "status": "Active",
      "accounts_type": null,
      "confidence": null
    }
  ]
}
  • no results
200 OK
Content-Type: application/json
{
  "matches": []
}
  • error response (country field missing)
{
  "country": [
    "This field is required."
  ]
}
  • error response (name and reg_number fields missing)
400 Bad Request 
Content-Type: application/json
{
  "non_field_errors": [
    "Not enough information to identify company. Provide at least country and either name or registration number."
  ]
}

Search for a company by country, name, registration number if available. Country is mandatory, and one of name or registration number must be provided. The API will try to find the best match and return a list of potential matches.

field description requirement
country Country the company is registered in required
name Name of the company required*
reg_number Registration number in country required*

(at least one of fields, marked with * is required)

Errors:

code description
400 a required field is missing

View Company

Request

GET /v1/companies/{company_id} HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key> 
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/companies/{company_id} \
  --header "Authorization: Token <your_api_key>"
  --header "Content-Type: application/json"

Responses

  • regular response
200 OK
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/companies/co-EWzoaRqbvsdq8FW7dB6evL",
  "id": "co-EWzoaRqbvsdq8FW7dB6evL",
  "country": "GB",
  "name": "HOKODO LTD",
  "address": "35 Kingsland Road, London, United Kingdom, E2 8AA",
  "city": "London",
  "postcode": "E2 8AA",
  "legal_form": "",
  "sectors": [],
  "creation_date": "2018-02-20",
  "identifiers": [
    {
      "idtype": "reg_number",
      "country": "GB",
      "value": "11215527"
    }
  ],
  "email": "",
  "phone": "",
  "status": "Undefined",
  "accounts_type": null
}
  • not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Look up a previously found company.

Errors:

code description
404 the company_id is probably invalid, and the company has not been found

Sole traders

By default, only certain types of companies can be insured by Hokodo. Sole traders in the United Kingdom are not registered and found in Companies House's database, and cannot be found in our company search API. They can however be used in the API as creditors, and insured by Hokodo. If a significant portion of your users are sole traders, get in touch with us to enable that function for you.

You will be able to create SoleTrader objects, which are an extension of the Company objects. These can be used as creditors in transactions.

Sole trader endpoints

SoleTrader object

{
    "id": "co-YuNEQ4nqA6Yto9QQUBnopW",
    "soletrader_id": "st-eE4un8TnDNjx9Uac2DVa6N",
    "owner": "user-sVr7a58Smbfqbo8cVpjEV6",
    "unique_id": "0d201ab1-46df-4274-8c90-256eaa66c135"
    "vat_number": "15141312",
    "trading_name": "The Dogfather 21",
    "trading_address": "123 Commercial St, Shoreditch",
    "trading_address_city": "London",
    "trading_address_country": "GB",
    "proprietor_name": "John John",
    "proprietor_address_line1": "Flat 5",
    "proprietor_address_line2": "10 Residential Street",
    "proprietor_address_line3": "Hackney",
    "proprietor_address_city": "London",
    "proprietor_address_postcode": "EC2 8AA",
    "proprietor_address_country": "GB",
    "date_of_birth": "1969-12-31"
}
field type flags description
id string(uuid) read-only Unique company identifier for the object. To be used where a Company identifier is required, such as creditor in a transaction.
soletrader_id string(uuid) read-only Unique identifier for the object. To be used where a SoleTrader identifier is required.
owner string(uuid) required Unique identifier of the user associated to the sole trader.
unique_id string required Unique identifier of the sole trader at your platform
vat_number string optional VAT number of the sole trader if available.
trading_name string required Company's name
trading_address string optional Company's full address
trading_address_city string optional Company's city
trading_address_country string optional Company's country
proprietor_name string required Proprietor's name
proprietor_address_line1 string optional Proprietor's address
proprietor_address_line2 string optional Proprietor's address
proprietor_address_line3 string optional Proprietor's address
proprietor_address_city string optional Proprietor's city
proprietor_address_postcode string optional Proprietor's postcode
proprietor_address_country string required Proprietor's country
date_of_birth string optional Proprietor's date of birth (e.g. 1969-12-31). Accepted format: YYYY-MM-DD.

Create a sole trader

Request

POST /v1/soletraders HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "owner": "user-KZcuB2oT6BPTjmQJiHm7ha",
  "trading_name": "The Dogfather",
  "trading_address": "123 Commercial St, Shoreditch",
  "trading_address_city": "London",
  "trading_address_country": "GB",
  "proprietor_name": "John John",
  "proprietor_address_line1": "Flat 5",
  "proprietor_address_line2": "10 Residential Street",
  "proprietor_address_line3": "Hackney",
  "proprietor_address_city": "London",
  "proprietor_address_postcode": "EC2 8AA",
  "proprietor_address_country": "GB",
  "vat_number": "15141312",
  "unique_id": "0d201ab1-46df-4274-8c90-256eaa66c136",
  "date_of_birth": "1969-12-31"     
}
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/soletraders \
  --header "Authorization: Token <your_api_key>" \
  --header 'Content-Type: application/json' \
  --data-binary "{
    \"owner\": \"user-KZcuB2oT6BPTjmQJiHm7ha\",
    \"trading_name\": \"The Dogfather\",
    \"trading_address\": \"123 Commercial St, Shoreditch\",
    \"trading_address_city\": \"London\",
    \"trading_address_country\": \"GB\",
    \"proprietor_name\": \"John John\",
    \"proprietor_address_line1\": \"Flat 5\",
    \"proprietor_address_line2\": \"10 Residential Street\",
    \"proprietor_address_line3\": \"Hackney\",
    \"proprietor_address_city\": \"London\",
    \"proprietor_address_postcode\": \"EC2 8AA\",
    \"proprietor_address_country\": \"GB\",
    \"vat_number\": \"15141312\",
    \"unique_id\": \"0d201ab1-46df-4274-8c90-256eaa66c136\",
    \"date_of_birth\": \"1969-12-31\"
}"

Responses

  • regular response
201 Created
Content-Type: application/json
{
  "id": "co-5oh3SJKQBaKMov9PYR7BkA",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "soletrader_id": "st-Vdrisa6GZnSp49ZaqMDssR",
  "trading_name": "The Dogfather",
  "trading_address": "123 Commercial St, Shoreditch",
  "trading_address_city": "London",
  "trading_address_country": "GB",
  "proprietor_name": "John John",
  "proprietor_address_line1": "Flat 5",
  "proprietor_address_line2": "10 Residential Street",
  "proprietor_address_line3": "Hackney",
  "proprietor_address_city": "London",
  "proprietor_address_postcode": "EC2 8AA",
  "proprietor_address_country": "GB",
  "vat_number": "15141312",
  "unique_id": "0d201ab1-46df-4274-8c90-256eaa66c136",
  "date_of_birth": "1969-12-31"
}
  • error response (example)
400 Bad Request
Content-Type: application/json
{
  "owner": [
    "Invalid pk \"user-KZcuB2oT6BPTjmQJiHm7hb\" - object does not exist."
  ],
  "unique_id": [
    "sole trader with this Unique identifier on platform already exists."
  ]
}

To create a sole trader, you create a SoleTrader object.

Errors

errors description
400 a required field is missing or some fields have incorrect values

List sole traders

Request

POST /v1/soletraders HTTP/1.1
Authorization: Token <your_api_key>
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/soletraders \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "co-5oh3SJKQBaKMov9PYR7BkA",
      "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
      "soletrader_id": "st-Vdrisa6GZnSp49ZaqMDssR",
      "trading_name": "The Dogfather",
      "trading_address": "123 Commercial St, Shoreditch",
      "trading_address_city": "London",
      "trading_address_country": "GB",
      "proprietor_name": "John John",
      "proprietor_address_line1": "Flat 5",
      "proprietor_address_line2": "10 Residential Street",
      "proprietor_address_line3": "Hackney",
      "proprietor_address_city": "London",
      "proprietor_address_postcode": "EC2 8AA",
      "proprietor_address_country": "GB",
      "vat_number": "15141312",
      "unique_id": "0d201ab1-46df-4274-8c90-256eaa66c136",
      "date_of_birth": "1969-12-31"
    }
  ]
}

List all sole traders, created by your platform

View sole trader

Request

POST /v1/soletraders/<soletrader_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/soletraders/co-5oh3SJKQBaKMov9PYR7BkA \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "id": "co-5oh3SJKQBaKMov9PYR7BkA",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "soletrader_id": "st-Vdrisa6GZnSp49ZaqMDssR",
  "trading_name": "The Dogfather",
  "trading_address": "123 Commercial St, Shoreditch",
  "trading_address_city": "London",
  "trading_address_country": "GB",
  "proprietor_name": "John John",
  "proprietor_address_line1": "Flat 5",
  "proprietor_address_line2": "10 Residential Street",
  "proprietor_address_line3": "Hackney",
  "proprietor_address_city": "London",
  "proprietor_address_postcode": "EC2 8AA",
  "proprietor_address_country": "GB",
  "vat_number": "15141312",
  "unique_id": "0d201ab1-46df-4274-8c90-256eaa66c136",
  "date_of_birth": "1969-12-31"
}

Retrieve a single sole trader, created by your platform

Errors

errors description
404 the soletrader_id is probably invalid, the sole trader has not been found

Modify sole trader

Request

PATCH /v1/soletraders/<soletrader_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "trading_name": "The Catfather",
  "proprietor_name": "Johnny John"
}
curl --request PATCH
  --url https://api-sandbox.hokodo.co/v1/soletraders/co-5oh3SJKQBaKMov9PYR7BkA \
  --header "Authorization: Token <your_api_key>" \
  --header 'Content-Type: application/json' \
  --data-binary "{
    \"trading_name\": \"The Catfather\",
    \"proprietor_name\": \"Johnny John\"
}"

Response

200 Ok
Content-Type: application/json
{
  "id": "co-5oh3SJKQBaKMov9PYR7BkA",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "soletrader_id": "st-Vdrisa6GZnSp49ZaqMDssR",
  "trading_name": "The Catfather",
  "trading_address": "123 Commercial St, Shoreditch",
  "trading_address_city": "London",
  "trading_address_country": "GB",
  "proprietor_name": "Johnny John",
  "proprietor_address_line1": "Flat 5",
  "proprietor_address_line2": "10 Residential Street",
  "proprietor_address_line3": "Hackney",
  "proprietor_address_city": "London",
  "proprietor_address_postcode": "EC2 8AA",
  "proprietor_address_country": "GB",
  "vat_number": "15141312",
  "unique_id": "0d201ab1-46df-4274-8c90-256eaa66c136",
  "date_of_birth": "1969-12-31"  
}

Modify previously created sole trader

Errors

errors description
404 the soletrader_id is probably invalid, the sole trader has not been found
400 a required field is missing or some fields have incorrect values

Scores

We compute an internal score to assess risk on companies in order to offer the best insurance prices for your users. We can make internal scores available to you and/or your users to help you better manage credit risk.

Note that all examples in this documentation are for illustration purposes only and do not represent a real risk assessment from Hokodo.

Scores endpoint

Company Score object

{
  "company": "co-EWzoaRqbvsdq8FW7dB6evL",
  "name": "Hokodo Ltd",
  "country": "GB",
  "reg_number": "11215527",
  "address": "35 Kingsland Road, London, E2 8AA",
  "score": "2",
  "net_assets": 1780444,
  "annualized_turnover": null,
  "creation_date": "2018-02-20",
  "ultimate_parent_company": "Hokodo Ltd",
  "number_officers": 3,
  "accounts_next_duedate": "2021-02-28",
  "latest_financials_date": "2019-05-31",
  "change_net_assets": null,
  "change_annualized_turnover": null,
  "status": "Active"
}
field type description
company string(uuid) API unique identifier for the company
name string Company name
reg_number string Registration number of the company
creation_date date Date of inception of the company
status string Current status of the company. You are generally interested about Active or ACT companies
country country Registered address: country code
address string Registered address: full postal address
number_officers integer TODO
ultimate_parent_company string Name of the ultimate parent of the current company
score string The actual score value, see below
net_assets integer TODO
annualized_turnover integer TODO
accounts_next_duedate date TODO
latest_financials_date date TODO
change_net_assets integer TODO
change_annualized_turnover integer TODO

Score value

The score value ranges from 1 to 5 with following indicative meaning:

value description recommendation S&P's equivalent
"5" Danger We do not recommend extending credit terms to this company unless you are really confident that you will get paid. C-, B-
"4" Caution This firm has a weak credit rating. Manage your exposure to this company carefully. B, B+
"3" Acceptable This firm has acceptable financial health, but you should still ensure you can withstand the costs of any default. BB-, BB+
"2" Fair This firm has reasonable financial health, though invoice protection can provide additional security. BBB-, A+
"1" Excellent This firm has strong financial health. AA-, AAA

For partners who have more advanced credit management needs, we can provide more detailed scales upon request.

View Company Score

Requests

  • with raw company data
POST /v1/scores HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key> 

{
  "name": "Hokodo Ltd.",
  "country": "GB"
}
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/scores \
  --header "Authorization: Token <your_api_key>"
  --header "Content-Type: application/json"
  --data-binary "{
    \"name\": \"Hokodo Ltd\",
    \"country\": \"GB\"
}"
  • with identified company
POST /v1/scores HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key> 

{
  "company": "co-EWzoaRqbvsdq8FW7dB6evL"
}
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/scores \
  --header "Authorization: Token <your_api_key>"
  --header "Content-Type: application/json"
  --data-binary "{
    \"company\": \"co-EWzoaRqbvsdq8FW7dB6evL\"
}"

Responses

  • regular response
200 OK
Content-Type: application/json
{
  "company": "co-EWzoaRqbvsdq8FW7dB6evL",
  "name": "Hokodo Ltd",
  "country": "GB",
  "reg_number": "11215527",
  "address": "35 Kingsland Road, London, E2 8AA",
  "score": "2",
  "net_assets": 1780444,
  "annualized_turnover": null,
  "creation_date": "2018-02-20",
  "ultimate_parent_company": "Hokodo Ltd",
  "number_officers": 3,
  "accounts_next_duedate": "2021-02-28",
  "latest_financials_date": "2019-05-31",
  "change_net_assets": null,
  "change_annualized_turnover": null,
  "status": "Active"
}
  • company does not exist (raw company data)
200 OK
Content-Type: application/json
{
  "company": null,
  "name": "Non-existent-company",
  "country": "GB",
  "reg_number": "",
  "address": "",
  "score": null,
  "net_assets": null,
  "annualized_turnover": null,
  "creation_date": "",
  "ultimate_parent_company": "",
  "number_officers": null,
  "accounts_next_duedate": "",
  "latest_financials_date": "",
  "change_net_assets": null,
  "change_annualized_turnover": null,
  "status": ""
}
  • company does not exist (with identified company)
400 Bad Request
Content-Type: application/json
{
  "company": [
    "Invalid pk \"co-EWzoaRqbvsdq8FW7dB6evd\" - object does not exist."
  ]
}
  • error response
400 Bad Request
Content-Type: application/json
{
  "company": [
    "Bad prefix. Expected a UUID prefixed by \"co\", but got non-existent-company."
  ]
}

Obtain the score of a single company. The company may have been identified using the search company endpoint beforehand. Otherwise, the API will try and identify the best match based on raw information.

If you choose not to provide company, you have to specify country and at least one of name or reg_number, just like Company search.

field description requirement
company Identifier of the company for which risk is to be evaluated preferred
name Name of the company optional
country Country of the company optional
reg_number Company registration number in the country optional
address Address of the company of the user optional

Errors

errors description
400 A field is not in the expected format

Credit limits

This endpoint is in beta with a limited set of partners at the moment. Please let us know if you would like to have access to it.

Depending on the company of the debtor or the creditor, the history of their transactions and repayments, Hokodo can insure their transactions up to a certain credit limit. As a B2B platform using Hokodo, you might want to check whether one of your customers can benefit from Hokodo's insurance, and to know up to which amount.

If your customer is about to complete a transaction, you can use the Transaction endpoint to inform Hokodo about the invoice, and the Quote endpoint to check if it is eligible to insurance.

However, in other situations, your customer may not yet have decided what they want to purchase, but you may wish to proactively know and/or inform them of their eligibility. You may want to know how big of a transaction is insurable for that customer. Or you may want to display that information on your platform. The credit limits endpoints are designed for these situations.

You may do that for example when the customer registers, or when they login, or at regular intervals.

To get the available credit limit for a customer on your platform, please use the following endpoint with the associated customer Company id

POST /credit_limits/debtor/company/<company_id>/

You will get one of the two possible responses:

Please note that credit limits can evolve over time as new information about the company arises (good or bad), we build a history of orders and repayments with the company, etc.

Note that all examples in this documentation are for illustration purposes only and do not represent a real risk assessment from Hokodo.

Credit limits endpoint

Credit limit object

{
    "company": "co-74cgmhG9U79oTWGEW4jeDW",
    "status": "eligible",
    "rejection_reason": {
      "code": "something-something",
      "detail": "An actual sentence",
      "params": {
          "key": "value"
      }
    },
    "credit_limit": {
        "currency": "GBP",
        "available_insured_amount": "9876.54",
        "current_insured_amount": "1234.56",
        "maximum_insured_amount": "11111.10",
    }
}
field type description
company string(uuid) API unique identifier for the company
status string Current credit approval status (eligible or declined)
rejection_reason dictionary If status is declined, details about why, otherwise null
current_credit_limit dictionary Current credit limit if approved
current_credit_limit[currency] currency ISO 4217 currency code (e.g. GBP, EUR)
current_credit_limit[available_insured_amount] decimal Credit limit currently available
current_credit_limit[current_insured_amount] decimal Credit limit currently in use
current_credit_limit[maximum_insured_amount] decimal Total credit limit

Please note that the amounts are given as insurance exposure amounts. If Hokodo covers, for example, 90% of the value of invoices on your platform, then the amounts returned in this endpoint are for the 90% of actually insured value, not for the total amount of invoices.

For example, if the available_insured_amount is "9,000.00", and the cover provided by Hokodo is for 90% of the value of invoices, you could give a customer credit for an invoice up to "10,000.00" in value.

Please also note that in general the maximum_insured_amount will equal available_insured_amount plus current_insured_amount.

However occasionally this will not be true. The main reason that can happen is that the buyer has other exposures with Hokodo (on other platforms) which have eroded some of his limit on your platform. In general we avoid this scenario by ring-fencing limits for platforms, but occasionally this is not possible (e.g. for buyers with very small limits).

Therefore, it’s best to focus on the available limit and utilisation: you should display the available_insured_amount and current_insured_amount numbers (adjusted for your insured percentage).

Request debtor credit limit

Requests

POST /v1/credit_limits/debtor/company/co-74cgmhG9U79oTWGEW4jeDW/ HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "currency": "GBP"
}
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/credit_limits/debtor/company/co-74cgmhG9U79oTWGEW4jeDW/ \
  --header "Authorization: Token <your_api_key>"
  --header "Content-Type: application/json"
  --data-binary '{
  "currency": "GBP"
}'

Responses

  • eligible
200 OK
Content-Type: application/json
{
    "company": "co-74cgmhG9U79oTWGEW4jeDW",
    "status": "eligible",
    "rejection_reason": null,
    "credit_limit": {
        "currency": "GBP",
        "available_insured_amount": "9876.54",
        "current_insured_amount": "1234.56",
        "maximum_insured_amount": "11111.10",
    }
}
  • declined
200 OK
Content-Type: application/json
{
    "company": "co-74cgmhG9U79oTWGEW4jeDW",
    "status": "declined",
    "rejection_reason": {
      "code": "something-something",
      "detail": "An actual sentence",
      "params": {
          "key": "value"
      }
    },
    "credit_limit": {
        "currency": "GBP",
        "available_insured_amount": null,
        "current_insured_amount": null,
        "maximum_insured_amount": null,
    }
}

Request the credit limit for a company, as a debtor (buyer side of the transaction).

The currency is optional in the request, and defaults to EUR if not provided.

field description requirement
currency currency Desired currency for the credit limit, as a ISO 4217 currency code (e.g. GBP, EUR)

Errors

errors description
400 A field is not in the expected format

Legacy users

Your platform can create a user by calling this endpoint. The created user is not yet registered and cannot directly login into our system. However they can register anytime and get access to past transactions and operations associated with them.

A user is necessary to create transactions and later request an insurance offer. It is associated with a company and other information about the future client, such as their email on the platform, their date of registration on the platform, etc.

To create a legacy user, the associated company may have been identified using the search company endpoint beforehand or raw data can be provided until user has the opportunity to review.

Legacy user endpoints

Legacy user object

{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "unique_id": "",
  "has_password": false,
  "name": "John",
  "phone": "",
  "registered": "2017-06-01T14:37:12Z",
  "country": "GB",
  "company": null,
  "company_address": "",
  "company_country": "GB",
  "company_name": "Hokodo Ltd",
  "company_regnum": ""
}
field type description
id string(uuid) API unique identifier for the user
email string Email of the user
unique_id string Unique identifier of the user on your platform (currently we don't validate its uniqueness and store it for your reference only)
has_password boolean Describes whether the user has registered with Hokodo and created a password
name string Full name of the user
phone string Phone of the user
registered datetime Date of user registration on your platform
country country Country of the user
company_name string Name of the company
company_address string Address of the company
company_country country Country of the company
company_regnum string Registration number of the company

Note that registered is the user's registration date on your platform, not in Hokodo.

Create a legacy user

Request

POST /v1/users HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key> 

{
  "name": "John",
  "email": "johnny@hokodo.co",
  "company_name": "Hokodo Ltd",
  "company_country": "GB",
  "registered": "2017-06-01T14:37:12Z",
  "client_type": "free"
}
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/users \
  --header "Authorization: Token <your_api_key>"
  --header "Content-Type: application/json"
  --data-binary="{
    \"name\": \"John\",
    \"email\": \"johnny@hokodo.co\",
    \"company_name\": \"Hokodo Ltd\",
    \"company_country\": \"GB\",
    \"registered\": \"2017-06-01T14:37:12Z\",
    \"client_type\": \"free\"
}"

Response

  • regular response
201 Created
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "unique_id": "",
  "has_password": false,
  "name": "John",
  "phone": "",
  "registered": "2017-06-01T14:37:12Z",
  "country": "GB",
  "company": null,
  "company_address": "",
  "company_country": "GB",
  "company_name": "Hokodo Ltd",
  "company_regnum": ""
}
  • error response
400 Bad Request
Content-Type: application/json
{
  "email": [
    "This field is required."
  ],
  "name": [
    "This field is required."
  ],
  "registered": [
    "This field is required."
  ]
}

The user's name, email and registration date on your platform must be provided. If the company has been identified, you can directly provide its identifier. Otherwise, you may simply fill as much as possible of the raw information (name, country, regnum, address).

field description requirement
name Full name of user required
email Email address of the user required
registered Registration date on your platform required
plan_type Type of plan (free, paying, premium) deprecated
phone Phone number of user optional
unique_id Unique identifier of the user on your platform optional
country Country of the user optional
company Identifier of the company of the user preferred
company_name Name of the company of the user optional
company_country Country of the company of the user optional
company_regnum Company registration number in the country optional
company_address Address of the company of the user optional

Notes:

  1. Repeated POST requests with user information that contains the same email address will trigger partial updates on the existing user.

  2. Creating a user with this endpoint does not grant the user full access to Hokodo resources. They are still expected to perform self-registration via our Customer portal and set up their credentials.

Errors

errors description
400 a required field is missing or some fields have incorrect values

List legacy users

Request

GET /v1/users HTTP/1.1
Authorization: Token <your_api_key> 
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/users \
  --header "Authorization: Token <your_api_key>"

Response

200 OK
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "user-mECT3e5n9i7gVGrbn2Pd38",
      "email": "johnny@hokodo.co",
      "unique_id": "",
      "has_password": false,
      "name": "John",
      "phone": "",
      "registered": "2017-06-01T14:37:10Z",
      "country": "GB",
      "company": null,
      "company_address": "",
      "company_country": "GB",
      "company_name": "Hokodo Lt",
      "company_regnum": ""
    }
  ]
}

You can list all users associated with your platform.

Get legacy user

Request

GET /v1/users/<user_id> HTTP/1.1
Authorization: Token <your_api_key> 
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38 \
  --header "Authorization: Token <your_api_key>"

Response

  • regular response
200 OK
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "unique_id": "",
  "has_password": false,
  "name": "John",
  "phone": "",
  "registered": "2017-06-01T14:37:10Z",
  "country": "GB",
  "company": null,
  "company_address": "",
  "company_country": "GB",
  "company_name": "Hokodo Lt",
  "company_regnum": ""
}
  • user not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Retrieve a previously created user.

Errors

errors description
404 the user_id is probably invalid, the user has not been found

Modify legacy user

TODO: We need to merge contorta!250 for his part to work

Delete legacy user

Request

DELETE /v1/users/<user_id> HTTP/1.1
Authorization: Token <your_api_key> 
curl --request DELETE \
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38 \
  --header "Authorization: Token <your_api_key>"

Response

  • regular response
204 No Content
  • user not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Delete a previously created user.

Errors

errors description
404 the user_id is probably invalid, the user has not been found

Organisations

The concept of organisation was introduced to enable grouping of users, as well as facilitate ownership of transactions by organisation entities. If you do not have organisations with multiple users or users with multiple organisations on your platform, you can omit the level of organisations and work with users directly.

Organisation concept

If the organisations functionality is enabled, an organisation can become a transaction's owner. Users can also be labelled as members of an organisation, with different roles and permissions. Note that one user can be part of multiple organisations.

Users in the same organisation will be able to see the same invoices, company matching etc. Depending on their role inside the organisation, they will be able to edit objects linked to the organisation.

Consider the following example:

Charlie, Bob, and Alice are members of the organisation "Test Ltd" from the "Cash flow for SMEs" platform.

When an invoice is synced with the Hokodo API by the "Cash flow for SMEs" platform, when a quote is made, when a customer name is matched to a company, etc., all this applies at the organisation level. It is shared between all the members of the organisation.

At the same time, Charlie and Bob can be members of "Test Plus Ltd", and they will be able to match customer names to companies, add invoices, request quotes etc. together under the name of the new organisation, while Alice will not have access to it.

This is a typical API flow to use organisations:

User roles within organisations

Users can have one of the following roles in an organisation:

Organisation endpoints

Organisation object

{
  "id": "org-9RxFsXTgnWqwjK4apxBAn8",
  "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
  "registered": "2017-06-01T14:37:12Z",
  "plan_type": "free",
  "company": null,
  "company_name": "Test Ltd",
  "company_country": "GB",
  "company_regnum": "",
  "company_address": "",
  "company_postcode": "",
}
field type flags description
id string(uuid) read-only API unique identifier for the user
created datetime read-only Created time
modified datetime read-only Last modified time
unique_id string required Unique identifier of the organisation on your platform
registered datetime required When the organisation registered on your platform
plan_type string deprecated Type of plan (free, paying, premium)
company string optional Hokodo unique identifier of the company
company_name string optional Company name
company_regnum string optional Company registration number
company_address string optional Company address
company_postcode string optional Company postal/zip code
company_city string optional Company city
company_country country optional Company country
has_purchased_policy boolean read-only Indicates whether the organisation has ever purchased any policy
users list read-only List of users attached to the organisation

Note that registered is the organisation's registration date on your platform, not in Hokodo.

Create an organisation

Request

POST /v1/organisations HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
  "registered": "2017-06-01T14:37:12Z",
  "company_name": "Test Ltd",
  "company_country": "GB" 
}
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/organisations \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"unique_id\": \"c105b862-f1ba-4197-9d97-57db63196b00\",
    \"registered\": \"2017-06-01T14:37:12Z"\,
    \"company_name\": \"Test Ltd\",
    \"company_country\": \"GB\"
}"

Responses

  • organisation created successfully
201 Created
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
  "registered": "2017-06-01T14:37:12Z",
  "company": null,
  "company_name": "Test Ltd",
  "company_regnum": "",
  "company_address": "",
  "company_postcode": "",
  "company_city": "",
  "company_state": "",
  "company_country": "GB",
  "has_purchased_policy": false,
  "users": []
}
  • organisation already exists (identified by unique_id), it is updated
200 Ok
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
  "registered": "2017-06-01T14:37:12Z",
  "company": null,
  "company_name": "Test Ltd",
  "company_regnum": "",
  "company_address": "",
  "company_postcode": "",
  "company_city": "",
  "company_state": "",
  "company_country": "GB",
  "has_purchased_policy": false,
  "users": []
}

To create an organisation, you create an Organisation object.

Errors

errors description
400 a required field is missing or a field has incorrect format

List organisations

Request

GET /v1/organisations HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET
  --url https://api-sandbox.hokodo.co/v1/organisations \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "org-pHr6VCyzQJALUsePkatPBo",
      "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
      "registered": "2017-06-01T14:37:12Z",
      "company": null,
      "company_name": "Test Ltd",
      "company_regnum": "",
      "company_address": "",
      "company_postcode": "",
      "company_city": "",
      "company_state": "",
      "company_country": "GB",
      "has_purchased_policy": false,
      "users": []
    }
  ]
}

List organisations created by your platform

View organisation

Request

GET /v1/organisations/<organisation_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "org-pHr6VCyzQJALUsePkatPBo",
      "unique_id": "c105b862-f1ba-4197-9d97-57db63196b00",
      "registered": "2017-06-01T14:37:12Z",
      "company": null,
      "company_name": "Test Ltd",
      "company_regnum": "",
      "company_address": "",
      "company_postcode": "",
      "company_city": "",
      "company_state": "",
      "company_country": "GB",
      "has_purchased_policy": false,
      "users": []
    }
  ]
}

Retrieve an organisation created by your platform

Errors

errors description
404 the organisation_id is probably invalid, the organisation has not been found

Modify organisation

Request

PATCH /v1/organisations/<organisation_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "unique_id": "c105b862-f1ba-4197-9d97-57db63196b01",
  "registered": "2018-06-01T14:37:12Z",
  "company_name": "Another Test Ltd",
  "company_country": "FR" 
}
curl --request PATCH
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"unique_id\": \"c105b862-f1ba-4197-9d97-57db63196b01\",
    \"registered\": \"2018-06-01T14:37:12Z"\,
    \"company_name\": \"Another Test Ltd\",
    \"company_country\": \"FR\"
}"

Response

200 Ok
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "unique_id": "c105b862-f1ba-4197-9d97-57db63196b01",
  "registered": "2018-06-01T14:37:12Z",
  "company": null,
  "company_name": "Another Test Ltd",
  "company_regnum": "",
  "company_address": "",
  "company_postcode": "",
  "company_city": "",
  "company_state": "",
  "company_country": "FR",
  "has_purchased_policy": false,
  "users": []
}

Modify an organisation created by your platform

Errors

errors description
404 the organisation_id is probably invalid, the organisation has not been found
400 a required field is missing or a field has incorrect format

Delete an organisation

Request

DELETE /v1/organisations/<organisation_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request DELETE
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo \
  --header "Authorization: Token <your_api_key>"

Responses

  • regular response
204 No Content
  • can not delete organisation, it has objects attached
409 Conflict
Content-Type: application/json
{
  "detail": "Organisation has undeletable objects attached, it cannot be deleted."
}

Delete an organisation created by your platform. Please note, that you can not delete an organisation that has insurance-related objects attached to it (such as accepted quotes or policies, etc.)

Errors

errors description
404 the organisation_id is probably invalid, the organisation has not been found
409 an organisation can not be deleted because it has objects attached to it

Users

Your platform can create a user by calling this endpoint. The created user will not be registered, and will not be able to directly login into our system just yet. However they will be able to register anytime in the future, and get access to past transactions and operations.

Users not linked to an organisation cannot access transactions, request quotes or generate policies. Therefore we suggest creating the organisation first, then create users linked to the organisation with the proper role.

User endpoints

User object

{
  "id": "user-VG4i93EPLRamVFK6oXpvt9",
  "email": "johnny@hokodo.co",
  "unique_id": "",
  "has_password": false,
  "name": "John",
  "phone": "",
  "registered": "2017-06-01T14:37:12Z",
  "organisations": [
    {
      "id": "org-FEjrdMsmhdNp34HxaZ6n63",
      "role": "member"
    }
  ]
}
field type flags description
id string(uuid) read-only API unique identifier for the user
email string required Email of the user
unique_id string optional Unique identifier of the user on your platform (currently we don't validate its uniqueness and store it for your reference only)
has_password boolean read-only True if the user has registered with Hokodo and created a password
name string required Full name of the user
phone string optional Phone number of the user
registered datetime required Date of user registration on your platform
organisations list optional List of organisations to which the user is linked
organisations[*][id] string(uuid) required API identifier of the organisation
organisations[*][role] role required Role of the user in the organisation

Note that registered is the user's registration date on your platform, not in Hokodo.

Create a user

Request

POST /v1/users HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key> 

{
  "name": "John",
  "email": "johnny@hokodo.co",
  "registered": "2017-06-01T14:37:12Z",
  "organisations": [
    {
      "id": "org-FEjrdMsmhdNp34HxaZ6n63",
      "role": "member"
    }
  ]
}
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/users \
  --header "Authorization: Token <your_api_key>"
  --header "Content-Type: application/json"
  --data-binary="{
    \"name\": \"John\",
    \"email\": \"johnny@hokodo.co\",
    \"registered\": \"2017-06-01T14:37:12Z\",
    \"organisations\": [
      {
        \"id\": \"org-FEjrdMsmhdNp34HxaZ6n63\",
        \"role\": \"member\"
      }
    ]
}"

Response

  • regular response
201 Created
Content-Type: application/json
{
  "id": "user-VG4i93EPLRamVFK6oXpvt9",
  "email": "johnny@hokodo.co",
  "unique_id": "",
  "has_password": false,
  "name": "John",
  "phone": "",
  "registered": "2017-06-01T14:37:12Z",
  "organisations": [
    {
      "id": "org-FEjrdMsmhdNp34HxaZ6n63",
      "role": "member"
    }
  ]
}
  • error response
400 Bad Request
Content-Type: application/json
{
  "email": [
    "This field is required."
  ],
  "name": [
    "This field is required."
  ],
  "registered": [
    "This field is required."
  ],
  "organisations": [
    "This field is required."
  ]
}

To create a user, you create a User object.

Notes:

  1. Repeated POST requests with user information that contains the same email address will trigger partial updates on the existing user. Still, organisations field must be omitted on the repeated POST requests, as it will generate a validation exception:{ "organisations": "You can't set this field for an existing user." }

  2. To gain full access to Hokodo resources the users that were created by a platform are still expected to perform self-registration via our Customer portal and set up their credentials.

errors description
400 a required field is missing

List users

Request

GET /v1/users HTTP/1.1
Authorization: Token <your_api_key> 
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/users \
  --header "Authorization: Token <your_api_key>"

Response

200 OK
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "user-mECT3e5n9i7gVGrbn2Pd38",
      "email": "johnny@hokodo.co",
      "unique_id": "",
      "has_password": false,
      "name": "John",
      "phone": "",
      "registered": "2017-06-01T14:37:12Z",
      "organisations": [
        {
          "id": "org-FEjrdMsmhdNp34HxaZ6n63",
          "role": "member"
        }
      ]
    }
  ]
}

List all users associated with your platform.

Get user

Request

GET /v1/users/<user_id> HTTP/1.1
Authorization: Token <your_api_key> 
curl --request GET \
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38 \
  --header "Authorization: Token <your_api_key>"

Response

  • regular response
200 OK
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "unique_id": "",
  "has_password": false,
  "name": "John",
  "phone": "",
  "registered": "2017-06-01T14:37:12Z",
  "organisations": [
    {
      "id": "org-FEjrdMsmhdNp34HxaZ6n63",
      "role": "member"
    }
  ]
}
  • user not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Look up a previously created user.

errors description
404 the user_id is probably invalid, the user has not been found

Modify user

Request

PATCH /v1/users/<user_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key> 

{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "unique_id": "some-unique-id",
  "name": "Johnny",
  "phone": "+1234567890",
  "registered": "2018-06-01T14:37:10Z"
}

Response

200 OK
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "unique_id": "some-unique-id",
  "has_password": false,
  "name": "Johnny",
  "phone": "+1234567890",
  "registered": "2018-06-01T14:37:10Z",
  "organisations": [
    {
      "id": "org-FEjrdMsmhdNp34HxaZ6n63",
      "role": "member"
    }
  ]
}

Update a previously created user.

Please note that organisation membership can not be updated via this endpoint.

errors description
404 the user_id is probably invalid, the user has not been found
400 updating a user failed or some of the fields have incorrect format

Delete user

Request

DELETE /v1/users/<user_id> HTTP/1.1
Authorization: Token <your_api_key> 
curl --request DELETE \
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38 \
  --header "Authorization: Token <your_api_key>"

Response

  • regular response
204 No Content
  • user not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Delete a previously created user.

Errors

errors description
404 the user_id is probably invalid, the user has not been found

Manage organisations of user

If your platform supports multiple organisations per user and you have already created some organisations in our API, you can manage users memberships and roles in various organisations. Please refer to section Organisations regarding creating and managing organisations.

Our API provides two alternative endpoint collections to manage relation between users and organisations. Below is the list of methods from the perspective of a user. For the list of methods from the perspective of an organisation, please refer to section Manage users in organisation

User organisations endpoints

User organisation object

{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "role": "admin"
}
field type flags description
id string(uuid) required API unique identifier for the organisation
role role required Role of the user in the organisation

Add user to organisation

Request

POST /v1/users/<user_id>/organisations HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "role": "admin"
}
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38/organisations \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"id\": \"org-pHr6VCyzQJALUsePkatPBo\",
    \"role\": \"admin"\
}'

Responses

  • regular response
201 Created
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "role": "admin"
}
  • user already added to the organisation
200 Ok
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "role": "admin"
}
  • error (organisation not found and/or incorrect user role)
400 Bad Request
Content-Type: application/json
{
  "id": [
    "Invalid pk \"org-mECT3e5n9i7gVGrbn2Pd39\" - object does not exist."
  ],
  "role": [
    "\"reader\" is not a valid choice."
  ]
}

Attach existing user to a previously created organisation. When a user is already added to the organisation, but a different role is provided in the request, his existing role will be updated.

To create a user, see the relevant section.

Errors

errors description
400 a required field is missing or a field has incorrect format

View organisations of a user

Request

GET /v1/users/<user_id>/organisations HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38/organisations \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "org-pHr6VCyzQJALUsePkatPBo",
      "role": "admin"
    }
  ]
}

List all organisations of a user

View individual organisation of user

Request

GET /v1/users/<user_id>/organisations/<organisation_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38/organisations/org-pHr6VCyzQJALUsePkatPBo \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "role": "admin"
}

Retrieve one specific organisation of a user

Errors

errors description
404 the organisation_id is probably invalid, the organisation has not been found

Modify user role in organisation

Request

PATCH /v1/users/<user_id>/organisations/<organisation_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "role": "member"
}
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38/organisations/org-pHr6VCyzQJALUsePkatPBo \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"role\": \"member"\
}'

Responses

  • regular response
200 Ok
Content-Type: application/json
{
  "id": "org-pHr6VCyzQJALUsePkatPBo",
  "role": "member"
}
  • error (incorrect user role)
400 Bad Request
Content-Type: application/json
{
  "role": [
    "\"reader\" is not a valid choice."
  ]
}

Modify the role of the user in a specific organisation

Errors

errors description
400 the role field is missing or has incorrect value

Remove user from organisation

Request

DELETE /v1/users/<user_id>/organisations/<organisation_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request DELETE
  --url https://api-sandbox.hokodo.co/v1/users/user-mECT3e5n9i7gVGrbn2Pd38/organisations/org-pHr6VCyzQJALUsePkatPBo \
  --header "Authorization: Token <your_api_key>"

Response

204 No Content

Remove the user from a specific organisation

Errors

errors description
404 the organisation_id is probably invalid, the organisation has not been found

Manage users in organisation

Our API provides two alternative endpoint collections to manage relation between users and organisations. Below is the list of methods from the perspective of an organisation. For the list of methods from the perspective of a user, please refer to section Manage organisations of user

Organisation users endpoints

Organisation user object

{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "role": "admin"
}
field type flags description
id string(uuid) required API unique identifier for the user
email string read-only Email of the user
role role required Role of the user in the organisation

Add user to organisation

Request

POST /v1/organisations/<organisation_id>/users HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "role": "admin"
}
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo/users \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"id\": \"user-mECT3e5n9i7gVGrbn2Pd38\",
    \"role\": \"admin"\
}'

Responses

  • regular response
201 Created
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "role": "admin"
}
  • user already added to the organisation
200 Ok
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "role": "admin"
}
  • error (user not found and/or incorrect user role)
400 Bad Request
Content-Type: application/json
{
  "id": [
    "Invalid pk \"user-mECT3e5n9i7gVGrbn2Pd39\" - object does not exist."
  ],
  "role": [
    "\"reader\" is not a valid choice."
  ]
}

Attach previously created user to the organisation. When a user is already added to the organisation, but a different role is provided in the request, his existing role will be updated.

Users can have one of the following roles in an organisation:

To create a user, see the relevant section.

Errors

errors description
400 a required field is missing or a field has incorrect format

View users of organisation

Request

GET /v1/organisations/<organisation_id>/users HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo/users \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "user-mECT3e5n9i7gVGrbn2Pd38",
      "email": "johnny@hokodo.co",
      "role": "admin"
    }
  ]
}

List all current users of an organisation

View individual user of organisation

Request

GET /v1/organisations/<organisation_id>/users/<user_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo/users/user-mECT3e5n9i7gVGrbn2Pd38 \
  --header "Authorization: Token <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "role": "admin"
}

Retrieve one specific user of an organisation

Errors

errors description
404 the user_id is probably invalid, the user has not been found

Modify user role in organisation

Request

PATCH /v1/organisations/<organisation_id>/users/<user_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "role": "member"
}
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo/users/user-mECT3e5n9i7gVGrbn2Pd38 \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"role\": \"member"\
}'

Responses

  • regular response
200 Ok
Content-Type: application/json
{
  "id": "user-mECT3e5n9i7gVGrbn2Pd38",
  "email": "johnny@hokodo.co",
  "role": "member"
}
  • error (incorrect user role)
400 Bad Request
Content-Type: application/json
{
  "role": [
    "\"reader\" is not a valid choice."
  ]
}

Modify the role of a specific user in an organisation

Errors

errors description
400 the role field is missing or has incorrect value

Remove user from organisation

Request

DELETE /v1/organisations/<organisation_id>/users/<user_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request DELETE
  --url https://api-sandbox.hokodo.co/v1/organisations/org-pHr6VCyzQJALUsePkatPBo/users/user-mECT3e5n9i7gVGrbn2Pd38 \
  --header "Authorization: Token <your_api_key>"

Response

204 No Content

Remove one specific user from the organisation

Errors

errors description
404 the user_id is probably invalid, the user has not been found

Transactions

A transaction describes an invoice, or order, or any other form of transaction described on your platform, past or present, closed or ongoing.

You will need to create a transaction, before requesting an insurance quote on it.

In order to be able to provide your customers the most adapted insurance offers, we need to have information about their transaction history on your platform. This helps us assess their credit relationship with their clients, especially for smaller companies, as well as reduce fraud.

To do so, you should create transactions through the API prior to requesting insurance.

Transaction endpoints

Transaction object

{
  "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "trns-yQKxbtCg9aTS5JYnsRVA9B",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "debtor": "co-AgBGknk7D8KixY2ntbJtmT",
  "debtor_name": "",
  "debtor_country": "",
  "debtor_regnum": "",
  "debtor_address": "",
  "creditor": "co-K35WAmVFuSo6SCAPrSNdkP",
  "creditor_name": "",
  "creditor_country": "",
  "creditor_regnum": "",
  "creditor_address": "",
  "status": "pending",
  "pay_method": "bank",
  "net_amount": "10000.00",
  "gross_amount": "12000.00",
  "currency": "GBP",
  "issue_date": "2018-04-25",
  "due_date": "2018-05-21",
  "paid_date": null,
  "number": "AB2018-123",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": "10.000",
      "unit_price": "1000.00"
    }
  ],
  "source": null,
  "transaction_key": "JqzI0T5W7FFdUODv9vkU2bXOTJyV2kT7-Ku2ESJJKXQ",
  "estimated_quote_price": null,
  "metadata": null,
  "referral_url": "https://sandbox.hokodo.co/?transaction=trns-yQKxbtCg9aTS5JYnsRVA9B&key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scheduled_payments": [
    {
      "date": "2018-05-21",
      "amount": "12000.00"
    }
  ],
  "payments": []
}
field type flags description
url string read-only API endpoint to access the transaction
id string(uuiod) read-only API unique identifier for the transaction
owner string(uuid) required API unique identifier for the owner of the transaction (user or organisation)
unique_id string optional Unique identifier of the transaction in your platform (currently we don't validate its uniqueness and store it for your reference only, but we may enforce uniqueness in the future)
debtor string(uuid) optional API unique identifier for the debtor company (can be expanded to a full Company object)
debtor_name string optional Name of the debtor company (if separately provided at create/update)
debtor_country country optional Country of the debtor company (if separately provided at create/update)
debtor_regnum string optional Registration number of the debtor company (if separately provided at create/update)
debtor_address string optional Address of the debtor company (if separately provided at create/update)
creditor string(uuid) optional API unique identifier for the creditor company (can be expanded to a full Company object)
creditor_name string optional Name of the creditor company (if separately provided at create/update)
creditor_country country optional Country of the creditor company (if separately provided at create/update)
creditor_regnum string optional Registration number of the creditor company (if separately provided at create/update)
creditor_address string optional Address of the creditor company (if separately provided at create/update)
number string optional Transaction number according to the owner's internal numbering system
status string optional Transaction status
pay_method string optional Payment method
net_amount decimal optional Decimal value of the net transaction amount
gross_amount decimal optional Decimal value of the gross transaction amount
currency currency optional Currency of transaction amounts
issue_date date optional Date of issuance of the transaction
due_date date optional Date due of the transaction
paid_date date optional Date when the transaction is paid in full
items list optional The list of items that constitute the transaction
items[*][decription] string required Description of the item
items[*][quantity] decimal required Number of items in the transaction
items[*][unit_price] decimal required Price of a single item
scheduled_payments list optional The list of partial payments, expected according to a defined schedule
scheduled_payments[*][date] string required Payment date
scheduled_payments[*][amount] decimal required Payment amount in transaction currency
payments list optional The list of partial payments, that have actually been received
payments[*][id] string(uuid) read-only API unique identifier for the transaction payment
payments[*][date] string required Payment date
payments[*][amount] decimal required Payment amount in transaction currency
policy string(uuid) read-only API unique identifier for the transaction policy (if created, can be expanded to a full Policy object)
quote string(uuid) read-only API unique identifier for the transaction quote (if created, can be expanded to a full Quote object)
source string read-only Source of transaction (available if the transaction has been imported from an accounting platform)
referral_url string read-only A URL for referring the customer to Hokodo Quote&Buy website, see Referral URL
metadata dict optional Set of key-value pairs you can attach to the object. You can use this to store your custom data in the object and read it back later.
estimated_quote_price null deprecated

Transaction status

The transaction status must be one of:

On draft transactions

Draft transaction status can be used for transactions that the user has not yet commited to, eg. they put something in their cart but did not go through with the checkout.

A draft transaction can be updated, like any other uninsured transaction. Its status can only go from draft to pending though, and a pending transaction cannot go back to the draft status.

An insured transaction cannot be updated. In particular an insured draft transaction cannot be updated via the transaction update API endpoint. The only change you can make to an insured draft transaction is to change its status to pending. See below for more details.

This will change the status of a transaction from draft to pending, and works even if the transaction has already been insured.

Payment method

The payment_method must be one of:

Create transaction

Requests

  • using debtor and creditor, previously identifier by the API
POST /v1/transactions HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "owner": "user-nNqgg5AFymQMumaU7EdrLa",
  "debtor": "co-4MRXDjtbScBmDzbrTbh9SW",
  "creditor": "co-7QCHuTN5AJycwX7iw9ofW2",
  "net_amount": 10000,
  "gross_amount": 12000,
  "currency": "GBP",
  "issue_date": "2018-04-25",
  "due_date": "2018-05-21",
  "paid_date": "2018-06-10",
  "number": "AB2018-123",
  "status": "paid",
  "pay_method": "bank",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": 10,
      "unit_price": 1000
    }
  ],
  "unique_id": "876987-987uinjojna-I8UH98Jnj"
}
curl --request POST \
     --url https://api-sandbox.hokodo.co/v1/transactions \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary "{
    \"owner\": \"user-nNqgg5AFymQMumaU7EdrLa\",
    \"debtor\": \"co-4MRXDjtbScBmDzbrTbh9SW\",
    \"creditor\": \"co-7QCHuTN5AJycwX7iw9ofW2\",
    \"net_amount\": 10000.000,
    \"gross_amount\": 12000.000,
    \"currency\": \"GBP\",
    \"issue_date\": \"2018-04-25\",
    \"due_date\": \"2018-05-21\",
    \"paid_date\": \"2018-06-10\",
    \"number\": \"AB2018-123\",
    \"status\": \"paid\",
    \"pay_method\": \"bank\",
    \"items\": [
        {
            \"description\": \"Super ergonomic chairs\",
            \"quantity\": 10,
            \"unit_price\": 1000
        }
    ],
    \"unique_id\": \"876987-987uinjojna-I8UH98Jnj\"
}"
  • using debtor and creditor raw information
POST /v1/transactions HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-krF9xKJcjC28mKGV2byJof",
  "id": "trns-krF9xKJcjC28mKGV2byJof",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "debtor": null,
  "debtor_name": "Debtor Company",
  "debtor_country": "GB",
  "debtor_regnum": "1234567890",
  "debtor_address": "Some existing address",
  "creditor": null,
  "creditor_name": "Creditor Company",
  "creditor_country": "GB",
  "creditor_regnum": "9876543210",
  "creditor_address": "Some other existing address",
  "status": "pending",
  "pay_method": "bank",
  "net_amount": "10000.00",
  "gross_amount": "12000.00",
  "currency": "GBP",
  "issue_date": "2018-04-25",
  "due_date": "2018-05-21",
  "paid_date": null,
  "number": "AB2018-123",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": "10.000",
      "unit_price": "1000.00"
    }
  ],
  "source": null,
  "transaction_key": "tQ9OhMH-uxIvHswdISDce2sfVxpMRX3eEyx2RXs0YV4",
  "estimated_quote_price": null,
  "metadata": null,
  "scheduled_payments": [],
  "payments": []
}
curl --request POST \
     --url https://api-sandbox.hokodo.co/v1/transactions \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary "{
    \"owner\": \"user-nNqgg5AFymQMumaU7EdrLa\",
    \"debtor_name\": \"Debtor Company\",
    \"debtor_country\": \"GB\",
    \"debtor_regnum\": \"1234567890\",
    \"debtor_address\": \"Some existing address\",
    \"creditor_name\": \"Creditor Company\",
    \"creditor_country\": \"GB\",
    \"creditor_regnum\": \"9876543210\",
    \"creditor_address\": \"Some other existing address\",
    \"net_amount\": 10000.000,
    \"gross_amount\": 12000.000,
    \"currency\": \"GBP\",
    \"issue_date\": \"2018-04-25\",
    \"due_date\": \"2018-05-21\",
    \"paid_date\": \"2018-06-10\",
    \"number\": \"AB2018-123\",
    \"status\": \"paid\",
    \"pay_method\": \"bank\",
    \"items\": [
        {
            \"description\": \"Super ergonomic chairs\",
            \"quantity\": 10,
            \"unit_price\": 1000
        }
    ],
    \"unique_id\": \"876987-987uinjojna-I8UH98Jnj\"
}"

Responses

  • regular response (debtor and creditor identified by API)
201 Created
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "trns-yQKxbtCg9aTS5JYnsRVA9B",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "debtor": "co-AgBGknk7D8KixY2ntbJtmT",
  "debtor_name": "",
  "debtor_country": "",
  "debtor_regnum": "",
  "debtor_address": "",
  "creditor": "co-K35WAmVFuSo6SCAPrSNdkP",
  "creditor_name": "",
  "creditor_country": "",
  "creditor_regnum": "",
  "creditor_address": "",
  "status": "pending",
  "pay_method": "bank",
  "net_amount": "10000.00",
  "gross_amount": "12000.00",
  "currency": "GBP",
  "issue_date": "2018-04-25",
  "due_date": "2018-05-21",
  "paid_date": null,
  "number": "AB2018-123",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": "10.000",
      "unit_price": "1000.00"
    }
  ],
  "source": null,
  "transaction_key": "JqzI0T5W7FFdUODv9vkU2bXOTJyV2kT7-Ku2ESJJKXQ",
  "estimated_quote_price": null,
  "metadata": null,
  "referral_url": "https://sandbox.hokodo.co/?transaction=trns-yQKxbtCg9aTS5JYnsRVA9B&key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scheduled_payments": [],
  "payments": []
}
  • regular response (debtor and creditor not identified by API)
201 Created
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "trns-yQKxbtCg9aTS5JYnsRVA9B",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "debtor": null,
  "debtor_name": "Debtor Company",
  "debtor_country": "GB",
  "debtor_regnum": "1234567890",
  "debtor_address": "Some existing address",
  "creditor": null,
  "creditor_name": "Creditor Company",
  "creditor_country": "GB",
  "creditor_regnum": "1234567890",
  "creditor_address": "Some existing address",
  "status": "pending",
  "pay_method": "bank",
  "net_amount": "10000.00",
  "gross_amount": "12000.00",
  "currency": "GBP",
  "issue_date": "2018-04-25",
  "due_date": "2018-05-21",
  "paid_date": null,
  "number": "AB2018-123",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": "10.000",
      "unit_price": "1000.00"
    }
  ],
  "source": null,
  "transaction_key": "JqzI0T5W7FFdUODv9vkU2bXOTJyV2kT7-Ku2ESJJKXQ",
  "estimated_quote_price": null,
  "metadata": null,
  "referral_url": "https://sandbox.hokodo.co/?transaction=trns-yQKxbtCg9aTS5JYnsRVA9B&key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scheduled_payments": [],
  "payments": []
}
  • error response (example)
400 Bad Request
Content-Type: application/json
{
  "debtor": [
    "Invalid pk \"co-AgBGknk7D8KixY2ntbJtmA\" - object does not exist."
  ],
  "creditor": [
    "Bad prefix. Expected a UUID prefixed by \"co\", but got some-company."
  ]
}
  • error response (incorrect owner type) http-doc 400 Bad Request Content-Type: application/json json-doc { "owner": [ "Bad prefix. Expected a UUID prefixed by \"org\", but got user-mECT3e5n9i7gVGrbn2Pd38." ] }

To create a transaction, you create a Transaction object.

Most fields are optional. Only the owner is required. It identifies a user or organisation of the platform to which the transaction is attached.

Many fields are optional. However to obtain a quote later the system must be provided with the following information at least:

The more information is provided at transaction creation, the better the quote quality and the less friction for client subscription later on.

The preferred way to identify the debtor is to provide the debtor's API unique identifier in the debtor field. However, you may use debtor_country in conjunction with debtor_name and / or debtor_regnum to obtain a match later on. These fields behave the same way than a Company search. The same goes for creditor fields.

Errors

errors description
400 a required field is missing or some of the fields have incorrect value

Company matching for existing transactions

Request

PUT /v1/transactions/<transaction_id>/match_debtor HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "debtor": "co-CWzEFpHwrmxx9NWsXXL7u8"
}
curl --request POST
  --url https://api-sandbox.hokodo.co/v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B"/match-debtor \
  --header "Authorization: Token <your_api_key>" \
  --header "Content-Type: application/json" \
  --data-binary "{
    \"debtor\": \"co-CWzEFpHwrmxx9NWsXXL7u8"\
}'

Responses

  • regular response
200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "trns-yQKxbtCg9aTS5JYnsRVA9B",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "debtor": "co-CWzEFpHwrmxx9NWsXXL7u8",
  "debtor_name": "Debtor Company",
  "debtor_country": "GB",
  "debtor_regnum": "1234567890",
  "debtor_address": "Some existing address",
  "creditor": null,
  "creditor_name": "Creditor Company",
  "creditor_country": "GB",
  "creditor_regnum": "1234567890",
  "creditor_address": "Some existing address",
  "status": "pending",
  "pay_method": "bank",
  "net_amount": "10000.00",
  "gross_amount": "12000.00",
  "currency": "GBP",
  "issue_date": "2018-04-25",
  "due_date": "2018-05-21",
  "paid_date": null,
  "number": "AB2018-123",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": "10.000",
      "unit_price": "1000.00"
    }
  ],
  "source": null,
  "transaction_key": "JqzI0T5W7FFdUODv9vkU2bXOTJyV2kT7-Ku2ESJJKXQ",
  "estimated_quote_price": null,
  "metadata": null,
  "referral_url": "https://sandbox.hokodo.co/?transaction=trns-yQKxbtCg9aTS5JYnsRVA9B&key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scheduled_payments": [],
  "payments": []
}
  • error (debtor not found)
400 Bad Request
Content-Type: application/json
{
  "debtor": [
    "Invalid pk \"co-AgBGknk7D8KixY2ntbJtmd\" - object does not exist."
  ]
}

When a user fills in details of an invoice, or when importing invoices from an external accounting/invoicing provider, often enough only the name of the debtor is filled in. To provide accurate quotes, we need to match that debtor name to a precise legal entity.

The API provides a number of ways to do that, depending on your use case. The user could be typing a company name every time, or creating companies and typing the name only once, or importing that data from an external accounting package. Here are some options:

The remaining part of this sub-section describes the latter scenario.

Concepts of company matching

Let's start with an example. The user has to create customers before assigning them to their invoices. To do that, they have to enter their name and country. For example the user creates "Test customer" in the United Kingdom. Every time the user wants to create an invoice to "Test customer", they pick them from a list of options.

Before offering an insurance quote, make it visible to the user that they need to match the name to an actual company. Once they do that, you can inform the API:

  1. provide the user with a list of choices of possible companies matching the free text they typed
  2. create a CompanyMatch object that saves this choice

All the transactions of this user that had "Test customer" for debtor name will be automatically updated to point to the correct legal entity, for example "Test Customer LTD". Once the user imports new invoices with the same debtor name, the match will be made automatically as well.

If one of these transactions was already insured, we do not modify it but trigger a warning, to be handled by our customer support.

The CompanyMatch object

field type flags description
debtor string(uuid) required API unique identifier of the debtor

Create a match

To create a match, you associate the debtor of a transaction to a company identified by its Hokodo API identifier. That identifier can be obtained through the company search endpoint.

Usually, the matching will be done in three steps:

  1. create an invoice with just the debtor name (see Create transaction)
  2. search company to provide matches (see Company search)
  3. save the match (see code example in this section)

List transactions

Request

GET /v1/transactions HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/transactions \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B",
      "id": "trns-yQKxbtCg9aTS5JYnsRVA9B",
      "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
      "unique_id": "876987-987uinjojna-I8UH98Jnj",
      "debtor": "co-AgBGknk7D8KixY2ntbJtmT",
      "debtor_name": "",
      "debtor_country": "",
      "debtor_regnum": "",
      "debtor_address": "",
      "creditor": "co-K35WAmVFuSo6SCAPrSNdkP",
      "creditor_name": "",
      "creditor_country": "",
      "creditor_regnum": "",
      "creditor_address": "",
      "status": "pending",
      "pay_method": "bank",
      "net_amount": "10000.00",
      "gross_amount": "12000.00",
      "currency": "GBP",
      "issue_date": "2018-04-25",
      "due_date": "2018-05-21",
      "paid_date": null,
      "number": "AB2018-123",
      "items": [
        {
          "description": "Super ergonomic chairs",
          "quantity": "10.000",
          "unit_price": "1000.00"
        }
      ],
      "source": null,
      "policy": null,
      "quote": null,
      "estimated_quote_price": null,
      "metadata": null,
      "referral_url": "https://sandbox.hokodo.co/?transaction=trns-yQKxbtCg9aTS5JYnsRVA9B&key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "scheduled_payments": [],
      "payments": []
    },
    {
      "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-krF9xKJcjC28mKGV2byJof",
      "id": "trns-krF9xKJcjC28mKGV2byJof",
      "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
      "unique_id": "876987-987uinjojna-I8UH98Jnj",
      "debtor": null,
      "debtor_name": "Debtor Company",
      "debtor_country": "GB",
      "debtor_regnum": "1234567890",
      "debtor_address": "Some existing address",
      "creditor": null,
      "creditor_name": "Creditor Company",
      "creditor_country": "GB",
      "creditor_regnum": "1234567890",
      "creditor_address": "Some existing address",
      "status": "pending",
      "pay_method": "bank",
      "net_amount": "10000.00",
      "gross_amount": "12000.00",
      "currency": "GBP",
      "issue_date": "2018-04-25",
      "due_date": "2018-05-21",
      "paid_date": null,
      "number": "AB2018-123",
      "items": [
        {
          "description": "Super ergonomic chairs",
          "quantity": "10.000",
          "unit_price": "1000.00"
        }
      ],
      "source": null,
      "policy": null,
      "quote": null,
      "estimated_quote_price": null,
      "metadata": null,
      "referral_url": "https://sandbox.hokodo.co/?transaction=trns-krF9xKJcjC28mKGV2byJof&key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "scheduled_payments": [],
      "payments": []
    },
  ]
}

List transactions created by your platform

View transaction

Requests

  • without expanding referenced objects
GET /v1/transactions/<transaction_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/transactions/<transaction_id> \
     --header "Authorization: <your_api_key>"
  • with expanding referenced debtor, creditor, policy and quote objects
GET /v1/transactions/<transaction_id>?expand=debtor,creditor,policy,quote HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/transactions/<transaction_id>?extend=debtor,creditor,policy,quote \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>"

Responses

  • regular response (with expanded debtor, creditor, policy and quote)
200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-dTHo9Q2idffT7CMPCVjztA",
  "id": "trns-dTHo9Q2idffT7CMPCVjztA",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "debtor": {
    "url": "https://api-sandbox.hokodo.co/v1/companies/co-AgBGknk7D8KixY2ntbJtmT",
    "id": "co-AgBGknk7D8KixY2ntbJtmT",
    "country": "GB",
    "name": "Some Existing Debtor",
    "address": "2 Existing Street, London, SE11 6NQ",
    "city": "London",
    "postcode": "SE11 6NQ",
    "legal_form": "Private limited with share capital",
    "sectors": [
      {
        "system": "SIC2007",
        "code": "96090"
      }
    ],
    "creation_date": "1910-10-10",
    "identifiers": [
      {
        "idtype": "reg_number",
        "country": "GB",
        "value": "987654321"
      }
    ],
    "email": "",
    "phone": "",
    "status": "Active",
    "accounts_type": "Full accounts"
  },
  "debtor_name": "",
  "debtor_country": "",
  "debtor_regnum": "",
  "debtor_address": "",
  "creditor": {
    "url": "https://api-sandbox.hokodo.co/v1/companies/co-K35WAmVFuSo6SCAPrSNdkP",
    "id": "co-K35WAmVFuSo6SCAPrSNdkP",
    "country": "GB",
    "name": "Some Existing Creditor",
    "address": "1 Existing Street, London, SW1E 5NN",
    "city": "London",
    "postcode": "SW1E 5NN",
    "legal_form": "Public limited with share capital",
    "sectors": [
      {
        "system": "SIC2007",
        "code": "70100"
      }
    ],
    "creation_date": "1901-01-01",
    "identifiers": [
      {
        "idtype": "reg_number",
        "country": "GB",
        "value": "012345678"
      }
    ],
    "email": "",
    "phone": "",
    "status": "Active",
    "accounts_type": "Group"
  },
  "creditor_name": "",
  "creditor_country": "",
  "creditor_regnum": "",
  "creditor_address": "",
  "status": "pending",
  "pay_method": "bank",
  "net_amount": "10000.00",
  "gross_amount": "12000.00",
  "currency": "GBP",
  "issue_date": "2020-04-25",
  "due_date": "2020-07-21",
  "paid_date": null,
  "number": "AB2018-123",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": "10.000",
      "unit_price": "1000.00"
    }
  ],
  "source": null,
  "policy": {
    "url": "https://api-sandbox.hokodo.co/v1/policies/pol-V3h9nZQWDj9pxXWgkSjq8k",
    "id": "pol-V3h9nZQWDj9pxXWgkSjq8k",
    "number": "T-F9BE-13AF",
    "status": "active",
    "created": "2020-05-25T14:36:04.363353Z",
    "documents": [],
    "collection": null,
    "loss_payee": "Not applicable"
  },
  "quote": {
    "url": "https://api-sandbox.hokodo.co/v1/quotes/quo-YFaytjhqTD6ahBvjZdd5bV",
    "id": "quo-YFaytjhqTD6ahBvjZdd5bV",
    "client": {
      "url": "https://api-sandbox.hokodo.co/v1/companies/co-K35WAmVFuSo6SCAPrSNdkP",
      "id": "co-K35WAmVFuSo6SCAPrSNdkP",
      "country": "GB",
      "name": "John Lewis PLC",
      "address": "171 Victoria Street, London, SW1E 5NN",
      "city": "London",
      "postcode": "SW1E 5NN",
      "legal_form": "Public limited with share capital",
      "sectors": [
        {
          "system": "SIC2007",
          "code": "70100"
        }
      ],
      "creation_date": "1928-09-20",
      "identifiers": [
        {
          "idtype": "reg_number",
          "country": "GB",
          "value": "00233462"
        }
      ],
      "email": "",
      "phone": "",
      "status": "Active",
      "accounts_type": "Group"
    },
    "status": "accepted",
    "proposed_quote": null,
    "rejection_reason": null,
    "created": "2020-05-25T14:17:50.385544Z",
    "valid_until": "2020-05-25T16:17:50.344391Z",
    "currency": "GBP",
    "total_price": "97.75",
    "premium": "87.28",
    "ipt": "10.47",
    "price": {
      "currency": "GBP",
      "total_price": "97.75",
      "total_price_without_discount": "97.75",
      "discount_amount": null,
      "premium": "87.28",
      "ipt": "10.47",
      "discounts": []
    },
    "insured": {
      "currency": "GBP",
      "insured_amount": "9000.00"
    },
    "insured_pc_net": "90.0",
    "insured_pc_gross": null,
    "referral_url": null,
    "payment_required": true
  },
  "estimated_quote_price": null,
  "metadata": null,
  "referral_url": null,
  "scheduled_payments": [],
  "payments": []
}
  • transaction not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Look up a previously created transaction.

Errors

errors description
404 the transaction_id is probably invalid, the transaction has not been found

Modify uninsured transaction

Request (e.g. identify debtor)

PATCH /v1/transactions/<transaction_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "debtor": "co-AgBGknk7D8KixY2ntbJtmT"
}
curl --request PATCH \
     --url https://api-sandbox.hokodo.co/v1/transactions/<transaction_id> \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary "{
    \"debtor\": \"co-4MRXDjtbScBmDzbrTbh9SW\"
}"

Response

200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-krF9xKJcjC28mKGV2byJof",
  "id": "trns-krF9xKJcjC28mKGV2byJof",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "debtor": "co-AgBGknk7D8KixY2ntbJtmT",
  "debtor_name": "Debtor Company",
  "debtor_country": "GB",
  "debtor_regnum": "1234567890",
  "debtor_address": "Some existing address",
  "creditor": null,
  "creditor_name": "Creditor Company",
  "creditor_country": "GB",
  "creditor_regnum": "1234567890",
  "creditor_address": "Some existing address",
  "status": "pending",
  "pay_method": "bank",
  "net_amount": "10000.00",
  "gross_amount": "12000.00",
  "currency": "GBP",
  "issue_date": "2018-04-25",
  "due_date": "2018-05-21",
  "paid_date": null,
  "number": "AB2018-123",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": "10.000",
      "unit_price": "1000.00"
    }
  ],
  "source": null,
  "transaction_key": "tQ9OhMH-uxIvHswdISDce2sfVxpMRX3eEyx2RXs0YV4",
  "estimated_quote_price": null,
  "metadata": null,
  "referral_url": null,
  "scheduled_payments": [],
  "payments": []
}

Partially modify a previously created and not yet insured transaction.

Once a transaction has been insured, only some specific fields can be modified, please use the dedicated endpoint to Modify an already insured transaction and amend the transaction post-sale.

Errors

errors description
400 a required field is missing or some of the fields have incorrect value
409 the transaction is already insured, modification is not allowed

Delete transaction

Request

DELETE /v1/transactions/<transaction_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request DELETE \
     --url https://api-sandbox.hokodo.co/v1/transactions/<transaction_id> \
     --header "Authorization: <your_api_key>"

Responses

  • regular response
204 No Content
  • transaction not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}
  • transaction already insured
409 Conflict
Content-Type: application/json

Delete a previously created transaction.

Errors

errors description
404 the transaction_id is probably invalid, the transaction has not been found
409 the transaction is already insured, deleting is not allowed

Confirm a draft transaction

Request

PUT /v1/transactions/<transaction_id>/confirm HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>
curl --request PATCH \
     --url https://api-sandbox.hokodo.co/v1/transactions/<transaction_id>/paid \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>"

Response

200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-krF9xKJcjC28mKGV2byJof",
  "id": "trns-krF9xKJcjC28mKGV2byJof",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "debtor": "co-AgBGknk7D8KixY2ntbJtmT",
  "debtor_name": "Debtor Company",
  "debtor_country": "GB",
  "debtor_regnum": "1234567890",
  "debtor_address": "Some existing address",
  "creditor": null,
  "creditor_name": "Creditor Company",
  "creditor_country": "GB",
  "creditor_regnum": "1234567890",
  "creditor_address": "Some existing address",
  "status": "paid",
  "pay_method": "bank",
  "net_amount": "10000.00",
  "gross_amount": "12000.00",
  "currency": "GBP",
  "issue_date": "2018-04-25",
  "due_date": "2018-05-21",
  "paid_date": "2018-05-21",
  "number": "AB2018-123",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": "10.000",
      "unit_price": "1000.00"
    }
  ],
  "source": null,
  "policy": null,
  "quote": null,
  "estimated_quote_price": null,
  "metadata": null,
  "referral_url": null,
  "scheduled_payments": [],
  "payments": []
}

This endpoint lets you change the status of a draft transaction from draft to pending. For uninsured transactions, you may use the modify endpoint. This endpoint is particularly relevant for insured draft transactions: it is the only way to update their status.

Errors

errors description
404 the transaction_id is probably invalid, the transaction has not been found
409 the transaction is not in the draft status, modification from this endpoint is not allowed

Mark a transaction as paid

Request

PUT /v1/transactions/<transaction_id>/paid HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "pay_method": "bank",
  "paid_date": "2018-05-21"
}
curl --request PATCH \
     --url https://api-sandbox.hokodo.co/v1/transactions/<transaction_id>/paid \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary "{
    \"pay_method\": \"bank\",
    \"paid_date\": \"2018-05-21\"
}"

Response

200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-krF9xKJcjC28mKGV2byJof",
  "id": "trns-krF9xKJcjC28mKGV2byJof",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "debtor": "co-AgBGknk7D8KixY2ntbJtmT",
  "debtor_name": "Debtor Company",
  "debtor_country": "GB",
  "debtor_regnum": "1234567890",
  "debtor_address": "Some existing address",
  "creditor": null,
  "creditor_name": "Creditor Company",
  "creditor_country": "GB",
  "creditor_regnum": "1234567890",
  "creditor_address": "Some existing address",
  "status": "paid",
  "pay_method": "bank",
  "net_amount": "10000.00",
  "gross_amount": "12000.00",
  "currency": "GBP",
  "issue_date": "2018-04-25",
  "due_date": "2018-05-21",
  "paid_date": "2018-05-21",
  "number": "AB2018-123",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": "10.000",
      "unit_price": "1000.00"
    }
  ],
  "source": null,
  "policy": null,
  "quote": null,
  "estimated_quote_price": null,
  "metadata": null,
  "referral_url": null,
  "scheduled_payments": [],
  "payments": []
}

If your platform is able to know when the invoice has been paid, you should call this endpoint to notify the API.

field type flags description
pay_method string optional Payment method
paid_date date optional Date when the transaction has been paid in full

Errors

errors description
404 the transaction_id is probably invalid, the transaction has not been found

Modify an already insured transaction

Request

PATCH /v1/transactions/<transaction_id>/amend/ HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "net_amount": "1000.00",
  "gross_amount": "1200.00",
  "issue_date": "2021-01-15",
  "due_date": "2021-03-15",
  "scheduled_payments": [
    {"date": "2021-01-15", "amount": "1.00"},
    {"date": "2021-03-15", "amount": "1199.00"},
  ]
}
curl --request PATCH \
     --url https://api-sandbox.hokodo.co/v1/transactions/<transaction_id>/amend/ \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary '{
  "net_amount": "1000.00",
  "gross_amount": "1200.00",
  "issue_date": "2021-01-15",
  "due_date": "2021-03-15",
  "scheduled_payments": [
    {"date": "2021-01-15", "amount": "1.00"},
    {"date": "2021-03-15", "amount": "1199.00"},
  ]
}'

Response

200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-krF9xKJcjC28mKGV2byJof",
  "id": "trns-krF9xKJcjC28mKGV2byJof",
  "owner": "user-mECT3e5n9i7gVGrbn2Pd38",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "debtor": "co-AgBGknk7D8KixY2ntbJtmT",
  "debtor_name": "Debtor Company",
  "debtor_country": "GB",
  "debtor_regnum": "1234567890",
  "debtor_address": "Some existing address",
  "creditor": null,
  "creditor_name": "Creditor Company",
  "creditor_country": "GB",
  "creditor_regnum": "1234567890",
  "creditor_address": "Some existing address",
  "status": "pending",
  "pay_method": "unknown",
  "net_amount": "1000.00",
  "gross_amount": "1200.00",
  "currency": "GBP",
  "issue_date": "2021-01-15",
  "due_date": "2021-03-15",
  "paid_date": null,
  "number": "AB2018-123",
  "items": [],
  "source": null,
  "transaction_key": "tQ9OhMH-uxIvHswdISDce2sfVxpMRX3eEyx2RXs0YV4",
  "estimated_quote_price": null,
  "metadata": null,
  "referral_url": null,
  "scheduled_payments": [
    {"date": "2021-01-15", "amount": "1.00"},
    {"date": "2021-03-15", "amount": "1199.00"},
  ],
  "payments": [
    {"date": "2021-01-13", "amount": "1.00"},
  ]
}

Sometimes, an order on your platform gets modified after the sale. Maybe the customer has returned part of the order, or asked for a refund, or there was a mistake. Maybe the payment schedule has been altered for some reason.

The amendment endpoint allows a limited set of modifications after a transaction has been insured. It can cover the following cases:

It is important to use this in order to maintain proper synchronisation of your database and Hokodo's database, and to minise manual operational load and data exchanges.

field type flags description
net_amount decimal optional Decimal value of the net transaction amount
gross_amount decimal optional Decimal value of the gross transaction amount
issue_date date optional Date of issuance of the transaction
due_date date optional Date due of the transaction
scheduled_payments list optional The list of partial payments, expected according to a defined schedule
scheduled_payments[*][date] string required Payment date
scheduled_payments[*][amount] decimal required Payment amount in transaction currency

Notes

Errors

errors description
400 a required field is missing or some of the fields have incorrect value
409 this modification is not allowed

Transaction partial payments

Sample transaction with 3 installments over 60 days

  "gross_amount": "300.00",
  "issue_date": "2020-01-01",
  "due_date": "2020-03-01",
  "scheduled_payments": [
    {
      "date": "2020-01-01",
      "amount": "100.00",
      "currency": "EUR"
    },
    {
      "date": "2020-02-01",
      "amount": "100.00",
      "currency": "EUR"
    },
    {
      "date": "2020-03-01",
      "amount": "100.00",
      "currency": "EUR"
    }
  ],
  "payments": [
    {
      "date": "2020-01-01",
      "amount": "100.00",
      "currency": "EUR"
    }
  ]

Sample transaction with 30 days payment terms and no initial payment

  "gross_amount": "300.00",
  "issue_date": "2020-01-01",
  "due_date": "2020-03-01",
  "scheduled_payments": [
    {
      "date": "2020-03-01",
      "amount": "300.00",
      "currency": "EUR"
    }
  ],
  "payments": []

A transaction may be paid back in multiple partial payments. If you are using Hokodo insurance to cover transactions on your marketplace or e-commerce platform, to provide payment terms to your buyers, please include the schedule of expected payments with the Transaction and notify us of the partial payments as they arrive. In the event that a payment that you have recorded is subsequently reported to fail or be reversed, please record this as another payment but with a negative amount (see more information below).

You can find 2 examples of the relevant Transaction fields in the code samples in this sub-section:

You can then notify Hokodo of partial payments as they come through, as well as any chargebacks or negative events.

Transaction partial payments endpoints

Transaction partial payment object

{
  "date": "2020-03-01",
  "amount": "300.00",
  "currency": "EUR",
  "type": "settlement",
  "details": "",
  "provider_code": ""
}
field type flags description
date date required Date the scheduled payment is expected or the payment is received
amount decimal required Decimal value of the gross amount of the expected or received payment. Positive for settlements, negative for chargebacks
currency currency optional Currency of the payment amount
type string depends optional for positive amounts (and defaults to settlement), required for negative amounts: chargeback, error, other, or unknown
details string optional free text field containing details about the reason, such as "The bank account has been closed" or "This payment could not be processed"
provider_code string optional rejection code from 3rd party payment provider, for example account_closed, insufficient_funds (Stripe), or 1, B (GoCardless)

Create transaction with partial payments

Requests

POST /v1/transactions HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "owner": "user-nNqgg5AFymQMumaU7EdrLa",
  "debtor": "co-4MRXDjtbScBmDzbrTbh9SW",
  "creditor": "co-7QCHuTN5AJycwX7iw9ofW2",
  "net_amount": 10000,
  "gross_amount": 12000,
  "currency": "GBP",
  "issue_date": "2020-01-01",
  "due_date": "2020-03-01",
  "number": "AB2020-123",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": 10,
      "unit_price": 1000
    }
  ],
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "scheduled_payments": [
    {
      "date": "2020-01-01",
      "amount": "100.00",
      "currency": "EUR"
    },
    {
      "date": "2020-03-01",
      "amount": "11900.00",
      "currency": "EUR"
    }
  ],
  "payments": [
    {
      "date": "2020-01-01",
      "amount": "100.00",
      "currency": "EUR"
    }
  ]
}
curl --request POST \
     --url https://api-sandbox.hokodo.co/v1/transactions \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary '{
  "owner": "user-nNqgg5AFymQMumaU7EdrLa",
  "debtor": "co-4MRXDjtbScBmDzbrTbh9SW",
  "creditor": "co-7QCHuTN5AJycwX7iw9ofW2",
  "net_amount": 10000,
  "gross_amount": 12000,
  "currency": "GBP",
  "issue_date": "2020-01-01",
  "due_date": "2020-03-01",
  "number": "AB2020-123",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": 10,
      "unit_price": 1000
    }
  ],
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "scheduled_payments": [
    {
      "date": "2020-01-01",
      "amount": "100.00",
      "currency": "EUR"
    },
    {
      "date": "2020-03-01",
      "amount": "11900.00",
      "currency": "EUR"
    }
  ],
  "payments": [
    {
      "date": "2020-01-01",
      "amount": "100.00",
      "currency": "EUR"
    }
  ]
}'

Responses

201 Created
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B",
  "id": "trns-yQKxbtCg9aTS5JYnsRVA9B",
  "owner": "user-nNqgg5AFymQMumaU7EdrLa",
  "unique_id": "876987-987uinjojna-I8UH98Jnj",
  "debtor": "co-4MRXDjtbScBmDzbrTbh9SW",
  "debtor_name": "",
  "debtor_country": "",
  "debtor_regnum": "",
  "debtor_address": "",
  "creditor": "co-7QCHuTN5AJycwX7iw9ofW2",
  "creditor_name": "",
  "creditor_country": "",
  "creditor_regnum": "",
  "creditor_address": "",
  "status": "pending",
  "pay_method": "",
  "net_amount": "10000.00",
  "gross_amount": "12000.00",
  "currency": "GBP",
  "issue_date": "2020-01-01",
  "due_date": "2020-03-01",
  "paid_date": null,
  "number": "AB2020-123",
  "items": [
    {
      "description": "Super ergonomic chairs",
      "quantity": 10,
      "unit_price": 1000
    }
  ],
  "source": null,
  "transaction_key": "JqzI0T5W7FFdUODv9vkU2bXOTJyV2kT7-Ku2ESJJKXQ",
  "estimated_quote_price": null,
  "metadata": null,
  "referral_url": "https://sandbox.hokodo.co/?transaction=trns-yQKxbtCg9aTS5JYnsRVA9B&key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scheduled_payments": [
    {
      "date": "2020-01-01",
      "amount": "100.00",
      "currency": "EUR"
    },
    {
      "date": "2020-03-01",
      "amount": "11900.00",
      "currency": "EUR"
    }
  ],
  "payments": [
    {
      "date": "2020-01-01",
      "amount": "100.00",
      "currency": "EUR"
    }
  ]
}
  • error response (example)
400 Bad Request
Content-Type: application/json
{
    "due_date": [
        "If you provide a payment schedule, this field is required."
    ]
}
  • error response (example)
400 Bad Request
Content-Type: application/json
{
    "scheduled_payments": [
        "Scheduled amounts and gross amount are not equal."
    ]
}

Some things to keep in mind when creating a Transaction with scheduled payments (and optionally initial payments):

Errors

errors description
400 a required field is missing or some of the fields have incorrect value

Create a new payment for an existing transaction

Request

  • positive amount (settlement)
POST /v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B/payments/ HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "date": "2021-02-01",
  "amount": "100.00",
  "currency": "EUR"
}
curl --request POST \
     --url https://api-sandbox.hokodo.co/v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B/payments/ \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>"
     --data-binary '{
{
  "date": "2020-02-01",
  "amount": "100.00",
  "currency": "EUR"
}
}'
  • negative amount (failure, chargeback, etc.)
POST /v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B/payments/ HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "date": "2021-02-01",
  "amount": "-100.00",
  "currency": "EUR",
  "type": "error",
  "details": "The bank account has been closed.",
  "provider_code": "account_closed"
}
curl --request POST \
     --url https://api-sandbox.hokodo.co/v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B/payments/ \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>"
     --data-binary '{
{
  "date": "2021-02-01",
  "amount": "-100.00",
  "currency": "EUR",
  "type": "error",
  "details": "The bank account has been closed.",
  "provider_code": "account_closed"
}'

Response

  • positive amount (settlement)
201 OK
Content-Type: application/json
{
  "id": "pmnt-z3j4Se4yEnRaYyvDR8ZXcN",
  "date": "2021-02-01",
  "amount": 100.00,
  "currency": "EUR"
  "type": "settlement",
  "details": "",
  "provider_code": ""
}
  • negative amount (failure, chargeback, etc.)
201 OK
Content-Type: application/json
{
  "id": "pmnt-z3j4Se4yEnRaYyvDR8ZXcN",
  "date": "2021-02-01",
  "amount": "-100.00",
  "currency": "EUR",
  "type": "error",
  "details": "The bank account has been closed.",
  "provider_code": "account_closed"
}

Notify Hokodo of a partial payment linked to a transaction.

field type flags description
date date required Date the scheduled payment is expected or the payment is received
amount decimal required Decimal value of the gross amount of the expected or received payment. Positive for settlements, negative for chargebacks
currency currency optional Currency of the payment amount
type string depends optional for positive amounts (and defaults to settlement), required for negative amounts: chargeback, error, other, or unknown
details string optional free text field containing details about the reason, such as "The bank account has been closed" or "This payment could not be processed"
provider_code string optional rejection code from 3rd party payment provider, for example account_closed, insufficient_funds (Stripe), or 1, B (GoCardless)

If the payment amount is positive, it means the payment is a settlement (the customer / end-user has settled part of the transaction).

If the payment amount is negative, it means money flowed the other way or you have learned a settlement has failed, in which case we ask you to negate that settlement.. Many payment providers only notify of payment errors (eg. "insufficient funds") a few days after having already reported the settlement as having been successful. Or, the customer can dispute the payment and execute a chargeback at any time for weeks following the settlement. In these cases, the type field must be present with one of the values (chargeback, refund, error, unknown), and additional details are expected in the free text fields details and provider_code:

It is expected that if you notify us of a negative payment, a positive payment of the same or greater amount has already happened before.

The fields details and provider_code should be filled with details of the error or chargeback, that you will usually get from the payment provider. You will find some examples below from Stripe and GoCardless.

chargeback

Reversal of payment in case of dispute

type provider_code details
chargeback debit_not_authorized The customer has notified their bank that this payment was unauthorized or there is no mandate held by the paying bank
chargeback 4 Your customer has disputed having been notified of this Direct Debit.
chargeback 7 Your customer has disputed that the amount taken differs from the amount they were notified of.
chargeback Purchases that have been made without the buyer’s knowledge or consent
chargeback Purchases that were paid for but haven’t been received
chargeback Purchases that the buyer has been billed for more than once, purchases that have been billed incorrectly, or refunds that haven’t been issued

error

Reversal of payment because of payment failure or various errors

type provider_code details
error account_closed The bank account has been closed.
error bank_ownership_changed The account has been transferred to a new Payment Service Provider (PSP). Check if you have been notified of the new PSP’s details. If not, you must collect a new mandate from the customer.
error invalid_account_number The account number is not valid. This could mean it is not for a GBP account or that the account cannot process Direct Debit payments.
error insufficient_funds The customer’s account has insufficient funds to cover this payment.
error generic_could_not_process This payment could not be processed.
error 0 The payer's bank wasn't in a position to pay the Direct Debit. Generally this is due to insufficient funds. You should contact your customer and arrange to re-try taking the payment.
error 3 Your customer's DDI has been transferred to a new bank account, and you submitted payment to the old account.
error B Your customer's DDI has been cancelled as they've closed their bank account.
error 5 The paying bank didn't recognise the account number you submitted. It's likely that no DDI is set up.
error 2 Your customer's DDI will also have been cancelled.
error 6 Your customer doesn't have a DDI set up with you. In rare cases, this may be due to a small bank requiring additional time to set up a Direct Debit.
error 1 You tried to collect payment against a cancelled DDI.
error 8 Usually caused by submission of a payment before a DDI is fully set up (less than 2 working days after submission). This may also be raised if you attempt to take a payment before the date your customer was notified of.
error 9 You attempted to collect a payment more than 3 working days after the date you notified your customer of.
error A Your details don't match the details on the customer's DDI.

unknown

For an error/dispute, in case you don't have access to the details. It is still important for us to be informed of the negative payment event even if you can't provide the extra information.

type provider_code details
unknown

refund

Return of cash as a result of product return or order modification. For a refund event you might have no information to fill in the details or provider_code fields, but we would welcome any additional data that you provide.

type provider_code details
refund Order amount decreased and extra payment returned to the customer

List transaction payments

Request

POST /v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B/payments/ HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/transactions/trns-yQKxbtCg9aTS5JYnsRVA9B/payments/ \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>"

Response

200 OK
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "pmnt-z3j4Se4yEnRaYyvDR8ZXcN",
      "date": "2020-01-01",
      "amount": "100.00",
      "currency": "EUR"
    }
  ]
}

List partial payments linked to a transaction

Quotes

These resources allow you to request a quote, an offer for an insurance policy. They require having a transaction created, owned by a user or an organisation from your platform.

If the client company, or any of the creditor and the debtor of the transaction are not identified, the API will try to find a close match to propose a quote. The quote might be incorrect if companies are not correctly identified.

In most cases, the client company will be the same as the creditor company and as such it can be omitted from the request.

A transaction can only have one valid quote at a time: any new quote request makes previous ones expired. A quote can be accepted and paid for to obtain a proper policy. Editing the transaction makes any outstanding quote offer expired. A new quote must be requested.

Note that after a quote has been offered, the client is not insured yet. The quote must be accepted, and the price of the insurance paid before the insurance takes effect.

Quotes endpoints

Quote object

{
  "url": "https://api-sandbox.hokodo.co/v1/quotes/quo-EzH6BixNSHvaByEpXcFW5h",
  "id": "quo-EzH6BixNSHvaByEpXcFW5h",
  "transaction": "trns-dTHo9Q2idffT7CMPCVjztA",
  "client": "co-K35WAmVFuSo6SCAPrSNdkP",
  "status": "offered",
  "payment_required": true,
  "created": "2020-05-25T11:37:56.821701Z",
  "valid_until": "2020-05-25T13:37:56.764518Z",
  "policy": null,
  "referral_url": "https://sandbox.hokodo.co/#/?quote=quo-EzH6BixNSHvaByEpXcFW5h&transaction=trns-dTHo9Q2idffT7CMPCVjztA&key=xnwLGPAMu0q5R2mIG80s7q-OQsVk5YBNr60ifNSoyLQ",
  "insured": {
    "currency": "GBP",
    "insured_amount": "9000.00"
  },
  "insured_pc_net": 90,
  "insured_pc_gross": null
  "rejection_reason": null,
  "currency": "GBP",
  "total_price": "97.75",
  "ipt": "10.47",
  "premium": "87.28",
  "price": {
    "currency": "GBP",
    "total_price": "97.75",
    "ipt": "10.47",
    "premium": "87.28",
    "total_price_without_discount": "97.75",
    "discount_amount": null,
    "discounts": []
  },
  "proposed_quote": null,
}
field type description
url string API endpoint to access the quote
id string(uuid) API identifier of the quote
transaction string(uuid) API identifier of the transaction
client string(uuid) API identifier of the company requesting an insurance quote
status string Status of the quote, see Quote status
payment_required boolean True if payment is required for the quote to be accepted (can be False if eg. discount makes the quote free)
created datetime Date of quote request
valid_until datetime Validity limit if offered
policy string API identifier of the policy if the quote is accepted (always null at creation)
referral_url string A URL for referring the customer to Hokodo Quote&Buy website, see Referral URL
insured dictionary Components of the insured amount
insured[currency] currency Currency of the insured amount
insured[insured_amount] decimal Net amount that will be insured if quote is accepted
insured_pc_net decimal Percentage of net invoice value covered by policy when relevant
insured_pc_gross decimal Percentage of gross invoice value covered by policy when relevant
rejection_reason dictionary Rejection reason if quote is declined, see Rejection reasons
rejection_reason[code] string A text label identifying the reason
rejection_reason[detail] string A sentence in client language that can be shown to a user
rejection_reason[params] dictionary A dictionary of dynamic key-value pairs used to build the "detail" string
currency string Currency for all price amounts
total_price decimal Price that would be charged to the customer (including taxes)
ipt decimal Insurance tax
premium decimal Premium part of the amount charged to the customer (net of IPT, before deducting payment fees)
price dictionary Components of the policy price with currency
price[currency] currency Currency for all price amounts
price[total_price] decimal Price that would be charged to the customer (including taxes)
price[ipt] decimal Insurance tax
price[premium] decimal Premium part of the amount charged to the customer (net of IPT, before deducting payment fees)
price[total_price_without_discount] decimal Price that would be charged to the customer before discounts
price[discount_amount] decimal Total amount of discounts applicable to the quote
price[discounts] list List of discounts applicable to the quote
price[discounts][*][type] string Type of the discount (currently only "credits")
price[discounts][*][reason] string Reason for applying the discount, ready to be shown to the user
price[discounts][*][discount_amount] decimal Amount of the discount
price[discounts][*][remaining_credits_amount_after] decimal Amount of remaining credits once a policy for this quote is bought
price[discounts][*][remaining_credits_amount_after_currency] currency Currency of remaining amount
proposed_quote dictionary If a quote is declined a proposed alternative quote may be provided (eg. when transaction amount is too large), see Proposed quote
proposed_quote[price] dictionary See price object above
proposed_quote[insured] dictionary See insured object above
proposed_quote[insured_pc_net] decimal Percentage of net invoice value covered by policy when relevant
proposed_quote[insured_pc_gross] decimal Percentage of gross invoice value covered by policy when relevant

Some price fields are duplicated in the "root" level and in the price dictionary.

Quote status

Note that after an offer has been made, the client is not insured yet. The offer must be accepted, and the price of the insurance paid before the insurance takes effect.

The quote status is one of:

Rejection reason

The rejection code, params and detail can be one of the following:

code params (keys) detail
seller-country creditor_country We're not currently able to insure Sellers domiciled in {creditor_country}.
seller-profile At this stage we are not able to insure sellers fitting your profile.
seller-status creditor_status The status of the Seller on this invoice is registered as being {creditor_status} and so we cannot offer insurance.
seller-accounts creditor_accounts_type We are not currently able to insure Sellers where the Seller's accounts have the status {creditor_accounts_type}.
seller-country-subdivision public_subdivision We are not currently able to insure Sellers in this location: {public_subdivision}.
seller-too-young MIN_CREATION_YEARS We're not able to insure Sellers who incorporated fewer than {MIN_CREATION_YEARS} years ago.
seller-accounts-overdue MAX_ACCOUNTS_OVERDUE_MONTHS We're not currently able to insure Sellers when their accounts are overdue by more than {MAX_ACCOUNTS_OVERDUE_MONTHS} months.
seller-accounts-too-old MAX_AGE_LATEST_FINANCIALS We're not currently able to insure you because your accounts are too old: they were published more than {MAX_AGE_LATEST_FINANCIALS} days ago.
seller-invoices-overdue We're unable to provide a quote because you have too many overdue invoices.
seller-too-young-on-platform platform_name, customer_min_registration_days Invoice Protection is only available for users who have been registered on {platform_name} for at least {customer_min_registration_days} days.
seller-sector We're not presently able to offer insurance to companies in the sector you are registered as operating in.
seller-company-type legal_form We don't presently offer insurance to companies that are incorporated as {legal_form}.
seller-limit This invoice would exceed the limit of the value of invoices that Hokodo can insure for your company as a Seller.
buyer-too-young MIN_CREATION_YEARS We're not presently able to insure Buyer companies which incorporated fewer than {MIN_CREATION_YEARS} years ago.
buyer-country debtor_country We're not currently able to insure Buyers domiciled in {debtor_country}.
buyer-profile At this stage, we are not able to insure buyers fitting this profile.
buyer-status debtor_status The status of the Buyer on this invoice is registered as being "{debtor_status}" and so we cannot offer insurance.
buyer-company-type legal_form We don't presently insure invoices to companies that are incorporated as {legal_form}.
buyer-overdue-with-seller OVERDUE_DAYS The Buyer on this invoice has a {OVERDUE_DAYS}+ days overdue invoice with the Seller, so we're not able to insure at present.
buyer-accounts accounts_type We are not currently able to insure Buyers where the Buyer's accounts have the status {accounts_type}.
buyer-accounts-overdue MAX_ACCOUNTS_OVERDUE_MONTHS We're not currently able to insure Buyers when their accounts are overdue by more than {MAX_ACCOUNTS_OVERDUE_MONTHS} months.
buyer-accounts-too-old MAX_AGE_LATEST_FINANCIALS We're not currently able to insure against Buyers whose accounts are too old: this Buyers accounts were published more than {MAX_AGE_LATEST_FINANCIALS} days ago.
buyer-country-subdivision public_subdivision We are not currently able to insure Buyers in this location: {public_subdivision}.
buyer-size company_size Hokodo is not presently able to insure companies of the size: {company_size}.
buyer-pre-approved platform_name This buyer has not been pre-approved for Hokodo's insurance via {platform_name}
buyer-limit This invoice would exceed the limit of the value of invoices that Hokodo can insure for this company as a Buyer.
buyer-no-financials The buyer on this invoice hasn't published any financials yet or doesn't have any assets.
buyer-uncreditworthy We are unable to verify the creditworthiness of the buyer on this invoice.
buyer-high-risk We are unable to insure this buyer due their high risk profile.
buyer-high-risk-long-term max_term We are unable to insure for this duration due to the buyer's high risk profile. We can insure durations up to {max_term}.
buyer-sector We don't cover invoices against buyer operating in this sector.
buyer-risk-appetite tx_currency, debtor_risk_appetite It's only possible for us to cover invoices up to a value of {tx_currency} {debtor_risk_appetite} at the moment, and your request for cover would cause us to exceed that limit.
common-parent The Buyer and Seller companies on this invoice appear to be related and so we cannot offer insurance.
connected-companies The Buyer and Seller companies on this invoice appear to be related and so we cannot offer insurance.
invoice-currency tx_currency We don't currently insure invoices in the currency {tx_currency}.
invoice-too-early future_dated_limit_days At the moment, we can only insure invoices issued up to {future_dated_limit_days} days into the future.
invoice-too-late today, tx_due_date Today ({today}) is too close to, or past, the due date of the invoice ({tx_due_date}) for us to insure.
invoice-too-large website_email Due to the size of this invoice, please contact {website_email} and we may be able to cover it manually.
invoice-profile We are not able to insure any further invoices of this profile at this time.
invoice-remaining-terms credit_terms_days This invoice's remaining credit terms are {credit_terms_days} days, which is longer than the maximum we're presently able to insure.
invoice-credit-terms credit_terms_days, MAX_CREDIT_TERMS_DAYS This invoice's credit terms are {credit_terms_days} days. At the moment, we can only insure a maximum credit term of {MAX_CREDIT_TERMS_DAYS} days.
sector-accum-limit We are not able to insure any further invoices in the sector that either the buyer or seller is registered as operating in.

Proposed quote

An example for the proposed_quote field where a proposal is made for invoice protection of 20,000 GBP:

"proposed_quote": {
    "price": {
      "total_price": "147.78",
      "premium": "131.95",
      "ipt": "15.83"
    },
    "insured": {
      "currency": "GBP",
      "insured_amount": "20000.00"
    },
    "insured_pc_net": 50.15432098765432,
    "insured_pc_gross": null
}

The proposed_quote field is either null or contains a proposed quote in situations where the only reason for declining the quote is that the invoice was too large. In this case a response will be returned with a proposal for how much of the invoice can be insured.

Referral URL

The referral URL includes a secret key that allows limited access to transaction upon which the quote is based. The link allows a customer with just the link (no login/password required) to confirm the details of the transaction and purchase insurance.

Request a new quote

Request

POST /v1/quotes HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "transaction": "trns-dTHo9Q2idffT7CMPCVjztA"
}
curl --request POST \
     --url https://api-sandbox.hokodo.co/v1/quotes \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary "{
    \"transaction\": \"trns-dTHo9Q2idffT7CMPCVjztA\"
}"

Responses

  • quote offered
201 Created
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/quotes/quo-EzH6BixNSHvaByEpXcFW5h",
  "id": "quo-EzH6BixNSHvaByEpXcFW5h",
  "transaction": "trns-dTHo9Q2idffT7CMPCVjztA",
  "client": "co-K35WAmVFuSo6SCAPrSNdkP",
  "status": "offered",
  "proposed_quote": null,
  "rejection_reason": null,
  "created": "2020-05-25T11:37:56.821701Z",
  "valid_until": "2020-05-25T13:37:56.764518Z",
  "currency": "GBP",
  "total_price": "97.75",
  "premium": "87.28",
  "ipt": "10.47",
  "price": {
    "currency": "GBP",
    "total_price": "97.75",
    "total_price_without_discount": "97.75",
    "discount_amount": null,
    "premium": "87.28",
    "ipt": "10.47",
    "discounts": []
  },
  "insured": {
    "currency": "GBP",
    "insured_amount": "9000.00"
  },
  "insured_pc_net": 90,
  "insured_pc_gross": null,
  "policy": null,
  "referral_url": "https://sandbox.hokodo.co/#/?quote=quo-EzH6BixNSHvaByEpXcFW5h&transaction=trns-dTHo9Q2idffT7CMPCVjztA&key=xnwLGPAMu0q5R2mIG80s7q-OQsVk5YBNr60ifNSoyLQ",
  "payment_required": true
}
  • quote rejected
201 Created
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/quotes/quo-3VezfMFGKX6U247jRhXAkQ",
  "id": "quo-3VezfMFGKX6U247jRhXAkQ",
  "transaction": "trns-yQKxbtCg9aTS5JYnsRVA9B",
  "client": "co-K35WAmVFuSo6SCAPrSNdkP",
  "status": "declined",
  "proposed_quote": null,
  "rejection_reason": {
    "code": "invoice-too-late",
    "detail": "Today (2020-05-25) is too close to, or past, the due date of the invoice (2018-05-21) for us to insure.",
    "params": {
      "today": "2020-05-25",
      "tx_due_date": "2018-05-21"
    }
  },
  "created": "2020-05-25T10:12:35.239884Z",
  "valid_until": "2025-05-24T10:12:35.212006Z",
  "currency": "",
  "total_price": null,
  "premium": null,
  "ipt": null,
  "price": null,
  "insured": {
    "currency": "GBP",
    "insured_amount": "9000.00"
  },
  "insured_pc_net": 90,
  "insured_pc_gross": null,
  "policy": null,
  "referral_url": null,
  "payment_required": false
}

This endpoint is used to obtain a quote to insure a transaction. The only required field is transaction. client is optional and will default to the transaction's debtor company. If you want the client to be different, the preferred way is to provide the client's API unique identifier in the client field. However, you may use client_country in conjunction with client_name and / or client_regnum.

If the quote's client, the transaction's debtor or the transaction's creditor are null, they will internally be matched to companies. The user must be offered the opportunity to review the result of this matching before accepting and paying for the insurance.

field type flags description
transaction string(uuid) required API unique identifier of the transaction
client string(uuid) preferred API unique identifier of the insured company
client_name string optional Name of the insured company
client_country country optional Country of the insured company
client_regnum string optional Registration number of the insured company
client_address string optional Address of the insured company

Errors

errors description
400 a required field is missing
409 can't obtain a quote as transaction is already insured

List quotes

Request

GET /v1/quotes HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/quotes \
     --header "Authorization: <your_api_key>"
}"

Response

200 Ok
Content-Type: application/json
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "url": "https://api-sandbox.hokodo.co/v1/quotes/quo-EzH6BixNSHvaByEpXcFW5h",
      "id": "quo-EzH6BixNSHvaByEpXcFW5h",
      "transaction": "trns-dTHo9Q2idffT7CMPCVjztA",
      "client": "co-K35WAmVFuSo6SCAPrSNdkP",
      "status": "offered",
      "proposed_quote": null,
      "rejection_reason": null,
      "created": "2020-05-25T11:37:56.821701Z",
      "valid_until": "2020-05-25T13:37:56.764518Z",
      "currency": "GBP",
      "total_price": "97.75",
      "premium": "87.28",
      "ipt": "10.47",
      "price": {
        "currency": "GBP",
        "total_price": "97.75",
        "total_price_without_discount": "97.75",
        "discount_amount": null,
        "premium": "87.28",
        "ipt": "10.47",
        "discounts": []
      },
      "insured": {
        "currency": "GBP",
        "insured_amount": "9000.00"
      },
      "insured_pc_net": "90.0",
      "insured_pc_gross": null,
      "policy": null,
      "referral_url": "https://sandbox.hokodo.co/#/?quote=quo-EzH6BixNSHvaByEpXcFW5h&transaction=trns-dTHo9Q2idffT7CMPCVjztA&key=xnwLGPAMu0q5R2mIG80s7q-OQsVk5YBNr60ifNSoyLQ",
      "payment_required": true
    },
    {
      "url": "https://api-sandbox.hokodo.co/v1/quotes/quo-3VezfMFGKX6U247jRhXAkQ",
      "id": "quo-3VezfMFGKX6U247jRhXAkQ",
      "transaction": "trns-yQKxbtCg9aTS5JYnsRVA9B",
      "client": "co-K35WAmVFuSo6SCAPrSNdkP",
      "status": "declined",
      "proposed_quote": null,
      "rejection_reason": {
        "code": "invoice-too-late",
        "detail": "Today (2020-05-25) is too close to, or past, the due date of the invoice (2018-05-21) for us to insure.",
        "params": {
          "today": "2020-05-25",
          "tx_due_date": "2018-05-21"
        }
      },
      "created": "2020-05-25T10:12:35.239884Z",
      "valid_until": "2025-05-24T10:12:35.212006Z",
      "currency": "",
      "total_price": null,
      "premium": null,
      "ipt": null,
      "price": null,
      "insured": {
        "currency": "GBP",
        "insured_amount": "9000.00"
      },
      "insured_pc_net": 90,
      "insured_pc_gross": null,
      "policy": null,
      "referral_url": null,
      "payment_required": false
    }
  ]
}

List all previously requested quotes

View quote

Request

GET /v1/quotes/<quote_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/quotes/<quote_id> \
     --header "Authorization: <your_api_key>"
}"

Responses

  • regular response
200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/quotes/quo-EzH6BixNSHvaByEpXcFW5h",
  "id": "quo-EzH6BixNSHvaByEpXcFW5h",
  "transaction": "trns-dTHo9Q2idffT7CMPCVjztA",
  "client": "co-K35WAmVFuSo6SCAPrSNdkP",
  "status": "offered",
  "proposed_quote": null,
  "rejection_reason": null,
  "created": "2020-05-25T11:37:56.821701Z",
  "valid_until": "2020-05-25T13:37:56.764518Z",
  "currency": "GBP",
  "total_price": "97.75",
  "premium": "87.28",
  "ipt": "10.47",
  "price": {
    "currency": "GBP",
    "total_price": "97.75",
    "total_price_without_discount": "97.75",
    "discount_amount": null,
    "premium": "87.28",
    "ipt": "10.47",
    "discounts": []
  },
  "insured": {
    "currency": "GBP",
    "insured_amount": "9000.00"
  },
  "insured_pc_net": "90.0",
  "insured_pc_gross": null,
  "policy": null,
  "referral_url": "https://sandbox.hokodo.co/#/?quote=quo-EzH6BixNSHvaByEpXcFW5h&transaction=trns-dTHo9Q2idffT7CMPCVjztA&key=xnwLGPAMu0q5R2mIG80s7q-OQsVk5YBNr60ifNSoyLQ",
  "payment_required": true
}
  • not found http-doc 404 Not Found Content-Type: application/json json-doc { "detail": "Not found." }

Retrieve a previously requested quote

Errors

errors description
404 the quote id is probably incorrect, a quote has not been found

Delete quote

Request

DELETE /v1/quotes/<quote_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request DELETE \
     --url https://api-sandbox.hokodo.co/v1/quotes/<quote_id> \
     --header "Authorization: <your_api_key>"
}"

Responses

  • regular response
204 No Content
  • not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}
  • unable to delete accepted quote
409 Conflict
Content-Type: application/json

Delete a previously requested quote

Errors

errors description
404 the quote id is probably incorrect, a quote has not been found
409 can't delete the quote, probably because it's already been accepted

Policies

To accept a quote and initiate actual insurance, create a Policy.

If you refer your customers to our quote and payment page, we will take care of this part. Otherwise, you can use our API to do it.

Note: A policy cannot be deleted or modified through API.

Policies endpoints

Policy object

{
  "url": "https://api-sandbox.hokodo.co/v1/policies/pol-V3h9nZQWDj9pxXWgkSjq8k",
  "id": "pol-V3h9nZQWDj9pxXWgkSjq8k",
  "number": "T-F9BE-13AF",
  "quote": "quo-YFaytjhqTD6ahBvjZdd5bV",
  "status": "active",
  "created": "2020-05-25T14:36:04.363353Z",
  "documents": [],
  "collection": null,
  "loss_payee": "Not applicable"
}
field type description
url string API endpoint to access the policy
id string(uuid) API identifier of the policy
number string Public identifier of the policy
quote string(uuid) API identifier of the related quote
status string Status of the policy, see below
created datetime Date of creation of the policy
documents list List of documents attached to the policy, see below
documents[*][category] string Category of the document
documents[*][url] string URL to download the document
collection string Identifier of a collection resource (available after collection is initiated)
loss_payee string Name of the company that will be loss payee (not always applicable)

Policy status

The policy status is one of:

If your platform is able to know when the invoice has been paid, you should call endpoint /transactions/<transaction_id>/paid to notify the API.

Policy documents

After a policy insurance has been accepted, the client can retrieve the policy documents, using links provided in the documents section of the policy object

Documents are available in PDF format and may contain:

Create policy

Request

POST /v1/policies HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "quote": "quo-EzH6BixNSHvaByEpXcFW5h",
  "stripe_id: "tok_1DRHM2KvLUV9XNYvo4vNGeDi"
}
curl --request POST \
     --url https://api-sandbox.hokodo.co/v1/quotes \
     --header "Content-Type: application/json" \
     --header "Authorization: <your_api_key>" \
     --data-binary "{
    \"quote\": \"trns-dTHo9Q2idffT7CMPCVjztA\",
    \"stripe_id\": \"tok_1DRHM2KvLUV9XNYvo4vNGeDi\"
}"

Responses

  • regular response
201 Created
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/policies/pol-V3h9nZQWDj9pxXWgkSjq8k",
  "id": "pol-V3h9nZQWDj9pxXWgkSjq8k",
  "number": "T-F9BE-13AF",
  "quote": "quo-YFaytjhqTD6ahBvjZdd5bV",
  "status": "active",
  "created": "2020-05-25T14:36:04.363353Z",
  "documents": [],
  "collection": null,
  "loss_payee": "Not applicable"
}
  • error response (payment information not provided)
400 Bad Request
Content-Type: application/json
{
  "non_field_errors": [
    "Invalid payment information."
  ]
}
  • error response (invalid StripeID type)
400 Bad Request
Content-Type: application/json
{
  "detail": "Attempted to purchase a policy with an invalid stripe_id type: invalid.stripe_id must be a valid PaymentMethod, Source or Token."
}
  • error response (quote expired)
400 Bad Request
Content-Type: application/json
{
  "quote": [
    "Quote is expired."
  ]
}
  • error response (quote already accepted)
400 Bad Request
Content-Type: application/json
{
  "quote": [
    "Quote is already accepted."
  ]
}
  • payment failed
402 Payment Required
Content-Type: application/json
{
  "detail": "Payment failed."
}

This endpoint is used to obtain a policy from a quote. The quote needs to be accepted, and valid payment details should be provided for the total amount requested. The quote must have been offered and still be valid at the time of the call.

Payment is made using Stripe API. A valid Stripe Token or Source should be used so that it can be charged by backend. Please refer to Stripe API documentation for how to obtain a Source or a Token identifier. Never send raw bank or payment information through this endpoint (no bank account, no card number).

Once a policy has been created without error, the insurance takes effect, providing that all information collected is correct.

field type flags description
quote string(uuid) required API unique identifier of the quote
stripe_id string required Valid Stripe Token or Source

Errors

errors description
400 required field is missing or quote has expired or was accepted
402 payment failed
502 payment processor responded with a system error
504 timeout happened when accessing payment provider

List policies

Request

GET /v1/policies HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/policies \
     --header "Authorization: <your_api_key>"
}"

Response

200 Ok
Content-Type: application/json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "url": "https://api-sandbox.hokodo.co/v1/policies/pol-V3h9nZQWDj9pxXWgkSjq8k",
      "id": "pol-V3h9nZQWDj9pxXWgkSjq8k",
      "number": "T-F9BE-13AF",
      "quote": "quo-YFaytjhqTD6ahBvjZdd5bV",
      "status": "active",
      "created": "2020-05-25T14:36:04.363353Z",
      "documents": [],
      "collection": null,
      "loss_payee": "Not applicable"
    }
  ]
}

List all previously created policies

View policy

Request

GET /v1/policies/<policy_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET \
     --url https://api-sandbox.hokodo.co/v1/policies/<policy_id> \
     --header "Authorization: <your_api_key>"
}"

Responses

  • regular response
200 Ok
Content-Type: application/json
{
  "url": "https://api-sandbox.hokodo.co/v1/policies/pol-V3h9nZQWDj9pxXWgkSjq8k",
  "id": "pol-V3h9nZQWDj9pxXWgkSjq8k",
  "number": "T-F9BE-13AF",
  "quote": "quo-YFaytjhqTD6ahBvjZdd5bV",
  "status": "active",
  "created": "2020-05-25T14:36:04.363353Z",
  "documents": [],
  "collection": null,
  "loss_payee": "Not applicable"
}
  • not found
404 Not Found
Content-Type: application/json
{
  "detail": "Not found."
}

Retrieve a previously created policy

Errors

errors description
404 the policy id is probably incorrect, a policy has not been found

Collections and claims

If an insured invoice doesn't get paid past a certain date, the user can hand it over to Hokodo. We will then try to collect, and if that is unsuccessful pay a claim.

To hand over an unpaid invoice to collections, you create a Collection object, attached to a Policy. Collections are identified by a unique, random ID.

The collection object will be pre-filled with known information about the creditor and the debtor. That information can still be modified by the customer, for example to indicate the address of the proper branch of the debtor company to contact, or the right contact person.

Some documents must be attached to the collection request, for example a copy of the original invoice. To do so, create a CollectionDocument object.

Once a Collection object is created and attached to a policy, it cannot be attached to a different policy.

Once a collection request has been sent, the object cannot be modified anymore (this rule may be relaxed in the future) and documents attached to it cannot be deleted through the API.

Collection endpoints

Collections:

Collection documents:

Collection object

{
    "id": "coll-TWyj6XFLYfCnw95KgBhHDf",
    "policy": "pol-WwX8y7hKWyje2ttm6nAbvU",
    "created": "2019-06-18T10:56:05.933635Z",
    "modified": "2019-06-26T08:42:34.254546Z",
    "sent": "2019-06-26T08:42:33.069006Z",
    "confirm_correct": true,
    "confirmed_correct": "2019-06-26T08:42:32.388611Z",
    "collections_terms_acceptance": true,
    "accepted_collections_terms": "2019-06-26T08:42:32.388621Z",
    "collect_fees_from_debtor": true,
    "creditor_contact_name": "This Is Me",
    "creditor_contact_email": "realuser@usercompany.com",
    "creditor_contact_phone": "+441234567890",
    "debtor_address": "1 Bad Payer Street, London, E2 8AA",
    "debtor_postcode": "E2 8AA",
    "debtor_city": "London",
    "debtor_country": "GB",
    "debtor_contact_name": "Mean Buyer",
    "debtor_contact_email": "mean@buyer.com",
    "debtor_contact_phone": "+440987654321",
    "debtor_website": "",
    "bank_account_name": "User Company",
    "bank_account_sortcode": "12-10-24",
    "bank_account_number": "80804040",
    "bank_account_email": "accounts@usercompany.com",
    "actions_taken": "",
    "partial_payment": "0.00",
    "disputed": false,
    "other_invoices": false,
    "reasons": "",
    "comments": ""
}
field type flags description
id string(uuid) read-only API identifier of the collection
policy string(uuid) required API identifier of the linked policy
created datetime read-only Created time
modified datetime read-only Last modified time
sent datetime read-only Timestamp at which the collection request has been sent
confirm_correct boolean optional Customer has confirmed the information is correct (Cannot be set at creation)
confirmed_correct datetime read-only Timestamp of confirm_correct true
collections_terms_acceptance boolean optional Customer has accepted the collections terms and conditions (Cannot be set at creation)
accepted_collections_terms datetime read-only Timestamp of collections_terms_acceptance true
collect_fees_from_debtor boolean optional Should the collection fees be collected from debtor?
creditor_contact_name string optional Creditor contact name (defaults to the user's name)
creditor_contact_email string(email) optional Creditor contact email address (defaults to the user's email address)
creditor_contact_phone string optional Creditor contact phone number (defaults to the user's phone if available)
debtor_address string optional Debtor address
debtor_postcode string optional Debtor postal/zip code
debtor_city string optional Debtor city
debtor_country country optional Debtor country (ISO 3166-1 2 letter code)
debtor_contact_name string optional Debtor contact name
debtor_contact_email string(email) optional Debtor contact email address
debtor_contact_phone string optional Debtor contact phone number
debtor_website string optional Debtor website
bank_account_name string optional Name on the bank account
bank_account_sortcode string optional Bank account sortcode
bank_account_number string optional Bank account number
bank_account_email string(email) optional Email address of person checking the bank account
actions_taken string optional Actions already taken by the creditor
partial_payment decimal optional Partial payment received (defaults to 0)
disputed boolean optional Is the invoice disputed by the debtor? (defaults to false)
other_invoices boolean optional Are there other outstanding invoices with this debtor? (defaults to false)
reasons string optional Non-payment reasons if known
comments string optional Other comments and instructions

Create a collection

Request

POST /v1/collections HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key>

{
  "policy": "pol-WwX8y7hKWyje2ttm6nAbvU"
}
curl --request POST 
  --url https://api-sandbox.hokodo.co/v1/collections/ \
  --header 'Authorization: Token <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data-binary "{
    \"policy\": \"pol-WwX8y7hKWyje2ttm6nAbvU\"
}"

Response

  • regular response
201 Created
Content-Type: application/json
{
  "id": "coll-e8rkfpHNMyCoaL6MNab8sP",
  "created": "2020-05-28T13:47:05.086201Z",
  "modified": "2020-05-28T13:47:05.120969Z",
  "sent": null,
  "creditor_contact_name": "",
  "creditor_contact_email": "johnny@hokodo.co",
  "creditor_contact_phone": "",
  "debtor_address": "1 Some Street, London, SE11 6NQ",
  "debtor_postcode": "SE11 6NQ",
  "debtor_city": "London",
  "debtor_country": "GB",
  "debtor_contact_name": "",
  "debtor_contact_email": "",
  "debtor_contact_phone": "",
  "debtor_website": "",
  "actions_taken": "",
  "partial_payment": "0.00",
  "disputed": false,
  "other_invoices": false,
  "reasons": "",
  "comments": "",
  "bank_account_name": "Some Company LLC",
  "bank_account_sortcode": "",
  "bank_account_number": "",
  "bank_account_email": "johnny@hokodo.co",
  "confirmed_correct": null,
  "accepted_collections_terms": null,
  "collect_fees_from_debtor": null,
  "policy": "pol-bX9R96pziJSs6774VkpmCR"
}
  • error response (incorrect policy status)
409 Conflict
Content-Type: application/json
{
  "detail": "Collection request not available in this policy status"
}

To create a collection request, you create a Collection object attached to the Policy of the unpaid invoice.

A Policy has to be in the state late_can_handover for a collection request to be possible. The policy reaches that state automatically depending on the due date and the terms of the insurance (how soon can a customer hand over the invoice after the due date). Trying to start or modify a collection request in another state will result in an HTTP 409 error in the response.

Organisation, which owns the invoice, must have at least one admin user to create collection requests.

Errors

errors description
400 a required field is missing or some of the fields have incorrect value
409 current policy status does not allow creation of collection requests

View collection

Request

GET /v1/collections/<collection_id> HTTP/1.1
Authorization: Token <your_api_key>
curl --request GET 
  --url https://api-sandbox.hokodo.co/v1/collections/ \
  --header 'Authorization: Token <your_api_key>'

Response

200 Ok
Content-Type: application/json
{
  "id": "coll-e8rkfpHNMyCoaL6MNab8sP",
  "created": "2020-05-28T13:47:05.086201Z",
  "modified": "2020-05-28T13:47:05.120969Z",
  "sent": null,
  "creditor_contact_name": "",
  "creditor_contact_email": "johnny@hokodo.co",
  "creditor_contact_phone": "",
  "debtor_address": "1 Some Street, London, SE11 6NQ",
  "debtor_postcode": "SE11 6NQ",
  "debtor_city": "London",
  "debtor_country": "GB",
  "debtor_contact_name": "",
  "debtor_contact_email": "",
  "debtor_contact_phone": "",
  "debtor_website": "",
  "actions_taken": "",
  "partial_payment": "0.00",
  "disputed": false,
  "other_invoices": false,
  "reasons": "",
  "comments": "",
  "bank_account_name": "Some Company LLC",
  "bank_account_sortcode": "",
  "bank_account_number": "",
  "bank_account_email": "johnny@hokodo.co",
  "confirmed_correct": null,
  "accepted_collections_terms": null,
  "collect_fees_from_debtor": null,
  "policy": "pol-bX9R96pziJSs6774VkpmCR"
}

Retrieve a single previously created collection request.

Errors

errors description
404 the collection_id is probably invalid, the collection has not been found

Update collection request

Request

PATCH /v1/collections/<collection_id> HTTP/1.1
Content-Type: application/json
Authorization: Token <your_api_key> 

{
  "creditor_contact_phone": "+441234567890",
  "debtor_contact_name": "Mean Buyer",
  "debtor_contact_email": "mean@buyer.com",
  "debtor_contact_phone": "+440987654321",
  "confirm_correct": true,
  "collections_terms_acceptance": true,
  "collect_fees_from_debtor": false
}
curl --request PATCH \
  --url https://api-sandbox.hokodo.co/v1/collections/coll-TWyj6XFLYfCnw95KgBhHDf \
  --header 'Authorization: Token <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "creditor_contact_phone": "+441234567890",
    "debtor_contact_name": "Mean Buyer",
    "debtor_contact_email": "mean@buyer.com",
    "debtor_contact_phone": "+440987654321",
    "confirm_correct": true,
    "collections_terms_acceptance": true,
    "collect_fees_from_debtor": false
}'

Response

200 Ok
Content-Type: application/json
{
  "id": "coll-e8rkfpHNMyCoaL6MNab8sP",
  "confirm_correct": true,
  "collections_terms_acceptance": true,
  "created": "2020-05-28T13:47:05.086201Z",
  "modified": "2020-05-28T13:54:50.902225Z",
  "sent": null,
  "creditor_contact_name": "",
  "creditor_contact_email": "johnny@hokodo.co",
  "creditor_contact_phone": "+441234567890",
  "debtor_address": "1 Some Street, London, SE11 6NQ",
  "debtor_postcode": "SE11 6NQ",
  "debtor_city": "London",
  "debtor_country": "GB",
  "debtor_contact_name": "Mean Buyer",
  "debtor_contact_email": "mean@buyer.com",
  "debtor_contact_phone": "+440987654321",
  "debtor_website": "",
  "actions_taken": "",
  "partial_payment": "0.00",
  "disputed": false,
  "other_invoices": false,
  "reasons": "",
  "comments": "",
  "bank_account_name": "Some Company LLC",
  "bank_account_sortcode": "",
  "bank_account_number": "",
  "bank_account_email": "johnny@hokodo.co",
  "confirmed_correct": "2020-05-28T13:54:50.902013Z",
  "accepted_collections_terms": "2020-05-28T13:54:50.902022Z",
  "collect_fees_from_debtor": false,
  "policy": "pol-bX9R96pziJSs6774VkpmCR"
}

Update a collection request.

Errors

errors description
400 a required field is missing or some of the fields have incorrect value
404 the collection_id is probably invalid, the collection has not been found

CollectionDocument object

{
    "id": "cdoc-afipG98cKcQL5VRjVfPP2S",
    "policy": "pol-WwX8y7hKWyje2ttm6nAbvU",
    "type": "invoice",
    "description": "",
    "file": "https://hokodo-sandbox-clientdocuments.s3.amazonaws.com/media/user_uploaded_documents/..."
}
field type flags description
id string(uuid) read-only API unique identifier of the collection document
policy string(uuid) required API identifier of the linked policy
type string optional Type of document, see below
description string optional Description of the document
file string(uri) read-only Link to the document

CollectionDocument type

Possible collection document types are:

Create a collection document

POST /v1/collectiondocuments HTTP/1.1
Host: api-sandbox.hokodo.co
Content-Type: multipart/form-data; boundary=X-CLIENT-BOUNDARY
Authorization: Token <your_api_key>
Accept: */*
Content-Length: <some_length>
curl --request POST \
  --url https://api-sandbox.hokodo.co/v1/collectiondocuments \
  --header 'Authorization: Token <your_api_key>' \
  --form policy=pol-WwX8y7hKWyje2ttm6nAbvU \
  --form type=invoice \
  --form file=@/path/to/file

To create a collection document, you create a CollectionDocument object attached to the Policy of the unpaid invoice.

Send a collection request

PUT /v1/collections/<collection_id>/send HTTP/1.1
Authorization: Token <your_api_key> 
curl --request PUT \
  --url https://api-sandbox.hokodo.co/v1/collections/coll-TWyj6XFLYfCnw95KgBhHDf/send/ \
  --header 'Authorization: Token <your_api_key>'

Once all the information has been filled in correctly, calling this hands over the collection request to our collections partner.

Notes and possible causes of error

A Policy has to be in the state late_can_handover for a collection request to be possible. The policy reaches that state automatically depending on the due date and the terms of the insurance (how soon can a customer hand over the invoice after the due date). Trying to start or modify a collection request in another state will result in an HTTP 409 error in the response.

When a policy is insured, it will go in the following states:

There are a number of additional states after a policy goes through the collections and claims process, that can be useful to display the current status of collections to the users.

Collection

Claim

Webhooks

Sample content

Active insurance policy

  • policy is filled
  • quote.status is accepted
{
    "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-5DpFHDgVpv87wJFa9dXyvW",
    "id": "trns-5DpFHDgVpv87wJFa9dXyvW",
    "owner": "user-MzPbafH78Byb65U7PshRpF",
    "debtor": "co-Tv5pezgn7VAYEbLXfexbS2",
    "debtor_name": "Test debtor",
    "debtor_country": "GB",
    "debtor_regnum": "",
    "debtor_address": "",
    "creditor": "co-WUaZHXbdsbAvxpYbBPhYh8",
    "creditor_name": "Test creditor",
    "creditor_country": "GB",
    "creditor_regnum": "",
    "creditor_address": "",
    "status": "pending",
    "pay_method": "unknown",
    "net_amount": "1234.00",
    "gross_amount": null,
    "currency": "GBP",
    "issue_date": "2019-10-16",
    "due_date": "2019-12-16",
    "paid_date": null,
    "number": "",
    "items": [],
    "source": null,
    "unique_id": "",
    "policy": {
        "url": "https://api-sandbox.hokodo.co/v1/policies/pol-4wvXe9URiecFYiLxuXkkxf",
        "id": "pol-4wvXe9URiecFYiLxuXkkxf",
        "number": "T-4ZW5-611D",
        "status": "active",
        "created": "2019-11-07T11:17:40.451738Z",
        "documents": [
            {
                "category": "policy",
                "url": "https://removed.for.this.example"
            }
        ],
        "collection": null,
        "loss_payee": "Not applicable"
    },
    "quote": {
        "url": "https://api-sandbox.hokodo.co/v1/quotes/quo-jaetYa8f9TmFDBYsb33KAT",
        "id": "quo-jaetYa8f9TmFDBYsb33KAT",
        "client": {
            "url": "https://api-sandbox.hokodo.co/v1/companies/co-WUaZHXbdsbAvxpYbBPhYh8",
            "id": "co-WUaZHXbdsbAvxpYbBPhYh8",
            "country": "GB",
            "name": "Test creditor Limited",
            "address": "123 Main Street, City, County, Region, Postcode",
            "city": "Test city",
            "postcode": "Test postcode",
            "legal_form": "Private limited with share capital",
            "sectors": [
                {
                    "system": "SIC2007",
                    "code": "47710"
                }
            ],
            "creation_date": "1995-07-12",
            "identifiers": [
                {
                    "idtype": "reg_number",
                    "country": "GB",
                    "value": "01234567"
                }
            ],
            "email": "",
            "phone": "",
            "status": "Active",
            "accounts_type": "Total exemption full"
        },
        "status": "accepted",
        "proposed_quote": null,
        "rejection_reason": null,
        "created": "2019-11-07T11:17:38.166454Z",
        "valid_until": "2019-11-07T13:17:38.158274Z",
        "price": {
            "currency": "GBP",
            "total_price": "20.45",
            "premium": "18.26",
            "ipt": "2.19"
        },
        "insured": {
            "currency": "GBP",
            "insured_amount": "1110.60"
        },
        "insured_pc_net": 90.0,
        "insured_pc_gross": null,
        "referral_url": null
    },
    "estimated_quote_price": null
}

Quote, but no insurance policy purchased

  • policy is null
  • quote.status is offered
{
    "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-5DpFHDgVpv87wJFa9dXyvW",
    "id": "trns-5DpFHDgVpv87wJFa9dXyvW",
    "owner": "user-MzPbafH78Byb65U7PshRpF",
    "debtor": "co-Tv5pezgn7VAYEbLXfexbS2",
    "debtor_name": "Test debtor",
    "debtor_country": "GB",
    "debtor_regnum": "",
    "debtor_address": "",
    "creditor": "co-WUaZHXbdsbAvxpYbBPhYh8",
    "creditor_name": "Test creditor",
    "creditor_country": "GB",
    "creditor_regnum": "",
    "creditor_address": "",
    "status": "pending",
    "pay_method": "unknown",
    "net_amount": "1234.00",
    "gross_amount": null,
    "currency": "GBP",
    "issue_date": "2019-10-16",
    "due_date": "2019-12-16",
    "paid_date": null,
    "number": "",
    "items": [],
    "source": null,
    "unique_id": "",
    "policy": null,
    "quote": {
        "url": "https://api-sandbox.hokodo.co/v1/quotes/quo-jaetYa8f9TmFDBYsb33KAT",
        "id": "quo-jaetYa8f9TmFDBYsb33KAT",
        "client": {
            "url": "https://api-sandbox.hokodo.co/v1/companies/co-WUaZHXbdsbAvxpYbBPhYh8",
            "id": "co-WUaZHXbdsbAvxpYbBPhYh8",
            "country": "GB",
            "name": "Test creditor Limited",
            "address": "123 Main Street, City, County, Region, Postcode",
            "city": "Test city",
            "postcode": "Test postcode",
            "legal_form": "Private limited with share capital",
            "sectors": [
                {
                    "system": "SIC2007",
                    "code": "47710"
                }
            ],
            "creation_date": "1995-07-12",
            "identifiers": [
                {
                    "idtype": "reg_number",
                    "country": "GB",
                    "value": "01234567"
                }
            ],
            "email": "",
            "phone": "",
            "status": "Active",
            "accounts_type": "Total exemption full"
        },
        "status": "offered",
        "proposed_quote": null,
        "rejection_reason": null,
        "created": "2019-11-07T11:17:38.166454Z",
        "valid_until": "2019-11-07T13:17:38.158274Z",
        "price": {
            "currency": "GBP",
            "total_price": "20.45",
            "premium": "18.26",
            "ipt": "2.19"
        },
        "insured": {
            "currency": "GBP",
            "insured_amount": "1110.60"
        },
        "insured_pc_net": 90.0,
        "insured_pc_gross": null,
        "referral_url": null
    },
    "estimated_quote_price": null
}

No valid quote, nor insurance policy

  • policy is null
  • quote.status is null
{
    "url": "https://api-sandbox.hokodo.co/v1/transactions/trns-5DpFHDgVpv87wJFa9dXyvW",
    "id": "trns-5DpFHDgVpv87wJFa9dXyvW",
    "owner": "user-MzPbafH78Byb65U7PshRpF",
    "debtor": "co-Tv5pezgn7VAYEbLXfexbS2",
    "debtor_name": "Test debtor",
    "debtor_country": "GB",
    "debtor_regnum": "",
    "debtor_address": "",
    "creditor": "co-WUaZHXbdsbAvxpYbBPhYh8",
    "creditor_name": "Test creditor",
    "creditor_country": "GB",
    "creditor_regnum": "",
    "creditor_address": "",
    "status": "pending",
    "pay_method": "unknown",
    "net_amount": "1234.00",
    "gross_amount": null,
    "currency": "GBP",
    "issue_date": "2019-10-16",
    "due_date": "2019-12-16",
    "paid_date": null,
    "number": "",
    "items": [],
    "source": null,
    "unique_id": "",
    "policy": null,
    "quote": null,
    "estimated_quote_price": null
}

Hokodo can send webhook events to notify your application when an event related to a quote or active policy happens. This is useful for example for events that are triggered by a user action outside of your application, or events that are triggered at a certain point in time on our side. For example, but not limited to:

It allows you to avoid polling the quote view endpoint and be notified instead. It is entirely optional. If you wish to use this feature, please let us know at partner-support@hokodo.co and we will be happy to configure your account.

Concepts

Currently the webhooks cover changes related to the Transaction, Quote and Policy objects.

Your callback endpoint will receive the Transaction object representation, in expanded form to include the latest quote or policy attached to the transaction. Hokodo calls your endpoint with the content of the transaction, as you would get if you were polling GET /v1/transactions/:transaction-id/?expand=quote,policy.

What you need to build on your side is an endpoint ready to receive our requests, with that expanded Transaction in the body. Provide us with:

Notes

  1. Your endpoint must be using HTTPS.

  2. In production, our API will verify the validity of the HTTPS certificate. In sandbox, you can use a self-signed certitificate.

  3. Our API will send a POST request, with the content of the Transaction in the POST request body as JSON.

  4. Our API expects a 2xx status code from your endpoint for a successful response.

  5. Our API will retry up to 3 times if it can't connect successfully to your endpoint. It will wait 0, 2, and 4 seconds respectively before the 1st, 2nd and 3rd retry.

Events of interest

If a quote has been offered and the customer has purchased an insurance policy, both the quote and policy field in the transaction JSON will be filled and expanded. What will probably be of most interest to you then is looking at the quote and policy fields in the webhook request body.

Errors

The Hokodo API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The requested function is not available for your account.
404 Not Found -- The specified object could not be found.
405 Method Not Allowed -- You tried to access an object with an invalid method.
409 Conflict -- The requested action conflicts with the current state of the object.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.