Policies

As the name suggests, policies are a core part of InsuredSpeaks Labs—the very reason InsuredSpeaks Labs exists is to help you work securely with insurance policy data. On this page, we'll dive into the centralized insurance policy endpoints you can use to manage insurance data programmatically. We'll look at how to query, create, update, and delete policies.

The Policy Model

The policy model contains information about an insurance policy, including its policy number, insurance carrier, product code, status, and directory listing status. It also includes detailed policy information, such as coverage type, annual benefit limits, deductibles, co-payment structures, benefits, included riders, and exclusions. 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_number
Type
string
Description
The unique policy number identifying the insurance policy.
Name
carrier_name
Type
string
Description
The name of the insurance provider.
Name
product_code
Type
string
Description
The code identifying the insurance product.
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
policy_details
Type
object
Description
Detailed information about the insurance policy, including its plan name, coverage, limits, deductibles, benefits, riders, and exclusions.
Name
policy_details.plan_marketing_name
Type
string
Description
The marketed name of the insurance plan.
Name
policy_details.coverage_type
Type
string
Description
The type of insurance coverage offered by the policy.
Name
policy_details.network_type
Type
string
Description
The network classification of the insurance plan.
Name
policy_details.limits
Type
object
Description
The policy's coverage limits, including the annual maximum benefit and currency.
Name
policy_details.limits.annual_max_benefit
Type
number
Description
The maximum annual benefit amount provided by the policy.
Name
policy_details.limits.currency
Type
string
Description
The currency used for the policy's benefit limits.
Name
policy_details.deductible
Type
object
Description
Information about the policy deductible, including its amount, frequency, and type.
Name
policy_details.deductible.amount
Type
number
Description
The specified deductible amount.
Name
policy_details.deductible.frequency
Type
string
Description
The frequency or basis on which the deductible applies.
Name
policy_details.deductible.type
Type
string
Description
The classification of the deductible.
Name
policy_details.copay_structure
Type
object
Description
Details of the policy's co-payment structure.
Name
policy_details.copay_structure.primary_care_visit
Type
number
Description
The specified co-payment amount for a primary care visit.
Name
policy_details.benefits
Type
object
Description
A collection of coverage categories and their corresponding benefit descriptions.
Name
policy_details.riders_included
Type
array
Description
A list of included riders and their descriptions.
Name
policy_details.exclusions
Type
array
Description
A list of exclusions specified for the policy.
Name
ingested_at
Type
timestamp
Description
The timestamp indicating when the policy data was ingested into the system.
Name
last_synced_at
Type
timestamp
Description
The 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 all your policies. By default, a maximum of ten policies are shown per page.

Optional attributes

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

Request

GET

/v1/policies

curl -G https://api.protocol.chat/v1/policies \
  -H "Authorization: Bearer {token}" \
  -d active=true \
  -d limit=10

Response

{
  "success": true,
  "data": [
    {
      "policy_number": "3023",
      "carrier_name": "AIA PUBLIC Takaful Berhad",
      "product_code": "3023",
      "status": "active",
      "directory_status": "published",
      "policy_details": {
        "plan_marketing_name": "AIA i-Starter Plan",
        "coverage_type": "Takaful",
        "network_type": "Standalone Plan",
        "limits": {
          "annual_max_benefit": 0,
          "currency": "MYR"
        },
        "deductible": {
          "amount": 0,
          "frequency": "Annual",
          "type": "unspecified"
        },
        "copay_structure": {
          "primary_care_visit": 0
        },
        "benefits": {
          "Death or total and permanent disability (TPD)": "Death Benefit: Provides a lump sum payment if the participant passes away during the one-year term of the certificate. If death is due to suicide within the first year, only the contributions paid (without profit) will be refunded.",
          "Rewards for healthy living": "Surplus Sharing (Conditional Hibah): Participants are eligible to receive 50% of the distributable surplus from the Participants’ Risk Fund at the end of the financial year. This is provided as a reward for the efficient management of the fund, on the condition that the fund is not in deficit and no claims were made during that year.",
          "Savings, maturity payouts, and investment-linked growth": "Surrender Value: If the certificate is surrendered after the 15-day free-look period, the participant receives the unutilised Tabarru’ (donation) and the unearned Wakalah (agency) fee. This is only applicable for payment modes other than monthly."
        },
        "riders_included": [
          "eath or total and permanent disability (TPD): Death Benefit: Provides a lump sum payment if the participant passes away during the one-year term of the certificate. If death is due to suicide within the first year, only the contributions paid (without profit) will be refunded.",
          "Rewards for healthy living: Surplus Sharing (Conditional Hibah): Participants are eligible to receive 50% of the distributable surplus from the Participants’ Risk Fund at the end of the financial year. This is provided as a reward for the efficient management of the fund, on the condition that the fund is not in deficit and no claims were made during that year.",
          "Savings, maturity payouts, and investment-linked growth: Surrender Value: If the certificate is surrendered after the 15-day free-look period, the participant receives the unutilised Tabarru’ (donation) and the unearned Wakalah (agency) fee. This is only applicable for payment modes other than monthly."
        ],
        "exclusions": []
      },
      "ingested_at": "2026-10-20T13:51:28.394Z",
      "last_synced_at": "2026-10-20T13:51:28.394Z"
    }
  ]
}

POST/v1/contacts

Create a contact

This endpoint allows you to add a new contact to your contact list in Protocol. To add a contact, you must provide their Protocol username and phone number.

Required attributes

Name
username
Type
string
Description
The username for the contact.
Name
phone_number
Type
string
Description
The phone number for the contact.

Optional attributes

Name
avatar_url
Type
string
Description
The avatar image URL for the contact.
Name
display_name
Type
string
Description
The contact display name in the contact list. By default, this is just the username.

Request

POST

/v1/contacts

curl https://api.protocol.chat/v1/contacts \
  -H "Authorization: Bearer {token}" \
  -d username="FrankMcCallister" \
  -d phone_number="1-800-759-3000" \
  -d avatar_url="https://assets.protocol.chat/avatars/frank.jpg"

Response

{
  "id": "WAz8eIbvDR60rouK",
  "username": "FrankMcCallister",
  "phone_number": "1-800-759-3000",
  "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
  "display_name": null,
  "conversation_id": "xgQQXg3hrtjh7AvZ",
  "last_active_at": null,
  "created_at": 692233200
}

GET/v1/contacts/:id

Retrieve a contact

This endpoint allows you to retrieve a contact by providing their Protocol id. Refer to the list at the top of this page to see which properties are included with contact objects.

Request

GET

/v1/contacts/WAz8eIbvDR60rouK

curl https://api.protocol.chat/v1/contacts/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "WAz8eIbvDR60rouK",
  "username": "FrankMcCallister",
  "phone_number": "1-800-759-3000",
  "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
  "display_name": null,
  "conversation_id": "xgQQXg3hrtjh7AvZ",
  "last_active_at": 705103200,
  "created_at": 692233200
}

PUT/v1/contacts/:id

Update a contact

This endpoint allows you to perform an update on a contact. Currently, the only attribute that can be updated on contacts is the display_name attribute which controls how a contact appears in your contact list in Protocol.

Optional attributes

Name
display_name
Type
string
Description
The contact display name in the contact list. By default, this is just the username.

Request

PUT

/v1/contacts/WAz8eIbvDR60rouK

curl -X PUT https://api.protocol.chat/v1/contacts/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}" \
  -d display_name="UncleFrank"

Response

{
  "id": "WAz8eIbvDR60rouK",
  "username": "FrankMcCallister",
  "phone_number": "1-800-759-3000",
  "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
  "display_name": "UncleFrank",
  "conversation_id": "xgQQXg3hrtjh7AvZ",
  "last_active_at": 705103200,
  "created_at": 692233200
}

DELETE/v1/contacts/:id

Delete a contact

This endpoint allows you to delete contacts from your contact list in Protocol. Note: This will also delete your conversation with the given contact.

Request

DELETE

/v1/contacts/WAz8eIbvDR60rouK

curl -X DELETE https://api.protocol.chat/v1/contacts/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"