Qoala API Specification API
Policy API documentation consist of create policy, get policy detail or status, policy cancellation and policy activation.
OpenAPI Specification
openapi: 3.2.0
info:
title: Qoala API Specification API
version: v1.3
description: 'Operations tagged API Specification across 14 of this provider''s published API definitions: qoala-bus-insurance-openapi.yml, qoala-claim-api-alt-openapi.yml, qoala-claim-api-openapi.yml, qoala-credit-insurance-openapi.yml, qoala-credit-life-insurance-openapi.yml, qoala-experience-event-insurance-openapi.yml, qoala-flight-insurance-openapi.yml, qoala-gadget-insurance-openapi.yml, qoala-goods-insurance-openapi.yml, qoala-hotel-insurance-openapi.yml, qoala-logistic-insurance-openapi.yml, qoala-micro-health-insurance-openapi.yml, qoala-train-insurance-openapi.yml, qoala-vehicle-insurance-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-staging.qoala.app
- url: https://api.uat.qoala.app
- url: https://api.qoala.app
security:
- ApiKeyAuth: []
tags:
- name: API Specification
description: Policy API documentation consist of create policy, get policy detail or status, policy cancellation and policy activation.
paths:
/api/v2/quotation/quotes:
servers:
- url: https://api-staging.qoala.app
- url: https://api.uat.qoala.app
- url: https://api.qoala.app
post:
tags:
- API Specification
summary: Create Policy
description: This API is used by partner to create policy
security:
- ApiKeyAuth: []
responses:
'200':
$ref: '#/components/responses/200createQuotation'
'202':
$ref: '#/components/responses/202createQuotation'
'400':
$ref: '#/components/responses/400createQuotation'
'401':
$ref: '#/components/responses/401createQuotation'
'404':
$ref: '#/components/responses/404createQuotation'
'500':
$ref: '#/components/responses/500createQuotation'
requestBody:
content:
application/json:
examples:
Bus:
$ref: '#/components/examples/createPolicyBus'
schema:
type: object
required:
- product_category
- partner_transaction_number
- product_code
- policy_holder
properties:
product_category:
description: product classification will be provided by Qoala
type: string
enum:
- TRAVEL
partner_transaction_number:
description: The Transaction ID serves as a unique identifier for each transaction initiated through the API. Partners are responsible for generating this ID and ensuring its uniqueness across their transactions.
type: string
maxLength: 100
example: 1234567890
product_code:
description: Defined by Qoala, plays a pivotal role in the API, providing contextual information about certain aspects of the product. However, as of now, the details for this field will be shared at a later stage when the product is ready for testing.
type: string
example: T-TBUS-PARTNER-001
purchased_at:
description: A timestamp indicating when a product was purchased. This field is of the time type and is not mandatory. By default, if no value is provided, it is set to the current time. The timestamp is formatted using the ISO 8601 date format.
type: string
example: '2023-09-04T06:38:00Z'
format: date-time
premium:
description: A vital component of the API, representing the cost of an insurance product in its respective currency.
type: number
example: 2000
format: float64
policy_holder:
description: The policy_holder field serves as a container for essential data regarding the holder of the policy. This data provides insight into the individual or organization that is associated with the policy.
type: object
$ref: '#/components/schemas/PolicyHolderRequest'
insureds:
description: 'Insured''s object. The object can be different depending on the product. For example: covered user, car, smartphone, flight, hotel, etc.'
type: array
items:
$ref: '#/components/schemas/Insured'
description: The following list explains body payload for creating policy
required: true
x-codeSamples:
- lang: Go
source: "package main\n\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"net/http\"\n)\n\ntype RequestPayload struct {\n\tProductCategory string `json:\"product_category\"`\n\tPartnerTransactionNumber string `json:\"partner_transaction_number\"`\n\t// ... other fields\n}\n\nfunc main() {\n\t// Construct the URL\n\tapiUrl := \"https://{{HOST_QOALA}}/api/v1/quotation\"\n\n\t// Create the request payload\n\tpayload := RequestPayload{\n\t\tProductCategory: \"TRAVEL\",\n\t\tPartnerTransactionNumber: \"FL-01\",\n\t\t// ... initialize other fields\n\t}\n\n\t// Convert the payload to JSON\n\tpayloadBytes, err := json.Marshal(payload)\n\tif err != nil {\n\t\tfmt.Println(\"Error encoding JSON:\", err)\n\t\treturn\n\t}\n\n\t// Create a new POST request with the payload\n\treq, err := http.NewRequest(\"POST\", apiUrl, bytes.NewBuffer(payloadBytes))\n\tif err != nil {\n\t\tfmt.Println(\"Error creating request:\", err)\n\t\treturn\n\t}\n\n\t// Set headers\n\treq.Header.Set(\"x-api-key\", \"abcdefg\")\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\t// Send the request\n\tclient := http.Client{}\n\tresp, err := client.Do(req)\n\tif err != nil {\n\t\tfmt.Println(\"Error sending request:\", err)\n\t\treturn\n\t}\n\tdefer resp.Body.Close()\n\n\t// Print the response status code\n\tfmt.Println(\"Response Status:\", resp.Status)\n}\n"
- lang: PHP
source: "<?php\n\nclass RequestPayload {\n public $product_category;\n public $partner_transaction_number;\n public $purchased_at;\n public $premium;\n public $pool_amount;\n public $addons;\n public $policy_holder;\n public $insureds;\n}\n\nclass Addons {\n public $code;\n public $unit;\n public $sum_insured;\n}\n\nclass PolicyHolder {\n public $identity_type;\n public $identity_number;\n public $full_name;\n public $email;\n public $phone_number;\n public $birth_date;\n public $gender;\n public $relationship;\n public $address;\n public $documents;\n}\n\nclass Document {\n public $file_name;\n public $type;\n public $url;\n}\n\nclass Insureds {\n public $type;\n public $details; // This can be either InsuredTravel or InsuredUser\n public $documents;\n}\n\nclass InsuredTravel {\n public $identity_type;\n public $identity_number;\n public $booking_time;\n public $name;\n public $number;\n // ... other fields\n}\n\nclass InsuredUser {\n public $identity_type;\n public $identity_number;\n public $full_name;\n public $email;\n public $phone_number;\n public $birth_date;\n public $gender;\n // ... other fields\n}\n\n// Construct the URL\n$apiUrl = \"https://{{HOST_QOALA}}/api/v1/quotation\";\n\n// Create the request payload\n$payload = new RequestPayload();\n$payload->product_category = \"TRAVEL\";\n$payload->partner_transaction_number = \"FL-01\";\n// ... initialize other fields\n\n// Convert the payload to JSON\n$payloadJson = json_encode($payload);\n\n// Create headers\n$headers = [\n \"x-api-key: abcdefg\",\n \"Content-Type: application/json\"\n];\n\n// Initialize cURL session\n$ch = curl_init();\n\n// Set cURL options\ncurl_setopt($ch, CURLOPT_URL, $apiUrl);\ncurl_setopt($ch, CURLOPT_POST, true);\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payloadJson);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, $headers);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n\n// Execute cURL session\n$response = curl_exec($ch);\n\n// Check for cURL errors\nif (curl_errno($ch)) {\n echo \"cURL Error: \" . curl_error($ch);\n} else {\n // Print response\n echo \"Response: \" . $response;\n}\n\n// Close cURL session\ncurl_close($ch);\n\n?>\n"
- lang: Node.js
source: "const axios = require('axios');\n\nasync function createPolicy() {\n const apiUrl = 'https://{{HOST_QOALA}}/api/v1/quotation';\n \n const payload = {\n product_category: 'TRAVEL',\n partner_transaction_number: 'FL-01',\n // ... other fields\n };\n\n const headers = {\n 'x-api-key': 'abcdefg',\n 'Content-Type': 'application/json'\n };\n\n try {\n const response = await axios.post(apiUrl, payload, { headers });\n console.log('Response:', response.data);\n } catch (error) {\n console.error('Error:', error.message);\n }\n}\n\ncreatePolicy();\n"
- lang: Python
source: "import requests\nimport json\n\ndef create_policy():\n api_url = 'https://{{HOST_QOALA}}/api/v1/quotation'\n\n payload = {\n \"product_category\": \"TRAVEL\",\n \"partner_transaction_number\": \"FL-01\",\n # ... other fields\n }\n\n headers = {\n 'x-api-key': 'abcdefg',\n 'Content-Type': 'application/json'\n }\n\n try:\n response = requests.post(api_url, data=json.dumps(payload), headers=headers)\n response_data = response.json()\n print('Response:', response_data)\n except requests.exceptions.RequestException as e:\n print('Error:', e)\n\ncreate_policy()\n"
/api/v2/quotation/quotes/partner/status:
servers:
- url: https://api-staging.qoala.app
- url: https://api.uat.qoala.app
- url: https://api.qoala.app
get:
tags:
- API Specification
summary: Get Policy Detail
description: Policy detail
operationId: detailPolicy
security:
- ApiKeyAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/200detailPolicy'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
code:
type: number
example: 400
error_code:
type: string
example: POLCE-ERR-001
message:
type: string
example: invalid request
status:
type: string
example: failed
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Unauthorizer Access
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
code:
type: number
example: 404
error_code:
type: string
example: QEC-ERR-REST-003
message:
type: string
example: product code T-TBUS-PARTNER-001 not found
status:
type: string
example: failed
'500':
description: Internal Error
content:
application/json:
schema:
type: object
properties:
code:
type: number
example: 500
error_code:
type: string
example: QES-ERR-001
message:
type: string
example: internal server error
status:
type: string
example: failed
parameters:
- in: query
name: partner_transaction_number
required: true
description: The Transaction ID serves as a unique identifier for each transaction initiated through the API. Partners are responsible for generating this ID and ensuring its uniqueness across all of their transactions.
schema:
type: string
example: 5099e32c-5c75-4587
- in: query
name: product_code
required: true
description: Defined by Qoala, this field plays a pivotal role in the API, providing contextual information about certain aspects of the product. However, the details for this field will be shared at a later stage, when the product is ready for testing in the staging environment.
schema:
type: string
example: T-TBUS-1029
- in: query
name: quotation_number
required: true
description: Unique identity number generated by qoala system as transaction identifier for each transaction that received by qoala.
schema:
type: string
example: QS-230802-5K9I8
/api/v2/policies/partner/cancel:
servers:
- url: https://api-staging.qoala.app
- url: https://api.uat.qoala.app
- url: https://api.qoala.app
patch:
tags:
- API Specification
summary: Cancel Policy
description: Policy cancellation
operationId: cancelPolicy
security:
- ApiKeyAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
message:
type: string
example: Success update policy status
code:
type: number
example: 200
data:
type: object
properties:
policy_number:
type: string
example: T-TBUS-PARTNER-001-20230828-OM94T
status:
type: string
example: POLICY_CANCELLED
reason:
type: string
example: explain reason why do you cancel this policy
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
code:
type: number
example: 400
error_code:
type: string
example: POLCE-ERR-001
message:
type: string
example: invalid request
status:
type: string
example: failed
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Unauthorizer Access
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
code:
type: number
example: 404
error_code:
type: string
example: QEC-ERR-REST-003
message:
type: string
example: product code T-TBUS-PARTNER-001 not found
status:
type: string
example: failed
'500':
description: Internal Error
content:
application/json:
schema:
type: object
properties:
code:
type: number
example: 500
error_code:
type: string
example: QES-ERR-001
message:
type: string
example: internal server error
status:
type: string
example: failed
requestBody:
content:
application/json:
schema:
type: object
required:
- policy_number
- reason
properties:
policy_number:
type: string
description: policy number generated by qoala
reason:
type: string
description: reason why do we need to cancel the policy
/api/v2/claims/partner/create:
servers:
- url: https://api-staging.qoala.app
- url: https://api.uat.qoala.app
- url: https://api.qoala.app
post:
tags:
- API Specification
summary: Create Claim
description: 'Partners could use this endpoint to generate and create a new claim. Qoala will validate and make sure the policy is claimable. Qoala will share the claim number in the response and if needed could also notify the partner via callback Integration.
### List of Claim Status
| Status Code | Claim Status (Subject) | Description |
| --------------------------- | ------------------------------- | ----------------------------------------------- |
| `CLAIM_INITIATE` | Claim initiated | When the claimer successfully submitted a claim |
| `QOALA_CLAIM_APPROVE` | Claim received by Qoala | Qoala approved the claim |
| `QOALA_CLAIM_REJECT` | Claim rejected by Qoala | Qoala rejects the claim |
| `INSURANCE_CLAIM_APPROVE` | Claim approved by Insurance | Insurance approved the claim |
| `INSURANCE_CLAIM_REJECT` | Claim rejected by Insurance | Insurance rejected the claim |
| `INSURANCE_CLAIM_PAID` | Claim paid by Insurance | Claim already paid by insurance |
| `INSURANCE_CLAIM_WAITING_PAID` | Claim Waiting paid | Claim already approved by insurance and waiting for paid |
Each status code corresponds to a specific claim status, providing information about the state of the claim in the system.
'
operationId: createClaim
security:
- ApiKeyAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
message:
type: string
example: Claim Service success
code:
type: number
example: 200
data:
type: object
properties:
number:
type: string
example: C-123445
last_status:
type: string
example: CLAIM_INITIATED
'400':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
code:
type: string
description: http code response
example: 400
error_code:
type: string
description: "qoala system error code for error classification\n \n### List of Error Code detail\n\n|Error Code | HTTP Status | Description|\n|----------|-------------|------------|\n|CLAIM-CREATE-001 | 400 | Invalid Body request|\n|CLAIM-CREATE-003 | 400 | Policy Not Available|\n|CLAIM-CREATE-004 | 400 | Product Not Found|\n|CLAIM-CREATE-006 | 400 | Failed claim Reach maximum Limitation|\n|CLAIM-CREATE-007 | 400 | Invalid Time|\n|CLAIM-CREATE-018 | 400 | Benefit Code Not Valid|\n"
example: CLAIM-CREATE-006
message:
type: string
description: status of response, it will contain failed
example: failed claim, reach maximum limitation
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
code:
type: number
description: http code response
example: 401
error_code:
type: string
description: 'qoala system error code for invalid token
### List of Error Code detail
| Error Code | HTTP Status | Description |
|---|---|---|
| QC-CLT-KEYA-V1-003 | 401 | Invalid Permission |
'
example: QEC-ERR-401-01
message:
type: string
description: short message explains about the failed response
example: invalid unauthorized
status:
type: string
description: status of response, it will contain failed
example: failed
'500':
description: Internal Error
content:
application/json:
schema:
type: object
properties:
code:
type: number
description: http code response
example: 500
error_code:
type: string
description: 'qoala system error code for error classification
### List of Error Code detail
|Error Code | HTTP Status | Description|
|----------|-------------|------------|
|CLAIM-CREATE-008 | 500 | Failed claim Reach maximum Limitation in Benefit Level|
'
example: CLAIM-ERR-001
message:
type: string
description: short message explains about the failed response
example: internal server error
status:
type: string
description: status of response, it will contain failed
example: failed
requestBody:
content:
application/json:
examples:
Claim for Travel Product:
$ref: '#/components/examples/createClaimTravelProduct'
Claim for Credit Insurance With Reinstatement:
$ref: '#/components/examples/createClaimCreditInsuranceWithReinstatement'
schema:
type: object
required:
- currency_code
- country_code
- policy_number
- user_channel
- partner_code
- product
- total_amount
properties:
currency_code:
description: Claim currency
type: string
example: IDR
country_code:
description: Claim country code
type: string
example: ID
total_amount:
type: number
description: "Total Claim amount\n *for finance product the value is equal to outstanding amount"
user_channel:
description: Channel where the claim comes from
type: string
example: PARTNERSHIP
partner_code:
description: Partner code predefined by Qoala
type: string
example: ABC
partner_claim_id:
description: Unique claim identifier generated by the partner system
type: string
example: C12345
policy_number:
description: Unique policy number generated by the Qoala system
type: string
example: F-CRDC-001-20230802
product:
description: Product information
type: object
required:
- category
- code
- benefit_code
properties:
category:
type: string
enum:
- GADGET
- TRAVEL
- FINANCE
- MICROHEALTH
code:
type: string
example: PA-123
description: Product code generated by Qoala
benefit_code:
type: string
example: BE-1234
description: Benefit Code generated by Qoala
claimant_data:
description: Claimant information
type: object
required:
- full_name
properties:
full_name:
type: string
description: Claimant full name
phone_number:
type: string
description: Claimant phone number
form_data:
description: Claim form Data
type: array
items:
type: object
properties:
name:
type: string
example: Alamat
description: name of data
value:
type: string
example: 85778
description: value of data
covered_data:
description: insureds information
type: array
items:
type: object
$ref: '#/components/schemas/Insured_2'
claim_additional_info:
description: Claim additional info only applicable for specific product category
type: object
properties:
loan_id:
type: string
description: partner transaction number or loan id // required for Credit Insurance with reinstatement product
borrower_name:
type: string
description: Borrower name // required for Credit Insurance with reinstatement product
beneficiary_name:
type: string
description: Beneficiary or lender name // required for Credit Insurance with reinstatement product
last_payment_date:
type: string
description: last payment date, if the loan hasnt been paid or loan is less than 30 days please put loan start date // required for Credit Insurance with reinstatement product
last_collection_date:
type: string
description: last collection date from the partner // required for Credit Insurance with reinstatement product
outstanding_amount:
type: number
description: remaining loan
description: Payload for creating claim // required for Credit Insurance with reinstatement product
required: true
/api/v2/claims/partner/cancel:
servers:
- url: https://api-staging.qoala.app
- url: https://api.uat.qoala.app
- url: https://api.qoala.app
patch:
tags:
- API Specification
summary: Cancel Claim
description: Claim cancellation
operationId: cancelClaim
security:
- ApiKeyAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
message:
type: string
example: Claim Service success
code:
type: number
example: 200
data:
type: object
properties:
claim_number:
type: string
example: C-123445
status:
type: string
example: CLAIM_CANCELLED
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
code:
type: string
example: 401
status:
type: string
example: failed
message:
type: string
example: Unauthorized token
error_code:
type: string
example: QC-CLT-KEYA-V1-003
'500':
description: Internal Error
content:
application/json:
schema:
type: object
properties:
code:
type: number
example: 500
error_code:
type: string
example: CLAIM-ERR-001
message:
type: string
example: internal server error
status:
type: string
example: failed
requestBody:
content:
application/json:
schema:
type: object
properties:
claim_number:
type: string
description: unique identifier for claim created by qoala system
example: C-123455
parent_category:
type: string
example: microhealth
description: category of product
enum:
- microhealth
- finance
- gadget
- travel
reason:
type: string
description: explain the reason for cancellation briefly
example: wrong claim number
description: Payload for cancelling claim
required: true
/api/v2/claims/partner/update/presign:
servers:
- url: https://api-staging.qoala.app
- url: https://api.uat.qoala.app
- url: https://api.qoala.app
post:
tags:
- API Specification
summary: Upload claim documents
description: Presign url to upload document
operationId: presignCreateClaim
security:
- ApiKeyAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
message:
type: string
example: Claim Service success
code:
t
# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/qoala/refs/heads/main/openapi/qoala-api-specification-api-openapi.yml