How to offer insurance

Particeep offer insurance, backed by Axa, for loans and equity fundraises.
We will describe the basic steps to implement the insurance on your website. This documentation will focus only on the technical part, please contact us if you have any business questions on this insurance.

We will describe the workflow to allow your user to subscribe to a loan insurance. It's easy to switch between loan and equity insurance, the main difference is required fields and the price.
Pre-requisites : manage authentication with particeep's API. You can follow the Getting started tutorial if you need some help.

NB: The insurance API is hosted on a specific sub-domain

Public access
base url

Step 1 - Create an insurance

We take for granted that your website has already collected data about the loan of your user.

In order to create your insurance you need to send a POST request on /v1/insurance/loan/new with the following information.

   "user": {
     "email": "",
     "firstName": "jean",
     "lastName": "dupont",
     "gender": "MEN",
     "phone": "0601020304",
     "birthday": "1982-10-17T00:00:00Z",
     "birthPlace": "Paris",
     "birthDepartment": "Ile de France",
     "nationality": "French"
   "address": {
     "number": "3",
     "street": "rue de france",
     "zip": "75600",
     "city": "Paris",
     "country": "FR"
   "loan" : {
     "name" : "name of the enterprise",
     "amount" : 6500000,    // in cents 6500000 <=> 65 000,00 €
     "duration" : 48,       // in month 
     "rate" : 3,            // in percentage
     "kind" : "CONSTANT",   // Either CONSTANT, IN_FINE or CUSTOM. Use CUSTOM if you don't know what to do
     "fundRaiseEnd" : "2040-10-17T00:00:00Z"
The server either made you an insurance offer in the response, such as this one

		  "insurance": {
    "uuid": "416a5cad-85a7-41bd-a381-252b73fb8f36",  // unique id of the offer, we use it later 
    "target": "LoanTarget",                          // the insurance is about a loan and not an equity fundraise
    "response": "Insurance validated",               // indicate that your loan can be insurred 
    "price": 31200,                                  // price in cents 31200 <=> 312,00 € 
    "hasSigned": false
Or your loan is not elligible for an online's insurance and we specify the reason.
You have two choices :

		"insurance": {
  "uuid": "5e8def54-c857-4d40-88ba-0d53c3f456e4",
  "target": "LoanTarget",
  "response": "Please contact for a loan with an amount above 70,000.00 €",
  "hasSigned": false
To update the loan information, use the POST /v1/insurance/loan/{uuid} endpoint. It will let you update all the information about the user, the enterprise and the loan.
We allow partial update so you can update only the amount of the loan for instance

   "loan" : {
     "amount" : 4000000

Step 2 - Sign the contract

Now you know the price of the insurance so you must tell your user about it. If he accept the terms and conditions of the insurance, you can request a signing url.
Do a POST on /v1/signature/{uuid} with the uuid of the insurance. In our previous exemple it would be /v1/signature/416a5cad-85a7-41bd-a381-252b73fb8f36
You also send the following information in the body. It will customize the language of the paiement page and the urls where your user will be redirected after the signing process.

      "language": "fr_FR",								     // iso code of the language
      "successUrl" : "",
      "failUrl"    : "",
      "cancelUrl"  : "",
      "notifyUrl"  : ""
The server will respond with a url to redirect your user to

  "error": {
    "hasError": false,
    "errors": []
  "result": "",
  "meta": {
    "version": "1",
    "endPoint": "/signature/416a5cad-85a7-41bd-a381-252b73fb8f36"
It's very important that your user fill a valid phone number because it will receive a code by sms to sign the contract.

The purpose of the notify url is to tell your server when the status of the signature change. You can't rely on your user being redirected to the success url to register in your system the success of the signature.
A user can tempered with the url or may loose is internet connexion before reaching your success url.
The notify url ensure you that your server will know the statut of the signature.

We'll send a GET request with the following parameters

Notify url
unique id of the insurance
status of the signature, one of the following
  • init : default statut
  • ready : waiting for the next signer
  • expired : created but not completed after 7 days
  • completed : all signers signed
  • canceled : canceled by a signer
  • failed : can't complete the process
  • pending-validation : pending a validation by Registration Authority

Another solution is to use the status endpoint /v1/signature/{uuid}/status but this will required you to implements some sort of batch. As the notify url is a real time solution we advise you to use it.

Step 3 - Display the signed contract

Your user has signed the contract. The last step is to display the signed PDF to your user.
This is fairly easy, just do a GET request on /v1/signature/{uuid}/file and the server will stream you the byte of the document.

Alternatively, if you request the detail of the signature with a GET /v1/signature/{uuid}, you will get all the information on the signature, including a permalink

  "error": {
    "hasError": false,
    "errors": []
  "result": {
    "uuid": "416a5cad-85a7-41bd-a381-252b73fb8f36",
    "email": "",
    "firstName": "particeep",
    "lastName": "insuranceApi",
    "phone": "0600000000",
    "language": "fr_FR",
    "fileName": "",
    // this is the permalink to the contract
    "fileUrl": "",
    // This is where you need to redirect your user to sign the document
    "fileToSignUrl": "",
    "status": "init",
    "notifyUrl": ""
  "meta": {
    "version": "1",
    "endPoint": "/signature/416a5cad-85a7-41bd-a381-252b73fb8f36"
The permalink allow you to share the link of the contract without the need of authentication header whereas /v1/signature/{uuid}/file need the authentication's header to be set. This way you can control who can see the document according to your need.

This is a sample pending contract
This is a sample signed contract

NB : The contract are store for a short period of time (few days) and after that the contract is put in hibernation. It means the contract is not accesible and you need to wait at most 24h for the file to get out of hibernation, then the contract will be available again.
If you want to have the contract available at any time, you need to save it on your own storage.