Leads

Some insurance types do not return a quote; for these types you pass the buyer's details to your provider as a lead, through your provider connection. You submit the lead with POST /api/v1/insurance/leads and follow its outcome on the lead endpoint and by webhook.

• A lead is a hand-over. Lunixi passes the lead to your provider and shows the outcome of the hand-over. A lead has no quote, premium, collection, policy or document; the next step (contacting the buyer, making an offer) is with the provider and is not part of the lead.
• Leads exist only on the API path. There are no leads on the Checkout Form or on payment links.
• A lead is not linked to a payment. A lead has no amount, currency, basket item or payment.

Authentication and signing: Flows › Authentication.

Lead types

To submit a lead:

• The type must be enabled on your account, and you must be using insurance on the API path.
• Your connections must have an active provider product that accepts leads for this type.

If a condition is not met, the request returns 412 insurance.type.not_available. Because lead-only types (CARGO_TRANSIT) do not return a quote, they are not listed in eligibility, and quote requests for them receive 412 insurance.type.not_available.

MOTOR_THIRD_PARTY_LIABILITY and MOTOR_COMPREHENSIVE return quotes too: Insurance Types › MOTOR_THIRD_PARTY_LIABILITY, MOTOR_COMPREHENSIVE. Leads and quotes work with separate products in your connections: a lead needs a product that accepts leads, a quote a product that returns quotes.

Flow

Submitting a lead: POST /api/v1/insurance/leads

Idempotency-Key is required. See Retries and Idempotency-Key.

• The fields and their requirements are in the type's lead schema: Lead schemas. A field that is not in the schema is rejected.
• All field violations are returned in a single 422 insurance.validation.invalid response; if there is a violation, no lead is created and no request goes to the provider.
• Formats: Data Formats.

A lead request for MOTOR_COMPREHENSIVE. The values are examples; replace the values in angle brackets with your buyer's details:

{
  "insuranceType": "MOTOR_COMPREHENSIVE",
  "policyholder": {
    "identityType": "TCKN",
    "identityNumber": "<identity number>",
    "birthDate": "<YYYY-MM-DD>",
    "email": "<email>",
    "phone": "<E.164 phone>"
  },
  "vehicle": {
    "plate": "<plate>",
    "registrationDocument": {
      "serial": "<serial code>",
      "number": "<registration number>"
    }
  },
  "note": "<lead note>"
}

source lunixi-sign.sh
BODY='<lead request, compact JSON>'
lunixi_sign POST "/api/v1/insurance/leads" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com/api/v1/insurance/leads" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: insurance-lead-1001" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

The fields and an example of the CARGO_TRANSIT lead: Insurance Types › CARGO_TRANSIT.

Response

When the request completes, it returns 201 with the lead object in data. If the provider received the lead, status is SUBMITTED; if the outcome is not known, it is UNKNOWN.

Outcomes

details.leadId in the error response carries the lead's ID; you can see the lead on the retrieve endpoint. If processing stops with an unexpected error, the response is 500 insurance.internal.integrity and the lead shows as UNKNOWN.

Retries and Idempotency-Key

• The lead is passed to the provider in the same request. The request can take up to 45 seconds; set your client timeout accordingly.
• If you did not receive the response after a timeout or a 5xx, repeat the request with the same Idempotency-Key and the same body. If the lead was created on the first attempt, no new lead is created; the existing lead is returned with its current status and is not sent to the provider again.
• The same key returns the same lead whatever its status. To send a FAILED or UNKNOWN lead again, generate a new key. Sending an UNKNOWN lead again may create a second lead at the provider.
• If you use the same key with a different request (another type, version or body), the response is 409 insurance.idempotency.conflict.

The lead object

The lead does not carry the provider's name, code, raw message or lead reference.

Statuses

SUBMITTED and FAILED are final; they do not change. The provider's steps after the lead (contacting the buyer, an offer or a policy) are not reflected in the lead's status.

Listing: GET /api/v1/insurance/leads

Returns your leads newest first, in cursor-based pages.

In the response the leads are in the data.items array; paging information is in the pageInfo field. A malformed cursor returns 422 insurance.validation.invalid (field: cursor).

source lunixi-sign.sh
REQ_PATH="/api/v1/insurance/leads?limit=25&insuranceType=CARGO_TRANSIT"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

Retrieval: GET /api/v1/insurance/leads/{leadId}

Returns a single lead. In the response, data is the lead object. Use this endpoint to confirm an outcome whose webhook you did not receive.

Errors

Common codes: Flows › Responses and errors. Code details: Error Codes › Leads.

Related

• Insurance Types and Schemas: lead schemas
• Webhook Events: insurance.lead.submitted
• Error Codes: lead codes