Quotation APIs
Product-independent APIs used after a quotation is created: read offers, regenerate them, change optional covers, edit the request, confirm, follow up and track.
The common APIs are used to retrieve quotation details that have been updated by the user, create offers, and modify covers when required. Once the customer selects an offer, the system proceeds with payment processing (Bima payment page or your own gateway with the Confirmation API).
Get Quotation
Returns the whole quotation: customer, request data, the offers with their covers, and payment amounts.
Read again every few seconds while the status is Awaiting or Processing.
To get quotation details included input data and offers you need to make POST call to the following url:
POST/v1/Quotation/Read
Quotation Statuses
data.status_code may be returned as the name or the number:
| Status | Code | Meaning |
|---|---|---|
| Awaiting | 4 | Request created, no update yet |
| Processing | 5 | Insurers are pricing; read again |
| Quoted | 6 | Offers ready |
| NoOffers | 7 | No insurer returned a price |
| Failed | 8 | Pricing failed |
| Pending | 9 | Payment received, policy being issued |
| Completed | 10 | Policy issued, documents sent |
| Cancelled | 11 | Cancelled before issue |
| Terminated | 12 | Terminated during the period |
| Expired | 13 | Quotation expired |
| Finalized | 19 | Data finalised, no more changes |
| Approved | 20 | Approved by the insurer |
| Followup | 31 | Follow-up needed |
| Submitted | 32 | Customer details submitted, payment can follow |
| Working | 33 | Customer is entering data |
Polling for offers
Insurers price in the background, so offers can arrive over several reads. Recommended polling (used by Bima's website): first read at once, then wait 5 s,
adding 1 s per attempt, at most 15 reads. Stop when data.status_code is no longer Awaiting / Processing (or 4 / 5), and show offers as they arrive.
Response Reference
Fields of data returned by Read (and by Create, Process, Reprocess and Review).
Quotation fields
| Field | Description |
|---|---|
| quotation_no, quotation_id, quotation_id_parent | Short number, encrypted id, parent id (renewals / copies) |
| request_type_code / _name | Product, e.g. MOTOR_PRIVATE_INSURANCE ("Motor Private"), TRAVEL_INSURANCE ("Travel") |
| insurance_type_code / _name | Insurance type, e.g. MOTOR_THIRD_PARTY, TRAVEL_OUTBOUND. Use it to pick the next page after an offer is chosen |
| status_code, status_title | See quotation statuses |
| quotation_expire_Date | Expiry (may be empty) |
| required_approval | true when the offer needs insurer approval before payment; see Follow Up |
| customer | As sent, plus full_name, gender_name, nationality_country_code/_name, region_name, city_name |
| request_data | Product data. Motor: vehicles[] (with ROP details). Travel: trip, dates, destinations |
| request_result.details[] | { code, value, title } summary lines, e.g. Motor reference_no ("97337/H"), reg_type, mfg_year; Travel contact_no_full (masked), full_name, policy_start_date |
| request_result.offers[] | The offers (see offer fields) |
| payment | gross_amount, tax_amount, net_amount, vat_amount, total_premium, discount_amount, total_amount, cross_sell_data[]; filled after Submit |
Offer fields
| Field | Description |
|---|---|
| offer_id | Single offer id (string). Empty on a group offer |
| offer_group_id | Group offer id (string): one offer covering several travellers. Empty on a single offer |
| provider_code, provider_name, provider_thumb | Insurer; logo path is relative to the API host |
| product_name, product_code, package_*, plan_* | Product of the insurer, e.g. "Third Party" |
| is_valid_offer | Hide offers with false. A group offer may be false while its members are valid: show it when at least one insurers[].offer is valid |
| basic_amount | Base premium |
| other_amount | Sum of the selected optional covers |
| gross_amount | basic + other |
| tax_amount | Tax and contribution (rate in the TAX cover option) |
| net_amount | gross + tax (+ processing_fee) |
| vat_amount | VAT (5%) |
| total_premium | Amount to pay, in OMR. Show this as the price |
| insurers_coverd_count, insurers_not_coverd_count, insurers_limit_min/_max | Travellers covered by a group offer |
| covers | { core: [], included: [], optional: [] } (older responses: a flat array, see covers) |
| badges[] | { code, text, value, icon_name, background_color, description }, e.g. POLICY "Instant", POLICY_TERM "One Year" |
| tob_download_url, network_download_url, documents[] | Table of benefits, hospital network, offer documents |
| medical_tests[] | { test_code, test_name } tests required by the insurer (e.g. Credit Life) |
| insurers[] | Group offer: one row per traveller { insurer_id, title, data, offer }; offer is that traveller's own priced offer (null when not covered) |
| messages[] | Insurer notes |
net_amount - other_amount.
Covers
{
"cover_id": 9,
"cover_code": "COURTESY_CAR",
"cover_name": "Courtesy Car",
"cover_desc_short": "",
"cover_desc_long": "",
"is_mandatory": false,
"is_selected": false,
"is_selectable": true,
"is_viewable": true,
"order_no": 5,
"amount": 0,
"is_excluded": false,
"insured_amount": { "is_enabled": false, "amount": 0, "type": "", "currency_name": "", "currency_code": "", "currency_symbol": "" },
"options": [
{
"option_id": 548,
"option_name": "7 Days",
"is_selected": false,
"amount": 3.9,
"order_no": 1,
"rate": { "is_enabled": false, "value": 7, "type": "Fix" },
"deductible": { "is_enabled": false, "amount": 0, "type": "Fix" },
"copay": { "is_enabled": false, "amount": 0, "type": "Fix" },
"insured_amount": { "amount": 0, "currency_symbol": "" }
},
{
"option_id": 557,
"option_name": "14 Days",
"amount": 7.0
}
]
}
- included: covers in the price. Codes
BASIC_AMOUNT,GROSS_AMOUNT,TAX,NET_AMOUNT,VAT,TOTAL_PREMIUMare price lines withis_viewable: false; do not list them as benefits. - optional: add-ons.
is_selectable: false= shown but cannot be changed (e.g. a mandatory medical cover). Price of an add-on = the chosen option'samount. - Options: with more than one option (e.g. Courtesy Car 7 / 14 days) the customer picks one; the selected one has
is_selected: true. - insured_amount = the benefit limit, in its own currency (
currency_symbol, often$on travel). It is not the premium; the premium is always OMR. - Flat responses (members of a group offer):
coversis one array; covers withis_mandatoryoris_selectedcount as included, the rest as optional.
Process Quotation
Process quotation is the main API where system generates multiple offers for the requested quotation id. It delete previous overs if any and re generates everytime whenever you call this API.
To create offers you need to make a POST call to the following url:
POST/v1/Quotation/Process
Re-process Quotation
In order to add or remove optional covers, you are required to make POST call with requried inputs to the following url:
POST/v1/Quotation/Reprocess
Optional cover rules
- Send every selectable optional cover of the offer (
is_selectable: true), each with its state after the change:is_selectedtrue or false. Ids are sent as strings. option_id: the chosen option; for a cover being switched off, its current or first option.- The response is the full quotation envelope (same
dataas Read), butrequest_datacomes back empty: keep the request data you already have and replace only the offer. - Show the cover exactly as the response has it. The insurer may refuse a cover; then it comes back
is_selected: falseand that is the final state. - Price after the change = the offer's new
total_premium;other_amountnow includes the selected add-ons. - Later Reads return the saved selection, so a refreshed page shows the same covers.
Edit a Quotation
There are two kinds of change. Changing what is being insured (vehicle, cover type, trip, dates, travellers' dates of birth) re-creates the quote. Adding personal details to an existing quote (e.g. traveller names and passports) uses the product's update call, such as UpdateInsurers for travel.
- Read the quote (Quotation/Read with
read_only_offers: true) and fill the form fromcustomerandrequest_data. Travel: also call ReadInsurers for the travellers. - Send the product's Create Quotation request again with the full, changed request. Use
0for vehicle and traveller ids. - A new quotation is created with a new
quotation_id; use it from then on and read its offers as after a normal Create.
Refill tips: take the cover type from insurance_type_code; the contact number from customer.national_no (fallback contact_full_no without the dial code;
subscriber_code holds only part of the number); the motor licence from customer.license_no (or id_no), plate from vehicles[0].vehicle_no / vehicle_code,
and the vehicle value only for Comprehensive.
Confirm/Purchase Offer
Once the customer has selected an offer, you are required to process the payment. After successfully receiving the payment, you must make a POST request to the following URL:
POST/v1/Quotation/Confirmation
Unauthorized with the reason in messages; contact Bima to enable it.
trans_track_id when you retry. The existing payment is returned and no second payment or policy is created. A trans_track_id already used on another quotation is rejected.
required_approval).
If required_approval is false, you may proceed with the payment or request a follow-up if needed.
Follow Up
Some offers require approval and cannot be purchased immediately upon retrieval. In such cases, you can submit follow-up request.
Bima’s support team will coordinate with the respective insurance provider and contact the customer if any additional information or documentation is required.
Once the provider approves the offer, the customer will be asked to proceed with payment. After successful payment, the policy document will be issued.
You are required make a POST request to the following URL:
POST/v1/Quotation/Followup
Request Tracking
In order to get request detils including policy documents, you are required make a POST request to the following URL:
POST/v1/Quotation/Track
Returns the quotation's status, details and documents. Issued policy files can be downloaded through /v1/Document/Download?drefid=....
Pending = paid, policy being issued; Completed = issued and sent. See quotation statuses.