Bima Bima API Docs v1

Motor Insurance

Third party or comprehensive cover for a private vehicle registered in Oman. Vehicle details (make, model, year, body, registration type) are fetched from ROP by the API, so only the plate and owner details are sent.

request_type_code MOTOR_PRIVATE_INSURANCE
insurance_type_code MOTOR_THIRD_PARTY MOTOR_COMPREHENSIVE
Pricing Asynchronous (async: true): read offers until Quoted
Before Submit Required documents

Create Quotation

Starts a motor quote for one vehicle. With async: true it returns at once with a quotation_id; insurers then price it in the background and you read the offers. To create a quotation you need to make a POST call to the following url: POST/v1/Quotation/Create

FieldTypeLimitRequiredDescription
request_type_codestring50YesQuotation request type: MOTOR_PRIVATE_INSURANCE
insurance_type_codestring50YesInsurance type: MOTOR_THIRD_PARTY, MOTOR_COMPREHENSIVE (same value as vehicles[].insurance_type)
voucher_codestring50OptionalVoucher or promo code
policy_no_previousstring50OptionalPrevious policy number, if any
lang_codestring2OptionalRequest language: en, ar. Default: en
asyncboolean-Optionaltrue: create the quotation and return at once, read offers later. false: return the offers in the response. Recommended: true
include_databoolean-OptionalResponse includes additional data
include_resultboolean-OptionalResponse includes offers
client_type_idint-OptionalWebsite: 1, Mobile: 2, Kiosk: 3
collector_track_idstring50OptionalYour own unique reference for this request
reference_by_idInt64-OptionalBima customer id when the customer is logged in; otherwise 0
osstring50OptionalDevice operating system name, version
browserstring50OptionalDevice browser name, version
schedule
Policy period object
FieldTypeLimitRequiredDescription
policy_term_idInt64-OptionalPolicy term; default: the product's term
date_fromstring10OptionalPolicy start date, dd/MM/yyyy
date_tostring10OptionalPolicy end date, dd/MM/yyyy
customer
Customer (vehicle owner) object
FieldTypeLimitRequiredDescription
country_codestring5YesMobile dial code without +, e.g. 968
national_nostring15YesMobile number without the dial code. Oman: exactly 8 digits
contact_full_nostring20Yescountry_code + national_no, e.g. 96895542930
area_codestring3OptionalCalculated from contact_full_no when empty
subscriber_codestring15OptionalCalculated from contact_full_no when empty
id_nostring10YesVehicle owner's driving licence number, digits only. Same value as license_no
license_nostring10YesVehicle owner's driving licence number, digits only
id_typeint-Fixed1
title_idint-Fixed1
first_namestring25OptionalSend ""; names are sent later
middle_namestring25OptionalSend ""
last_namestring25OptionalSend ""
emailstring50OptionalContact email
dobstring10OptionalDate of birth, dd/MM/yyyy
gender_idint-Fixed1
nationality_country_idint-OptionalFrom the nationalities lookup
city_idInt64-Fixed52
region_id, town_idInt64-OptionalSend 0
pobox_nostring10OptionalP.O. Box number
addressstring30OptionalAddress
address2string30OptionalAddress line 2
vehicles
Vehicles array (one vehicle per quotation) array
FieldTypeLimitRequiredDescription
idInt64-Optional0 for a new vehicle
insurance_typestring50YesMOTOR_THIRD_PARTY or MOTOR_COMPREHENSIVE (same as insurance_type_code)
vehicle_nostring6YesPlate number, digits only. New vehicle: "0"
vehicle_codestring5YesPlate code from the plate-code list. New vehicle: "T B A"
vehicle_valuenumber1-999999ConditionalComprehensive: market value in whole OMR, required. Third party: not used, send 1
renewal_requestboolean-Fixedtrue
transfer_requestboolean-Optionaltrue when the vehicle is being transferred to a new owner (renew in the new owner's name). Never together with new_plate_request
new_plate_requestboolean-Optionaltrue for a new vehicle not yet registered with ROP (bought new from an agency or imported). Needs chassis_no
chassis_nostring20ConditionalNew vehicle only: letters/digits, upper case. Otherwise ""
{ "request_type_code": "MOTOR_PRIVATE_INSURANCE", "insurance_type_code": "MOTOR_THIRD_PARTY", "voucher_code": "", "lang_code": "en", "include_data": false, "include_result": true, "async": true, "customer": { "id_no": "99086408", "id_type": 1, "id_expire_date": "", "license_no": "99086408", "country_code": "968", "area_code": "", "subscriber_code": "", "national_no": "95542930", "contact_full_no": "96895542930", "title_id": 1, "first_name": "", "middle_name": "", "last_name": "", "email": "", "nationality_country_id": 0, "residence_country_id": 0, "dob": "", "passport_no": "", "gender_id": 1, "region_id": 0, "city_id": 52, "town_id": 0, "pobox_no": "", "address": "", "address2": "" }, "vehicles": [ { "id": 0, "insurance_type": "MOTOR_THIRD_PARTY", "vehicle_no": "97337", "vehicle_code": "H", "vehicle_value": 1, "renewal_request": true, "transfer_request": false, "new_plate_request": false, "chassis_no": "" } ], "client_type_id": 1, "reference_by_id": 0, "os": "Windows", "browser": "Chrome" }
{ "status_code": "200", "status_message": "Quotation retrieved successfully", "data": { "quotation_no": "26100291362", "quotation_id": "dldTUytwK0tReHpW...", "status_code": "Processing", "status_title": "Processing", "messages": [] }, "messages": [] }

New vehicle (not yet registered)

For a vehicle bought new from an agency or imported, send new_plate_request: true, vehicle_no: "0", vehicle_code: "T B A" and the chassis_no with Create. Send the agency document (vehicle invoice, JPG/PNG/PDF up to 5 MB) with Submit in documents:

"documents": [ { "doc_type_id": 75, "ref_id_sub": 0, "file_name": "Vehicle_Invoice.jpg", "data_base64string": "<base64 without the data: prefix>" } ]

Handling the response

  • Processing or Quoted: go to the offers (Quotation/Read with this quotation_id).
  • NoOffers right away: no insurer could price this vehicle.
  • Any other status with messages: show the messages (the API is asking for more customer input).

data.status_code may be the name or the number; see quotation statuses. The API adds the vehicle details from ROP by itself: make_name, model_name, body_type_name, registration_type_name, spacs_name, no_of_doors, no_of_passengers, and the model year (in request_result.details as mfg_year).

Fixed values The fixed customer values (title_id 1, gender_id 1, city_id 52, id_type 1) are what Bima's website sends. vehicle_value is checked only for comprehensive cover (must be greater than 0).

Required Documents

After the customer picks an offer, list the documents that offer needs with Quotation/RequiredDocuments, then send the files inside the Submit request as documents. A typical motor offer asks for:

doc_type_id doc_type_code Document
67LICENSE_FRONTLicence front side
68LICENSE_BACKLicence back side
60VEHICLE_FRONTVehicle front photo (camera only)
69MULKIYA_FRONTMulkiya (vehicle registration card) front side

Submit Data

Locks the chosen offer and saves the owner's details and documents; after it the quotation status is Submitted and Review returns the payment amounts. To submit a quotation you need to make a POST call to the following url: POST/v1/Quotation/Submit

FieldTypeLimitRequiredDescription
quotation_idstring500YesQuotation Id (encrypted)
offer_idstring20ConditionalSelected offer's id. Send exactly one of offer_id / offer_group_id
offer_group_idstring20ConditionalSelected group offer's id (offers covering several insured persons)
lang_codestring2YesRequest language: en, ar
policy_no_previousstring50OptionalPrevious policy number, if any
schedule
Policy start object
FieldTypeLimitRequiredDescription
date_fromstring10OptionalPolicy start date, dd/MM/yyyy. Default: today
customer
Customer (vehicle owner) object
FieldTypeLimitRequiredDescription
id_nostring10YesOwner's licence number from the quotation
id_typeint-Optional1 = Person, 2 = Company
id_expire_datestring10OptionalID expiry date, dd/MM/yyyy
title_idint-OptionalFrom the titles lookup
first_namestring25YesOwner's first name as written on the Mulkiya
middle_namestring25OptionalEverything between the first and last name
last_namestring25YesOwner's last name as written on the Mulkiya
emailstring50OptionalPolicy documents are sent to it
dobstring10OptionalDate of birth, dd/MM/yyyy
gender_idint-Optional1 = Male, 2 = Female
nationality_country_idint-OptionalFrom the nationalities lookup
region_id, city_id, town_idInt64-OptionalFrom the regions and cities lookup
pobox_nostring10OptionalP.O. Box number
addressstring30OptionalAddress
address2string30OptionalAddress line 2
contact_full_nostring20YesThe quotation's contact number
documents
Files for the required documents, one item per document type. Empty array when none array
FieldTypeLimitRequiredDescription
doc_type_idInt64-YesDocument type from RequiredDocuments, e.g. 67
ref_id_subInt64-Optional0
file_namestring100YesFile name with extension, e.g. license-front.jpg
data_base64stringstring5 MBConditionalFile content in base64 without the data: prefix. Send this or file_url
file_urlstring500ConditionalFull http(s) URL of the file. Send this or data_base64string
question_answers
Answers to the offer's questions. Empty array when none array
FieldTypeLimitRequiredDescription
question_idInt64-YesQuestion unique id
option_idInt64-ConditionalSelected option id for choice questions; otherwise 0
answerstring50YesAnswer value
input_detilsstring500OptionalAdditional input details if required
{ "quotation_id": "dldTUytwK0tReHpW...", "offer_id": "102328", "lang_code": "en", "customer": { "country_code": "968", "national_no": "95542930", "contact_full_no": "96895542930", "first_name": "Saif", "middle_name": "Ali Salim", "last_name": "Almaluk", "passport_no": "", "email": "", "id_no": "99086408", "license_no": "99086408" }, "documents": [ { "doc_type_id": 67, "file_name": "license-front.jpg", "data_base64string": "/9j/4AAQ..." } ] }
Response On success status_code is "200" with "Quotation submitted successfully" and the quotation status becomes Submitted. Otherwise show status_message and messages[] and let the customer correct the form.
Single offer vs group offer Send a single offer as offer_id. A single offer sent as offer_group_id is refused with "Selected offer/group offer details not found".