Insurance API - Policies

Table of Contents

• Apply Insurance
• Get Insurance Policy
• Get Insurance Policies
• Policy Statuses

Apply Insurance

Ordering an insurance package reserves a policy but does not issue it. To issue a reserved policy against a named traveller, you need to send a POST request to the /api/insurance/apply endpoint.

You are required to provide the following parameters in the request body:

• policyId: The ID of the reserved policy, returned by POST /api/insurance/order. This is a required field of type string.
• startDate: The coverage start date in DD/MM/YYYY format. This is a required field of type string.
• endDate: The coverage end date in DD/MM/YYYY format. This is a required field of type string.
• mobile: The traveller’s mobile number. This is a required field of type string.
• email: The traveller’s email address. This is a required field of type string.
• insurer: The primary insured traveller. This is a required field of type object, containing:
  • firstName: The traveller’s first name. This is a required field of type string.
  • lastName: The traveller’s last name. This is a required field of type string.
  • nationality: The traveller’s nationality. This is a required field of type string.
  • dateOfBirth: The traveller’s date of birth in DD/MM/YYYY format. Conditional, see below.
  • idNumber: The traveller’s identification number. Conditional, see below.
  • passportNumber: The traveller’s passport number. Conditional, see below.

Which traveller fields are required

dateOfBirth, idNumber, and passportNumber are conditional. Whether each one is mandatory is decided by the requirements object of the package that was purchased, snapshotted onto the policy when the order was created.

Read requirements from GET /api/insurance/packages before you build your collection form, or from GET /api/insurance/policy for a policy you already hold.

A field the package does not ask for is ignored. A field it does ask for must be present and well formed.

Validation rules

Usage - issue an insurance policy

Here is an example of how you can issue an insurance policy using Roamify Insurance API.

curl --request POST \
--url 'https://api-dev.getroamify.com/api/insurance/apply' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
    "policyId": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
    "startDate": "01/08/2026",
    "endDate": "08/08/2026",
    "mobile": "966512345678",
    "email": "traveller@example.com",
    "insurer": {
        "firstName": "Fahad",
        "lastName": "Al Otaibi",
        "nationality": "Saudi Arabia",
        "dateOfBirth": "24/06/1990",
        "idNumber": "1012345678"
    }
}'

const axios = require('axios');
 
axios.post('https://api-dev.getroamify.com/api/insurance/apply', {
    policyId: 'b06036c5-eadc-4f88-aa31-8c207fec91ec',
    startDate: '01/08/2026',
    endDate: '08/08/2026',
    mobile: '966512345678',
    email: 'traveller@example.com',
    insurer: {
        firstName: 'Fahad',
        lastName: 'Al Otaibi',
        nationality: 'Saudi Arabia',
        dateOfBirth: '24/06/1990',
        idNumber: '1012345678'
    }
}, {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Sample Response

{
	"status": "success",
	"data": {
		"policyId": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
		"orderId": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
		"packageId": "insurance-saudi-arabia-individual-7days",
		"package": "Individual - 7 Days",
		"countryName": "Saudi Arabia",
		"type": "insurance",
		"status": "ISSUED",
		"startDate": "01/08/2026",
		"endDate": "08/08/2026",
		"insurerName": "Fahad Al Otaibi",
		"requirements": {
			"phoneNumber": true,
			"dateOfBirth": true,
			"idNumber": true,
			"passportNumber": false
		},
		"coverage": {
			"insuredType": "individual",
			"day": 7,
			"benefits": [
				"Emergency medical cover up to USD 50,000",
				"24/7 assistance hotline"
			]
		},
		"policy": {
			"policyNo": "TRV-2026-000123",
			"policyIssuanceDate": "2026-07-10",
			"policyLink": "https://provider.example.com/policies/TRV-2026-000123.pdf"
		},
		"createdAt": 1731837535,
		"updatedAt": 1731837987,
		"expiredAt": 1765238400
	}
}

Response fields

• policyId: The ID of the policy.
• orderId: The ID of the order the policy was reserved through.
• packageId: The ID of the insurance package.
• package: The display name of the package.
• countryName: The country the policy is associated with.
• type: The service type. Always insurance.
• status: The status of the policy. See Policy Statuses.
• startDate: The coverage start date, DD/MM/YYYY.
• endDate: The coverage end date, DD/MM/YYYY.
• insurerName: The insured traveller’s full name.
• requirements: The traveller fields this policy’s package requires.
• coverage: The coverage summary, containing insuredType, day, and benefits.
• policy: The issued policy document, or null if the policy has not been issued yet. Contains:
  • policyNo: The provider’s policy number.
  • policyIssuanceDate: The date the provider issued the policy.
  • policyLink: A link to the policy document. Pass this to your customer.
• createdAt: The Unix timestamp of when the policy was reserved.
• updatedAt: The Unix timestamp of when the policy was last updated.
• expiredAt: The Unix timestamp of when coverage expires, or -1 if not applicable.

Errors

Get Insurance Policy

To get a specific insurance policy, you need to send a GET request to the /api/insurance/policy endpoint.

You are required to provide the following query parameter:

• policyId: The ID of the insurance policy you want to retrieve. This is a required field of type string.

Use this endpoint to read the requirements for a policy you already hold, and to poll for the issued policy document after a 409 telling you issuance is in progress.

Usage - fetch an insurance policy

curl --request GET \
--url 'https://api-dev.getroamify.com/api/insurance/policy?policyId=Policy ID' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'

const axios = require('axios');
 
axios.get('https://api-dev.getroamify.com/api/insurance/policy?policyId=Policy ID', {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Sample Response

{
	"status": "success",
	"data": {
		"policyId": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
		"orderId": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
		"packageId": "insurance-saudi-arabia-individual-7days",
		"package": "Individual - 7 Days",
		"countryName": "Saudi Arabia",
		"type": "insurance",
		"status": "NEW",
		"startDate": "",
		"endDate": "",
		"insurerName": "",
		"requirements": {
			"phoneNumber": true,
			"dateOfBirth": true,
			"idNumber": true,
			"passportNumber": false
		},
		"coverage": {
			"insuredType": "individual",
			"day": 7,
			"benefits": [
				"Emergency medical cover up to USD 50,000",
				"24/7 assistance hotline"
			]
		},
		"policy": null,
		"createdAt": 1731837535,
		"updatedAt": 1731837535,
		"expiredAt": -1
	}
}

Errors

Get Insurance Policies

To get a list of insurance policies, you need to send a GET request to the /api/insurance/policies endpoint.

There are no required parameters for this endpoint, but you can provide the following optional parameters:

• orderId: Return only the policies reserved through this order. This is an optional field of type string.
• status: The status of the policies to return. This is an optional field of type string. Matching is exact and case-sensitive.
• limit: The number of policies to return. This is an optional field of type number. The default value is 50.

Policies are returned newest first, sorted by createdAt descending.

Usage - fetch a list of insurance policies

curl --request GET \
--url 'https://api-dev.getroamify.com/api/insurance/policies?status=ISSUED&limit=10' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json'

const axios = require('axios');
 
axios.get('https://api-dev.getroamify.com/api/insurance/policies?status=ISSUED&limit=10', {
    headers: {
        'Authorization': 'Bearer {access token here}',
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.error(error);
});

Sample Response

{
	"status": "success",
	"data": {
		"policies": [
			{
				"policyId": "b06036c5-eadc-4f88-aa31-8c207fec91ec",
				"orderId": "67bbabb7-e893-410a-b0a8-4fa62d347b6c",
				"packageId": "insurance-saudi-arabia-individual-7days",
				"package": "Individual - 7 Days",
				"countryName": "Saudi Arabia",
				"type": "insurance",
				"status": "ISSUED",
				"startDate": "01/08/2026",
				"endDate": "08/08/2026",
				"insurerName": "Fahad Al Otaibi",
				"requirements": {
					"phoneNumber": true,
					"dateOfBirth": true,
					"idNumber": true,
					"passportNumber": false
				},
				"coverage": {
					"insuredType": "individual",
					"day": 7,
					"benefits": [
						"Emergency medical cover up to USD 50,000",
						"24/7 assistance hotline"
					]
				},
				"policy": {
					"policyNo": "TRV-2026-000123",
					"policyIssuanceDate": "2026-07-10",
					"policyLink": "https://provider.example.com/policies/TRV-2026-000123.pdf"
				},
				"createdAt": 1731837535,
				"updatedAt": 1731837987,
				"expiredAt": 1765238400
			}
		]
	}
}

Policy Statuses

A policy’s status can be any of the following values: