Holdings

Holdings connect your insurance to the profiles it covers. On this page, we’ll look at how to add, retrieve, update, and remove policies from a portfolio.

Create a key in API keys and send it as shown below. Your key accesses only your own account’s data. See Authentication. Example IDs and product names are illustrative; replace them with values returned by your API.

The Holding Model

A holding is your personal record. It can reference an existing catalogue product or use a custom name for an unlisted product. Its pol_ ID is separate from the catalogue’s product ID, and changes to a holding record do not modify the catalogue.

Properties

Name
id
Type
string
Description
The opaque holding ID, prefixed with pol_ and followed by 32 hexadecimal characters.
Name
portfolio_id
Type
string
Description
The port_ ID of the portfolio containing this policy.
Name
directory_policy_id
Type
integer or null
Description
The linked catalogue product’s integer ID, or null for a custom policy. Requests also accept the catalogue’s insu_ or taka_ code.
Name
policy_name
Type
string or null
Description
Your custom name or optional override. Required when no catalogue product is linked. Trimmed, nonblank when present, and at most 255 characters.
Name
name
Type
string
Description
The displayed name: your override, or the current name from the linked catalogue product.
Name
policy_number
Type
string or null
Description
An optional personal policy number, up to 255 characters.
Name
status
Type
string
Description
One of active, expired, cancelled, or unknown. Defaults to unknown and does not change automatically with dates.
Name
start_date
Type
date or null
Description
Start date in YYYY-MM-DD format. Must not be after the end date when both are supplied.
Name
end_date
Type
date or null
Description
End date in YYYY-MM-DD format.
Name
covered_persons
Type
array
Description
The profiles covered by this policy. May be empty; self is not automatically assigned.
Name
covered_persons[].id
Type
string
Description
The covered profile's per_ ID.
Name
covered_persons[].name
Type
string
Description
The covered profile name.
Name
covered_persons[].relationship
Type
string
Description
The covered profile's relationship: self, spouse, child, parent, or other.
Name
created_at
Type
timestamp
Description
Creation time as Unix seconds.
Name
updated_at
Type
timestamp
Description
Last update time as Unix seconds.

GET/v1/portfolios/:id/policies

List all holdings

Retrieve this portfolio’s holdings, including covered profiles. Results are paginated and ordered newest first. Each policy’s name is resolved from its custom name or the current catalogue product.

Optional attributes

Name
page
Type
integer
Description
Page number, starting at 1. Defaults to 1; maximum 1000000.
Name
limit
Type
integer
Description
Number of results per page. Defaults to 20; maximum 100.

Request

GET

/…/policies

curl -G "https://api.insuredspeaks.com/v1/portfolios/$PORTFOLIO_ID/policies" \
  -H "X-API-Key: $API_KEY" \
  -d page=1 \
  -d limit=20

Response

{
  "success": true,
  "data": [
    {
      "id": "pol_594a8ae4f0214901b51d75cd876293b0",
      "portfolio_id": "port_8f15e4c0904c4c118239c9628302c172",
      "directory_policy_id": 3025,
      "policy_name": null,
      "name": "Example Family Medical Plan",
      "policy_number": "MY-12345",
      "status": "active",
      "start_date": null,
      "end_date": null,
      "covered_persons": [
        {
          "id": "per_9341a218009c4ab6a8d7f3ca1583bf01",
          "name": "Ahmad",
          "relationship": "self"
        },
        {
          "id": "per_4f92f0a1d1704a06ba648e81ae7c9152",
          "name": "Aisha",
          "relationship": "spouse"
        }
      ],
      "created_at": 1792713600,
      "updated_at": 1792713600
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

POST/v1/portfolios/:id/policies

Create a holding

Create a holding from a catalogue product or an unlisted policy. Supply a catalogue reference, a custom name, or both. Use the request tabs to compare the two examples. Product 3025 is illustrative: choose an actual product from your catalogue. Returns 201 with the holding and its covered profiles.

Attributes

Name
directory_policy_id
Type
integer or string
Description
A catalogue integer ID or insu_ / taka_ product code from Policies. The code must match the actual product. Omit or set to null for a custom policy.
Name
policy_name
Type
string
Description
Required for a custom policy; otherwise an optional name override. Nonblank, up to 255 characters.
Name
policy_number
Type
string
Description
An optional personal policy number, up to 255 characters.
Name
status
Type
string
Description
One of active, expired, cancelled, or unknown. Defaults to unknown.
Name
start_date
Type
date
Description
Optional start date in YYYY-MM-DD format.
Name
end_date
Type
date
Description
Optional end date in YYYY-MM-DD format. Must be on or after the start date.
Name
covered_person_ids
Type
array
Description
IDs from this portfolio’s profiles. Include several profiles for family coverage. Defaults to []; duplicate IDs are normalized.

Request

POST

/…/policies

curl "https://api.insuredspeaks.com/v1/portfolios/$PORTFOLIO_ID/policies" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "directory_policy_id": 3025,
  "policy_number": "MY-12345",
  "status": "active",
  "covered_person_ids": [
    "per_9341a218009c4ab6a8d7f3ca1583bf01",
    "per_4f92f0a1d1704a06ba648e81ae7c9152"
  ]
}'

Response

{
  "success": true,
  "data": {
    "id": "pol_594a8ae4f0214901b51d75cd876293b0",
    "portfolio_id": "port_8f15e4c0904c4c118239c9628302c172",
    "directory_policy_id": 3025,
    "policy_name": null,
    "name": "Example Family Medical Plan",
    "policy_number": "MY-12345",
    "status": "active",
    "start_date": null,
    "end_date": null,
    "covered_persons": [
      {
        "id": "per_9341a218009c4ab6a8d7f3ca1583bf01",
        "name": "Ahmad",
        "relationship": "self"
      },
      {
        "id": "per_4f92f0a1d1704a06ba648e81ae7c9152",
        "name": "Aisha",
        "relationship": "spouse"
      }
    ],
    "created_at": 1792713600,
    "updated_at": 1792713600
  }
}

GET/v1/portfolios/:id/policies/:policyId

Retrieve a holding

Retrieve one holding and its covered profiles. Use the pol_ ID returned when creating the holding, rather than a catalogue product ID. A missing policy, or one outside this portfolio, returns 404.

Request

GET

/…/policies/:policyId

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

Response

{
  "success": true,
  "data": {
    "id": "pol_594a8ae4f0214901b51d75cd876293b0",
    "portfolio_id": "port_8f15e4c0904c4c118239c9628302c172",
    "directory_policy_id": 3025,
    "policy_name": null,
    "name": "Example Family Medical Plan",
    "policy_number": "MY-12345",
    "status": "active",
    "start_date": null,
    "end_date": null,
    "covered_persons": [
      {
        "id": "per_9341a218009c4ab6a8d7f3ca1583bf01",
        "name": "Ahmad",
        "relationship": "self"
      },
      {
        "id": "per_4f92f0a1d1704a06ba648e81ae7c9152",
        "name": "Aisha",
        "relationship": "spouse"
      }
    ],
    "created_at": 1792713600,
    "updated_at": 1792713600
  }
}

PATCH/v1/portfolios/:id/policies/:policyId

Update a holding

Update one or more policy attributes. Omitted fields stay unchanged; unknown attributes and empty updates are rejected. All covered profiles must belong to this portfolio. An invalid assignment rejects the entire update, including changes to policy fields.

Optional attributes

Name
directory_policy_id
Type
integer, string or null
Description
Change the linked product, or set to null to unlink it. The final record must still have a catalogue reference or a custom name.
Name
policy_name
Type
string or null
Description
Change the custom name or override. Set to null to use the linked catalogue name.
Name
policy_number
Type
string or null
Description
Change the policy number, or set to null to clear it.
Name
status
Type
string
Description
One of active, expired, cancelled, or unknown. Cannot be null.
Name
start_date
Type
date or null
Description
Change the start date, or set to null to clear it. Date order is checked against the resulting policy.
Name
end_date
Type
date or null
Description
Change the end date, or set to null to clear it.
Name
covered_person_ids
Type
array
Description
Replace the complete coverage set. Omit to keep existing assignments, or send [] to clear them. Duplicate IDs are normalized. Cannot be null.

Request

PATCH

/…/policies/:policyId

curl -X PATCH "https://api.insuredspeaks.com/v1/portfolios/$PORTFOLIO_ID/policies/$TRACKED_POLICY_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "policy_number": null,
  "covered_person_ids": [
    "per_4f92f0a1d1704a06ba648e81ae7c9152"
  ]
}'

Response

{
  "success": true,
  "data": {
    "id": "pol_594a8ae4f0214901b51d75cd876293b0",
    "portfolio_id": "port_8f15e4c0904c4c118239c9628302c172",
    "directory_policy_id": 3025,
    "policy_name": null,
    "name": "Example Family Medical Plan",
    "policy_number": null,
    "status": "active",
    "start_date": null,
    "end_date": null,
    "covered_persons": [
      {
        "id": "per_4f92f0a1d1704a06ba648e81ae7c9152",
        "name": "Aisha",
        "relationship": "spouse"
      }
    ],
    "created_at": 1792713600,
    "updated_at": 1792717200
  }
}

DELETE/v1/portfolios/:id/policies/:policyId

Delete a holding

Stop tracking a policy and remove its coverage assignments. The shared catalogue product and the portfolio's profiles are preserved. This request accepts no body.

Request

DELETE

/…/policies/:policyId

curl -X DELETE "https://api.insuredspeaks.com/v1/portfolios/$PORTFOLIO_ID/policies/$TRACKED_POLICY_ID" \
  -H "X-API-Key: $API_KEY"

Response

{
  "success": true,
  "message": "Resource deleted"
}