Bima Bima API Docs v1

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
Awaiting4Request created, no update yet
Processing5Insurers are pricing; read again
Quoted6Offers ready
NoOffers7No insurer returned a price
Failed8Pricing failed
Pending9Payment received, policy being issued
Completed10Policy issued, documents sent
Cancelled11Cancelled before issue
Terminated12Terminated during the period
Expired13Quotation expired
Finalized19Data finalised, no more changes
Approved20Approved by the insurer
Followup31Follow-up needed
Submitted32Customer details submitted, payment can follow
Working33Customer 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_parentShort number, encrypted id, parent id (renewals / copies)
request_type_code / _nameProduct, e.g. MOTOR_PRIVATE_INSURANCE ("Motor Private"), TRAVEL_INSURANCE ("Travel")
insurance_type_code / _nameInsurance type, e.g. MOTOR_THIRD_PARTY, TRAVEL_OUTBOUND. Use it to pick the next page after an offer is chosen
status_code, status_titleSee quotation statuses
quotation_expire_DateExpiry (may be empty)
required_approvaltrue when the offer needs insurer approval before payment; see Follow Up
customerAs sent, plus full_name, gender_name, nationality_country_code/_name, region_name, city_name
request_dataProduct 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)
paymentgross_amount, tax_amount, net_amount, vat_amount, total_premium, discount_amount, total_amount, cross_sell_data[]; filled after Submit

Offer fields

Field Description
offer_idSingle offer id (string). Empty on a group offer
offer_group_idGroup offer id (string): one offer covering several travellers. Empty on a single offer
provider_code, provider_name, provider_thumbInsurer; logo path is relative to the API host
product_name, product_code, package_*, plan_*Product of the insurer, e.g. "Third Party"
is_valid_offerHide 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_amountBase premium
other_amountSum of the selected optional covers
gross_amountbasic + other
tax_amountTax and contribution (rate in the TAX cover option)
net_amountgross + tax (+ processing_fee)
vat_amountVAT (5%)
total_premiumAmount to pay, in OMR. Show this as the price
insurers_coverd_count, insurers_not_coverd_count, insurers_limit_min/_maxTravellers 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
Pricing example (motor) basic 45.600 + optional 5.000 (Roadside Assistance) = gross 50.600; tax 0.844; net 51.444; VAT 2.322; total_premium 53.766. The starting price shown before optional covers = 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_PREMIUM are price lines with is_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's amount.
  • 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): covers is one array; covers with is_mandatory or is_selected count 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_selected true 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 data as Read), but request_data comes 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: false and that is the final state.
  • Price after the change = the offer's new total_premium; other_amount now includes the selected add-ons.
  • Later Reads return the saved selection, so a refreshed page shows the same covers.
Recommended UI behaviour Repricing takes a few seconds (about 4 s in testing). Show a spinner on the cover and keep it unchanged until the response arrives; disable the offer's other covers and its Buy button meanwhile. On an error, change nothing and show the message. Example: adding Courtesy Car (7 days, 3.900) moved an offer from 53.766 to 57.666.

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.

  1. Read the quote (Quotation/Read with read_only_offers: true) and fill the form from customer and request_data. Travel: also call ReadInsurers for the travellers.
  2. Send the product's Create Quotation request again with the full, changed request. Use 0 for vehicle and traveller ids.
  3. 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

Note Bima records your payment and starts issuing the policy upon receiving confirmation from your system, without performing payment verification on Bima’s end. The response does not wait for the policy: it confirms the request was received and returns the payment details.
Payment collection access Your API user must be linked to a collector that has an enabled payment gateway. Otherwise the request returns Unauthorized with the reason in messages; contact Bima to enable it.
Safe to retry Send the same 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.
Check approval before payment Before processing the payment, you must check the quotation approval status (required_approval). If required_approval is false, you may proceed with the payment or request a follow-up if needed.
Using Bima's payment page instead? Confirmation is for partners that collect payment themselves. To let Bima take the payment, use Review, Finalize and GetPaymentLink instead.

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.