InsuredSpeaks

Profiles

Profiles identify who is covered by the insurance in a portfolio. On this page, we’ll look at how to add family members, update their details, and remove them.

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.

Use the portfolio ID returned by Create a portfolio as PORTFOLIO_ID in the examples.

Try these requests in the playground. Sign in to execute requests using your own account.

The Profile Model

Each profile belongs to one portfolio and can be covered by several tracked policies. Every portfolio has exactly one self profile. You can rename self, but cannot delete it or change its relationship.

Properties

  • Name
    id
    Type
    string
    Description

    The opaque profile ID, prefixed with per_ and followed by 32 hexadecimal characters.

  • Name
    portfolio_id
    Type
    string
    Description

    The port_ ID of the portfolio this profile belongs to.

  • Name
    full_name
    Type
    string
    Description

    The profile name. Trimmed, nonblank, and at most 255 characters.

  • Name
    relationship
    Type
    string
    Description

    One of 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/people

List all profiles

Retrieve a paginated list of profiles in this portfolio, ordered newest first. This includes the automatically created self profile. Copy returned IDs when assigning policy coverage.

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
/…/people
curl -G "https://api.insuredspeaks.com/v1/portfolios/$PORTFOLIO_ID/people" \
  -H "X-API-Key: $API_KEY" \
  -d page=1 \
  -d limit=20

Response

{
  "success": true,
  "data": [
    {
      "id": "per_4f92f0a1d1704a06ba648e81ae7c9152",
      "portfolio_id": "port_8f15e4c0904c4c118239c9628302c172",
      "full_name": "Aisha",
      "relationship": "spouse",
      "created_at": 1792713600,
      "updated_at": 1792713600
    },
    {
      "id": "per_9341a218009c4ab6a8d7f3ca1583bf01",
      "portfolio_id": "port_8f15e4c0904c4c118239c9628302c172",
      "full_name": "Ahmad",
      "relationship": "self",
      "created_at": 1792713600,
      "updated_at": 1792713600
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}
POST/v1/portfolios/:id/people

Create a profile

Add a profile to the portfolio. For example, add Aisha as a spouse, then add a son with the child relationship. Adding a profile does not automatically assign coverage to any policies. Returns 201 on success.

Required attributes

  • Name
    full_name
    Type
    string
    Description

    A nonblank name, up to 255 characters.

  • Name
    relationship
    Type
    string
    Description

    One of spouse, child, parent, or other. Self is created automatically with the portfolio.

Request

POST
/…/people
curl "https://api.insuredspeaks.com/v1/portfolios/$PORTFOLIO_ID/people" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "full_name": "Aisha",
  "relationship": "spouse"
}'

Response

{
  "success": true,
  "data": {
    "id": "per_4f92f0a1d1704a06ba648e81ae7c9152",
    "portfolio_id": "port_8f15e4c0904c4c118239c9628302c172",
    "full_name": "Aisha",
    "relationship": "spouse",
    "created_at": 1792713600,
    "updated_at": 1792713600
  }
}
PATCH/v1/portfolios/:id/people/:personId

Update a profile

Update a profile name or relationship. Supply at least one attribute; omitted attributes stay unchanged. You may rename self, but changes to or from the self relationship are rejected.

Optional attributes

  • Name
    full_name
    Type
    string
    Description

    The updated name. Must be nonblank and at most 255 characters.

  • Name
    relationship
    Type
    string
    Description

    The updated relationship. Allowed values are spouse, child, parent, and other; an existing self relationship can only remain self.

Request

PATCH
/…/people/:personId
curl -X PATCH "https://api.insuredspeaks.com/v1/portfolios/$PORTFOLIO_ID/people/$PERSON_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "full_name": "Aisha Ahmad"
}'

Response

{
  "success": true,
  "data": {
    "id": "per_4f92f0a1d1704a06ba648e81ae7c9152",
    "portfolio_id": "port_8f15e4c0904c4c118239c9628302c172",
    "full_name": "Aisha Ahmad",
    "relationship": "spouse",
    "created_at": 1792713600,
    "updated_at": 1792717200
  }
}
DELETE/v1/portfolios/:id/people/:personId

Delete a profile

Remove a profile and its coverage assignments. The policies it covered remain in the portfolio. Deleting self returns 400; deleting the whole portfolio removes self together with its other contents. This request accepts no body.

Request

DELETE
/…/people/:personId
curl -X DELETE "https://api.insuredspeaks.com/v1/portfolios/$PORTFOLIO_ID/people/$PERSON_ID" \
  -H "X-API-Key: $API_KEY"

Response

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

Was this page helpful?