InsuredSpeaks

Portfolios

Portfolios organize the insurance you track and the profiles it covers. On this page, we’ll look at how to create, retrieve, update, and delete 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.

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

The Portfolio Model

A portfolio belongs to one user and has its own list of profiles and tracked policies. Creating a portfolio also creates one editable self profile, using your profile name or “Me”.

Properties

  • Name
    id
    Type
    string
    Description

    The opaque portfolio ID, prefixed with port_ and followed by 32 hexadecimal characters.

  • Name
    name
    Type
    string
    Description

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

  • 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

List all portfolios

Retrieve a paginated list of your portfolios, ordered newest first. Each response includes pagination metadata; pages beyond the available results return an empty list.

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

Response

{
  "success": true,
  "data": [
    {
      "id": "port_8f15e4c0904c4c118239c9628302c172",
      "name": "My Family Insurance",
      "created_at": 1792713600,
      "updated_at": 1792713600
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
POST/v1/portfolios

Create a portfolio

Create a portfolio and its self profile together. The response contains the portfolio; use List all profiles to find the self profile's ID. Returns 201 on success.

Required attributes

  • Name
    name
    Type
    string
    Description

    A nonblank portfolio name, up to 255 characters.

Request

POST
/v1/portfolios
curl "https://api.insuredspeaks.com/v1/portfolios" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My Family Insurance"
}'

Response

{
  "success": true,
  "data": {
    "id": "port_8f15e4c0904c4c118239c9628302c172",
    "name": "My Family Insurance",
    "created_at": 1792713600,
    "updated_at": 1792713600
  }
}
GET/v1/portfolios/:id

Retrieve a portfolio

Retrieve a portfolio by its ID. Use the separate profiles and tracked policy endpoints to browse its contents. Returns 404 if the portfolio does not exist or belongs to another user.

Request

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

Response

{
  "success": true,
  "data": {
    "id": "port_8f15e4c0904c4c118239c9628302c172",
    "name": "My Family Insurance",
    "created_at": 1792713600,
    "updated_at": 1792713600
  }
}
PATCH/v1/portfolios/:id

Update a portfolio

Rename an existing portfolio. Its owner, profiles, and tracked policies remain the same. Returns the updated portfolio.

Required attributes

  • Name
    name
    Type
    string
    Description

    The new portfolio name. Must be nonblank and at most 255 characters.

Request

PATCH
/v1/portfolios/:id
curl -X PATCH "https://api.insuredspeaks.com/v1/portfolios/$PORTFOLIO_ID" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Family Protection"
}'

Response

{
  "success": true,
  "data": {
    "id": "port_8f15e4c0904c4c118239c9628302c172",
    "name": "Family Protection",
    "created_at": 1792713600,
    "updated_at": 1792717200
  }
}
DELETE/v1/portfolios/:id

Delete a portfolio

Delete a portfolio and all of its profiles, tracked policies, and coverage assignments. This includes its self profile. Shared catalogue products are preserved. This request accepts no body.

Request

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

Response

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

Errors

Portfolio endpoints return success: false and a message when a request fails. Invalid input returns 400, invalid authentication 401, and missing or inaccessible resources 404. Conflicts return 409, oversized bodies 413, and API-key rate limits 429. Server failures return 500 or 503. Responses use Cache-Control: no-store.

Was this page helpful?