Client Portals

Client portals give external viewers a branded, read-only call-history experience for a selected set of agents. The management API is organization scoped and requires an admin or owner authenticated with an sk_live_ key. Viewer login, sessions, call browsing, transcripts, and audio use the hosted portal’s separate viewer authentication. They are not sk_live_ integration endpoints.

Endpoints

Method	Path	Description
`GET`	`/v1/client-portals`	List portals.
`POST`	`/v1/client-portals`	Create a portal.
`GET`	`/v1/client-portals/{portal_id}`	Retrieve a portal.
`PATCH`	`/v1/client-portals/{portal_id}`	Update details, active state, branding color, or agents.
`DELETE`	`/v1/client-portals/{portal_id}`	Permanently delete a portal.
`POST`	`/v1/client-portals/{portal_id}/logo`	Upload or replace a logo.
`DELETE`	`/v1/client-portals/{portal_id}/logo`	Remove the logo.
`GET` / `POST`	`/v1/client-portals/{portal_id}/viewers`	List or add viewers.
`PATCH` / `DELETE`	`/v1/client-portals/{portal_id}/viewers/{viewer_id}`	Activate/deactivate or delete a viewer.
`GET` / `POST`	`/v1/client-portals/{portal_id}/domains`	List or add custom domains.
`DELETE`	`/v1/client-portals/{portal_id}/domains/{domain_id}`	Remove a custom domain.
`POST`	`/v1/client-portals/{portal_id}/domains/{domain_id}/verify`	Check the ownership TXT record.

Portal object

{
  "id": 18,
  "name": "Acme Dental",
  "slug": "acme-dental",
  "accent_color": "#2e8fff",
  "is_active": true,
  "logo_url": "https://…",
  "agent_ids": [12, 19],
  "agent_count": 2,
  "viewer_count": 3,
  "calls_last_30d": 147,
  "created_at": "2026-07-16T18:24:10.113Z",
  "updated_at": "2026-08-05T09:40:12.551Z"
}

Field	Type	Description
`id`	integer	Portal id used by management endpoints.
`name`	string	Client-facing name, maximum 255 characters.
`slug`	string	Globally unique hosted URL slug, maximum 100 characters.
`accent_color`	string	Empty for the default, or a full six-digit hex color.
`is_active`	boolean	Inactive portals cannot be opened by viewers.
`logo_url`	string \| null	Temporary or hosted URL for the current logo.
`agent_ids`	array of integer	Agents whose calls are in the portal scope.
`agent_count`, `viewer_count`	integer	Current related-resource counts.
`calls_last_30d`	integer	Calls from assigned agents in the preceding 30 days.
`created_at`, `updated_at`	timestamp	ISO 8601 timestamps.

List and create portals

curl https://api.thunderphone.com/v1/client-portals \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

The list is sorted by name, then id.

curl -X POST https://api.thunderphone.com/v1/client-portals \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Dental","slug":"acme-dental"}'

Field	Required	Validation
`name`	yes	Non-empty after trimming; maximum 255 characters.
`slug`	no	Maximum 100 characters. Lowercase letters, numbers, and single hyphens only; must be unique and not reserved. A unique slug is generated from `name` when omitted.

Returns 201 Created with the portal object.

Retrieve, update, and delete

PATCH /v1/client-portals/{portal_id} accepts any subset of:

Field	Type	Behavior
`name`	string	Replaces the client-facing name.
`slug`	string	Replaces the hosted URL slug after uniqueness validation.
`is_active`	boolean	Enables or disables all viewer access.
`accent_color`	string	Six-digit hex such as `#2e8fff`, or `""` for the default.
`agent_ids`	array of integer	Replaces the complete assigned-agent set. Duplicates are removed; every id must belong to the organization. Use `[]` for no visible calls.

curl -X PATCH https://api.thunderphone.com/v1/client-portals/18 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_ids":[12,19],"accent_color":"#2e8fff"}'

DELETE returns 204 No Content and permanently removes the portal, its viewers, domain records, and logo reference. It does not delete agents or calls.

Upload or remove a logo

Upload multipart form field file. The accepted formats are PNG, JPEG, and WebP, with a maximum size of 2 MB. The file contents must match the declared MIME type.

curl -X POST https://api.thunderphone.com/v1/client-portals/18/logo \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -F "file=@acme-logo.png"

The response is {"logo_url":"https://…"}. Uploading a new logo replaces the old one. DELETE removes it and returns 204.

Viewers

The viewer object is:

{
  "id": 31,
  "email": "client@example.com",
  "is_active": true,
  "has_password": false,
  "created_at": "2026-08-05T09:40:12.551Z",
  "updated_at": "2026-08-05T09:40:12.551Z"
}

Add a unique email address:

curl -X POST https://api.thunderphone.com/v1/client-portals/18/viewers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"client@example.com"}'

Returns 201. PATCH accepts only is_active; setting it to false blocks login without deleting the viewer. DELETE returns 204.

Custom domains

Create a domain with its hostname only:

curl -X POST https://api.thunderphone.com/v1/client-portals/18/domains \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"calls.client.com"}'

Returns 201:

{
  "id": 7,
  "hostname": "calls.client.com",
  "verification_token": "tp_verify_…",
  "status": "pending",
  "verified_at": null,
  "cname_record": {
    "name": "calls.client.com",
    "value": "CNAME_TARGET_FROM_RESPONSE"
  }
}

The hostname is normalized, can be at most 253 characters, and must be unique across portals. Add the returned CNAME, then add this TXT record:

Type	Name	Value
TXT	`_tp-portal-verify.calls.client.com`	The returned `verification_token`.

Check it with:

curl -X POST https://api.thunderphone.com/v1/client-portals/18/domains/7/verify \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

On success, the domain object has status: "active" and verified_at. While the TXT record is not visible, the response remains pending and repeats the expected TXT and CNAME records. DNS propagation can take several minutes. DELETE /domains/{domain_id} returns 204 and releases the hostname for reuse.

Errors and authorization

Status	Meaning
`400`	Invalid slug, color, agent list, upload, email, or hostname.
`401`	Missing or invalid API key.
`403`	The authenticated user or key is not authorized for admin management.
`404`	Portal or nested resource is outside the current organization or absent.
`204`	Successful deletion.

For the dashboard workflow and viewer experience, see Client portals.

Overview

Organizations

Agents

Phone Numbers

Calls

Billing

Developer

Endpoints

Portal object

List and create portals

Retrieve, update, and delete

Upload or remove a logo

Viewers

Custom domains

Errors and authorization

​Endpoints

​Portal object

​List and create portals

​Retrieve, update, and delete

​Upload or remove a logo

​Viewers

​Custom domains

​Errors and authorization

Endpoints

Portal object

List and create portals

Retrieve, update, and delete

Upload or remove a logo

Viewers

Custom domains

Errors and authorization