Who can use this feature?
Plan: Call Center AI
Managed from: Admin Portal
User type: Admin
The Krisp Portal API is a REST API that lets you programmatically manage your Krisp team. It is intended for admins managing large deployments where automating seat management, user provisioning, and usage monitoring would reduce manual overhead.
The API works for both device-based and email-based teams. The team type is determined by the API key you generate. No additional configuration is required.
Full endpoint reference and example requests are available in the Krisp Portal API Postman documentation.
Get your API key and secret
API credentials are generated per team in the Admin Portal. You need both the API key name and the secret to authenticate requests.
- In the Admin Portal, go to Settings >>> Team settings >>> Security.
-
Select API from the left menu.
- Click Create new API endpoint. A panel opens on the right.
-
Enter a name for the key in the Name of the key field, then click Create.
-
Copy both the API key name and the Secret key and store them securely. The secret is only shown once and cannot be retrieved after you close this panel.
Important
Store the secret key immediately after generation. It will not be shown again. If you lose it, you will need to delete the key and create a new one.
Rename or delete a key
To rename or delete an existing key, click on it in the API list. The edit panel opens on the right, where you can update the name or permanently delete the key.
Hint
Deleting a key immediately invalidates it. Any scripts or integrations using that key will stop working.
Authentication
The API uses HTTP Basic authentication. All requests must include an Authorization header with a Base64-encoded string of your API key name and secret, separated by a colon.
Header format:
Authorization: Basic base64(<api_key>:<secret>)
All requests must be made over HTTPS. Requests over plain HTTP and unauthenticated requests will fail.
Base URL:
https://teams.krisp.ai
Hint
The API supports both application/json and application/x-www-form-urlencoded content types for request bodies.
Available endpoints
Endpoints are grouped into three functional areas: seat management, user and device management, and analytics. The API key you use determines which team type (device or email) the operations apply to.
Seat management
These endpoints are available for both device-based and email-based teams.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/seats | Returns a paginated list of all seats in the team. Supports filtering by role, status, hostname, or nickname. Accepts page and perPage query parameters for pagination. |
| POST | /api/v1/seats | Adds the specified number of seats to the team. Requires a count body parameter. For credit card billing, the charge is prorated immediately. Not available for invoice-billed teams unless activity-based billing is enabled. |
| DELETE | /api/v1/seats/:id | Permanently deletes the specified seat. The seat must be unassigned before deletion. Remove the user or block the device first. |
User and device management
The endpoints available depend on the team type associated with the API key. Device teams are only supported on Windows.
| Method | Endpoint | Description | Team type |
|---|---|---|---|
| POST | /api/v1/team/invite | Sends an email invitation to a new team member. Requires an email body parameter. If a free seat is available, the user is automatically assigned to it upon accepting. Returns an error if no free seats exist. | |
| DELETE | /api/v1/seats/unassign/:id | Removes the user from a seat, freeing it for reassignment. The seat itself is not deleted. | |
| PUT | /api/v1/seats/block/:id | Blocks the device associated with the specified seat, preventing it from logging in to the team again. The seat is automatically unassigned upon blocking. | Device |
| GET | /api/v1/team/block/list | Returns a paginated list of all blocked devices in the team. Supports filtering by device name using the qs query parameter. Accepts page and perPage for pagination. | Device |
| PUT | /api/v1/team/device/unblock/:id | Removes a device from the block list. The :id parameter is the block list entry ID, not the seat ID. Once unblocked, the device can log in again if a seat is available. | Device |
Analytics
These endpoints are available for both team types.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/analytics/monitoring | Returns a paginated list of live device events from Live Monitoring, including device state (online, in_call, offline, or unhealthy, unavailable), user info, call status, and metadata. |
| GET | /api/v1/analytics/usage | Returns usage data broken down by user, username, device, or language over a specified date range and cadence (daily, weekly, or monthly). Includes microphone and speaker call durations and feature usage durations. Data is available for the past 4 months. |
Rate limiting
Rate limiting is applied per IP address. If the request threshold is exceeded, all requests from that IP are blocked for a set period and the API returns HTTP 429. The default configuration is 700 requests per minute, with a 1-hour blocking period.
Response codes
| Code | Meaning | HTTP status |
|---|---|---|
| 0 | Success | 200 |
| 1 | Authentication failure | 401 |
| 1015 | Not found | 400 |
| 1016 | Validation error | 400 |
| 1023 | Forbidden | 400 |
| 1026 | Too many requests | 429 |
| 10000 | Internal server error | 500 |
Error codes
When a request fails, the response body includes an error_code field with additional context on why the request failed.
| Error code | Situation | UI message |
|---|---|---|
| AUTH_HEADER_MISSING | Make sure to include the authorization header in request headers. | Problem during authentication. |
| AUTH_HEADER_WRONG_FORMAT | Only Basic and Bearer tokens are supported. | Problem during authentication. |
| AUTH_BASIC_ONLY | Happens when the authorization header is not Basic. | Problem during authentication. |
| AUTH_BASIC_INVALID_TOKEN | Happens when the Basic auth credentials are wrong. | Problem during authentication. |
| VALIDATION_ERROR | Happens when the API receives inputs from a client that are unexpected or wrong. | Something went wrong. |
| NOT_PERMITTED_ADD_SEATS | Happens when the team payment type is invoice. | Not enough permissions. |
| SEAT_NOT_FOUND | Happens when the seat is not found. | Seat not found. |
| NOT_PERMITTED_CHANGE_SEAT_STATUS | Happens when the seat type is not device. | Not enough permissions. |
| SEAT_IS_EMPTY | Happens when trying to change an empty seat's status. | Seat is empty. |
| SEAT_IS_NOT_EMPTY | Happens when trying to delete a seat that already has a user assigned. | Seat is in use. Remove the assigned user from the seat before deleting it. |
| NOT_PERMITTED_DELETE_SEAT | Happens when the team payment type is invoice. | Not enough permissions. |
| NOT_PERMITTED_INVITE_USER | Happens when access is denied while inviting new members. | Not enough permissions. |
| NOT_EMPTY_SEAT | Happens when trying to log in but there are no empty seats. | You don't have empty seats. |
| ALREADY_MEMBER | User is already assigned to another seat within the same team. | User is already a team member. |
| NOT_PERMITTED_UNASSIGN_LAST_ADMINISTRATOR_SEAT | Not enough permissions. | Happens when you try to unassign the last administrator in the team. |
Hint
For a full breakdown of response fields, possible values, and example payloads for each endpoint, see the Krisp Portal API Postman documentation.
Versioning
The API version is included in the URL path (e.g., /api/v1/). A new version is published only for breaking changes: changes to response attribute names or logic, endpoint renames, removal of attributes, or deprecated endpoints.
Adding new attributes to existing responses is not considered a breaking change and does not result in a new version.