Purchase an insurance product for a customer
POST/v1/orders
Submit an order for an insurance product for a customer.
Request
- application/json
Body
required
Details of the customer and the product to be purchased.
- GITPurchaseData
- ThirdPartyAutoPurchaseData
- ComprehensiveAutoPurchaseData
- MarinePurchaseData
- HealthPurchaseData
- JobLossPurchaseData
- GadgetPurchaseData
- CreditLifePurchaseData
- FireBurglaryPurchaseData
- InvestmentLifePurchaseData
- LifePurchaseData
- PersonalAccidentPurchaseData
- MicroHealthPurchaseData
- TravelPurchaseData
- InvestmentPurchaseData
- MedicalMalpracticePurchaseData
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
An external reference stored on the order and included in relevant webhooks.
Value of the insured goods. Required when the product uses relative-premium calculation.
Possible values: [single, recurring]
Default value: recurring
Single or recurring trip
Required for recurring trips. This is the number of trips made per day.
Required for recurring trips. Number of days in a year the trips are made (365 max)
The pickup address of the shipment or parcel. Accepted but not currently required by request validation.
The destination address of the shipment or parcel. Accepted but not currently required by request validation.
If this order has attachments, supply their IDs as an array. Each attachment must belong to the authenticated partner and must not already be attached to another resource.
For brokers only. The premium rate for the product.
For brokers only. A percentage of the premium to be added as tax
Possible values: [monthly, quarterly, annually]
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
Estimated value of the insured vehicle.
An external reference stored on the order and included in relevant webhooks.
The customer's driver's license number
The id of the attachment containing the customer's driver's license
the vehicle registration number
Possible values: [car, sedan, suv]
the class of the vehicle
The brand of the vehicle
The model of the vehicle
The vehicle's year of manufacture
The color of the vehicle
Possible values: [monthly, quarterly, annually]
Optional attachment IDs. Each attachment must belong to the authenticated partner and must not already be attached to another resource.
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
Estimated value of the insured vehicle. Required when the product uses relative-premium calculation.
An external reference stored on the order and included in relevant webhooks.
the vehicle registration number
Possible values: [car, sedan, suv]
the class of the vehicle
The brand of the vehicle
The model of the vehicle
The vehicle's year of manufacture
The customer's driver's license number
Required for the Kenyan market. The id of the attachment containing the customer's driver's license
Required for Kenyan products when the partner was created on or after November 28, 2023. The ID of the vehicle valuation report attachment.
The color of the vehicle
If this order has other attachments, supply their IDs as an array. Each attachment must belong to the authenticated partner and must not already be attached to another resource.
For brokers only. The premium rate for the product.
For brokers only. A percentage of the premium to be added as tax
Possible values: [monthly, quarterly, annually]
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
An external reference stored on the order and included in relevant webhooks.
Value of the insured goods. Required when the product uses relative-premium calculation.
The originating port of the shipment. Accepted but not currently required by request validation.
The destination port of the shipment. Accepted but not currently required by request validation.
If this order has attachments, supply their IDs as an array. Each attachment must belong to the authenticated partner and must not already be attached to another resource.
For brokers only. The premium rate for the product.
For brokers only. A percentage of the premium to be added as tax
Possible values: [monthly, quarterly, annually]
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner. The customer data must contain the following details - sex - birth_date
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
The start date of the intended policy coverage
An external reference stored on the order and included in relevant webhooks.
Preferred hospital location for claims
Kindly write down any previous health complication you may have
beneficiaries object[]
Possible values: <= 5
Optional. When supplied, every listed field is required.
Your relationship with the beneficiary
next_of_kin object
Next of kin details. Required if not set when creating the customer record. If customer record has next of kin, this will be used for this transaction instead.
If this order has attachments, supply their IDs as an array. Each attachment must belong to the authenticated partner and must not already be attached to another resource.
For brokers only. The premium rate for the product.
For brokers only. A percentage of the premium to be added as tax
height of the policy holder in meters
weight of the policy holder in Kg
Possible values: [monthly, quarterly, annually]
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
An external reference stored on the order and included in relevant webhooks.
The customer's net monthly income. Either this field or net_income must be supplied.
The name of the customer's employer
The role of the user in the company
employment date
Gross monthly income before taxes or deductions
Net monthly income after taxes or deductions. Either this field or asset_value must be supplied.
Optional attachment IDs. Each attachment must belong to the authenticated partner and must not already be attached to another resource.
For brokers only. The premium rate for the product.
For brokers only. A percentage of the premium to be added as tax
Possible values: [monthly, quarterly, annually]
The ID of the employment letter attachment.
Possible values: >= 3 characters and <= 3 characters
The three-character currency code used for gross income.
Possible values: >= 3 characters and <= 3 characters
The three-character currency code used for net income.
next_of_kin object[]
Possible values: <= 1
Optional. When supplied, every listed field is required.
Your relationship with the beneficiary
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
An external reference stored on the order and included in relevant webhooks.
The value or price of the gadget. Required when the product uses relative-premium calculation.
The type of gadget.
The name (model and brand) of the gadget.
The IMEI or serial number of the gadget
Date when the gadget was purchased
Optionally upload the following files via the attachments API - Picture of device - Receipt of Ownership Then supply their IDs as an array. Each attachment must belong to the authenticated partner and must not already be attached to another resource.
beneficiaries object[]
Possible values: <= 5
Optional. When supplied, every listed field is required.
Your relationship with the beneficiary
The id of the attachment to receipt of ownership
The id of the attachent of device attachment
For brokers only. The premium rate for the product.
For brokers only. A percentage of the premium to be added as tax
Possible values: [monthly, quarterly, annually]
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
An external reference stored on the order and included in relevant webhooks.
The amount insured. Required when the product uses relative-premium calculation.
Possible values: >= 1 and <= 12
Duration of the loan to be insured in months, should not exceed 12 months.
For loans lasting more than one month, the amount returned every month by the customer.
Business address of the customer
Nature of Customer's business
height of the policy holder in meters
weight of the policy holder in Kg
If this order has attachments, supply their IDs as an array. Each attachment must belong to the authenticated partner and must not already be attached to another resource.
Possible values: [monthly, quarterly, annually]
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
An external reference stored on the order and included in relevant webhooks.
The value of the insured property. Required when the product uses relative-premium calculation.
Address of the insured property
If this order has attachments, supply their IDs as an array. Each attachment must belong to the authenticated partner and must not already be attached to another resource.
For brokers only. The premium rate for the product.
For brokers only. A percentage of the premium to be added as tax
Possible values: [monthly, quarterly, annually]
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
An external reference stored on the order and included in relevant webhooks.
Possible values: [single, group]
beneficiaries object[]required
Possible values: <= 5
A maximum of five beneficiaries is accepted and their percentage shares must total 100.
The percentage of cover to be recieved by the beneficiary
The monthly savings amount. It must meet the selected product's configured minimum.
Possible values: [monthly, quarterly, half-yearly, yearly, one-off]
How often savings will be made until the duration is complete.
The savings duration in months. It must meet the selected product's configured minimum.
The amount of life insurance coverage chosen. It cannot exceed the product's configured maximum life sum assured.
The key of a child partner belonging to the authenticated parent partner.
height of the policy holder in meters
weight of the policy holder in Kg
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
An external reference stored on the order and included in relevant webhooks.
Possible values: [single, group]
beneficiaries object[]required
Possible values: <= 5
A maximum of five beneficiaries is accepted and their percentage shares must total 100.
The percentage of cover to be recieved by the beneficiary
Possible values: >= 12
The policy duration in months. Product-specific minimum and customer age limits also apply.
The requested cover amount. It cannot exceed the product's configured maximum sum assured.
The key of a child partner belonging to the authenticated parent partner.
height of the policy holder
weight of the policy holder
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
metadata objectnullable
Additional values merged into the order metadata and included in relevant webhooks.
Additional values merged into the order metadata and included in relevant webhooks.
Optional occupation of the policy holder. Stored in the order metadata when supplied.
Any previous injuries of the policy holder
Optional circumstances, lifestyle, or hobbies that make the policyholder liable to injury. Stored in the order metadata when supplied.
The policy holder's identification attachment ID. It must belong to the authenticated partner.
Optional height of the policy holder. Stored in the order metadata when supplied.
Optional weight of the policy holder. Stored in the order metadata when supplied.
dependants object[]
Optional dependant plans. Each dependant must satisfy the selected plan's age rules.
The dependant's date of birth
Possible values: [M, F]
relationship to the parent policy holder
occupation of the dependant
The ID of the personal accident plan for this dependant
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
An external reference stored on the order and included in relevant webhooks.
The optional current health condition of the policy holder. The customer must have a date of birth and satisfy the product's age rules.
The policy holder's identification attachment ID. It must belong to the authenticated partner.
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
An external reference stored on the order and included in relevant webhooks.
Possible values: [Business, Tourism, Study, Pilgrimage]
Purpose of travel
Possible values: >= 1 and <= 365
The number of travel days.
international passport number
upload the internation passport using the attachments endpoint and supply the Id
Optional: The nationality of customer's next of kin. Provide if missing from the customer record
Optional: The address of customer Provide if residential_address is missing from the customer record
Optional: The state of customer's address. Provide if missing from the customer record
Optional: The country of customer's address. Provide if missing from the customer record
Optional: The name of customer's next of kin. Provide if missing from the customer record
Optional: The phone of customers's next of kin. Provide if missing from the customer record
travellers object[]
If the customer is travelling with others and wishes to purchase same insurance for them, then the detials of the extra travellers should be specified here.
personal_info objectrequired
Possible values: [M, F]
Must be either M or F
Traveller's date of birth e.g 1990-10-10
The name of traveller's next of kin
The phone of traveller's next of kin
contact_info objectrequired
traveller's email address.
Traveller's phone number.
travel_info objectrequired
Possible values: [Business, Tourism, Study, Pilgrimage]
Purpose of travel
international passport number
upload the internation passport using the attachments endpoint and supply the Id
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
An external reference stored on the order and included in relevant webhooks.
Possible values: [single, group]
beneficiaries object[]required
Possible values: <= 5
A maximum of five beneficiaries is accepted and their percentage shares must total 100.
The percentage of cover to be recieved by the beneficiary
The monthly savings amount. It must meet the selected product's configured minimum when one is configured.
Possible values: [monthly, quarterly, half-yearly, yearly, one-off]
How often savings will be made until the duration is complete.
The savings duration in months. It must meet the selected product's configured minimum when one is configured.
height of the policy holder in meters
weight of the policy holder in Kg
The key of a child partner belonging to the authenticated parent partner.
The code of an approved, non-archived product available to the authenticated partner.
The reference of a customer belonging to the authenticated partner.
Possible values: [wallet, web_link, card]
How the order will be paid. If omitted, the authenticated partner's configured payment option is used.
the start date of the intended policy coverage
metadata objectnullable
Additional values merged into the order metadata and included in relevant webhooks.
Additional values merged into the order metadata and included in relevant webhooks.
Possible values: >= 1
The maximum amount that can be paid out for a single claim
Possible values: >= 1
The maximum total amount that can be paid out for all claims during the policy period
Possible values: >= 1
Duration of the policy coverage in months
The medical practitioner's occupation. Must be one of the valid options available for this product (use the field-options endpoint to get available options)
If this order has attachments, supply their IDs as an array. Each attachment must belong to the authenticated partner and must not already be attached to another resource.
The key of a child partner belonging to the authenticated parent partner.
Responses
- 200
- 400
- 401
- 403
- 422
OK
- application/json
- Schema
- Example (from schema)
Schema
order object
payment_instructions objectnullable
meta objectnullable
Returned when the selected product defines a life sum assured.
{
"order": {
"id": 23,
"asset_ref": "rwt345",
"product_price": 1200.89,
"partner_commission": 20.76,
"amount_due": 1180.13,
"currency": "NGN",
"payment_instructions": {
"message": "Payment successful",
"success": true
},
"payment_gateway_charge": null,
"status": "pending",
"country": "NG",
"meta": {
"premium_frequency": "annually"
},
"life_sum_assured": "5000000"
}
}
The order could not be created.
- application/json
- Schema
- Example (from schema)
Schema
{
"message": "We couldn't process your order. Premium could not be calculated"
}
Unauthenticated
The product is unavailable to the partner or the request is unauthorized.
- application/json
- Schema
- Example (from schema)
Schema
{
"message": "This product is not available in your region / currency"
}
Unprocessable Content
- application/json
- Schema
- Example (from schema)
Schema
errors object
{
"message": "The given data was invalid",
"errors": {
"customer_ref": [
"The selected customer ref is invalid"
],
"product_code": [
"The product code field is required"
]
}
}