Policies

These endpoints query the shared insurance product catalogue. To track a user's own insurance and covered people, use Portfolios. Creating or removing a portfolio tracking record does not modify the catalogue.

The Policy Model

The policy model contains information about an insurance policy, including its policy ID, insurance carrier, optional policy type, status, and directory listing status. The plan name, plan type, benefits, and exclusions are also top-level fields. Each benefit is an object with a code, name, category, and description. Metadata such as ingestion and last synchronization timestamps is also provided to help track when the policy data was added and last updated.

Properties

Name
policy_id
Type
string
Description
The unique ID identifying the insurance policy.
Name
product_type
Type
string (optional)
Description
The product classification from the linked policy_type table's policy_type column. Omitted when unavailable.
Name
carrier_name
Type
string
Description
The name of the insurance provider.
Name
policy_type
Type
string (optional)
Description
The type of insurance coverage. Omitted when unavailable.
Name
status
Type
string
Description
The current status of the insurance policy.
Name
directory_status
Type
string
Description
The publication status of the policy in the insurance directory.
Name
plan_name
Type
string
Description
The marketed name of the insurance plan.
Name
plan_type
Type
string
Description
The classification of the insurance plan.
Name
benefits
Type
array
Description
A list of benefit objects included in the policy.
Name
benefits[].benefit_code
Type
string
Description
Identifier for the benefit.
Name
benefits[].name
Type
string
Description
The benefit's name.
Name
benefits[].category
Type
string
Description
The category of coverage associated with the benefit.
Name
benefits[].description
Type
string
Description
A description of the benefit and its terms.
Name
exclusions
Type
array
Description
A list of exclusions specified for the policy.
Name
ingested_at
Type
timestamp
Description
ISO 8601 timestamp indicating when the policy data was ingested into the system.
Name
last_synced_at
Type
timestamp
Description
ISO 8601 timestamp indicating when the policy data was last synchronized.

GET/v1/policies

List all policies

This endpoint allows you to retrieve a paginated list of shared catalogue products. The default page size is 20 and the maximum is 100.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of policies returned.

Request

GET

/v1/policies

curl -G https://api.insuredspeaks.com/v1/policies \
  -H "X-API-Key: $API_KEY" \
  -d limit=10

Response

{
  "success": true,
  "data": [
    {
      "policy_id": "taka_000002bz",
      "product_type": "Life",
      "carrier_name": "AIA PUBLIC Takaful Berhad",
      "status": "active",
      "directory_status": "published",
      "policy_type": "Takaful",
      "plan_name": "AIA i-Starter Plan",
      "plan_type": "Standalone Plan",
      "benefits": [],
      "exclusions": [],
      "ingested_at": "2026-10-21T15:37:01.662Z",
      "last_synced_at": "2026-10-21T15:37:01.662Z"
    }
  ]
}

GET/v1/policies/:id

Retrieve a policy

This endpoint allows you to retrieve a policy by providing its Insurance Product id. Refer to the list at the top of this page to see which properties are included with policy objects.

Request

GET

/v1/policies/taka_000002bz

curl https://api.insuredspeaks.com/v1/policies/taka_000002bz \
  -H "X-API-Key: $API_KEY"

Response

{
  "success": true,
  "data": {
    "policy_id": "taka_000002bz",
    "product_type": "Life",
    "carrier_name": "AIA PUBLIC Takaful Berhad",
    "status": "active",
    "directory_status": "published",
    "policy_type": "Takaful",
    "plan_name": "AIA i-Starter Plan",
    "plan_type": "Standalone Plan",
    "benefits": [],
    "exclusions": [],
    "ingested_at": "2026-10-22T11:59:26.561Z",
    "last_synced_at": "2026-10-22T11:59:26.561Z"
  }
}