API
The portal exposes a small REST API that external systems can consume programmatically. All endpoints are secured with OAuth2 access tokens.
Where to find the API reference
The full, interactive API reference is at https://portal.cicops.ai/api-docs (opens in a new tab) (admin-authenticated).
The reference is generated from the live request specs, so it's always current.
Available endpoints (v1)
The current public API surface, under /api/v1:
| Endpoint | What it returns |
|---|---|
GET /api/v1/companies | List of companies the token's user has access to |
GET /api/v1/companies/:id | Single company detail |
GET /api/v1/companies/:id/playbook | The current playbook for a company |
GET /api/v1/inbound_numbers | Inbound numbers in scope |
GET /api/v1/profile | The authenticated user's profile |
Read-only at present. Write endpoints are not yet exposed publicly.
Authentication
The API uses OAuth2 (via Doorkeeper). Flow:
- Application registration. Engineering creates an OAuth application in the portal for your integration. You receive a
client_idandclient_secret. - Authorization. The integrator follows the OAuth2 authorization-code flow at the portal's authorization endpoint.
- Access token. The integrator exchanges the authorization code for an access token.
- API requests. Every API request includes
Authorization: Bearer <token>in the headers.
Tokens are scoped to specific permissions. Don't request more than you need.
Token lifecycle
- Access tokens expire (currently set per application). When yours expires, you'll receive a 401 — re-run the OAuth flow to get a fresh token.
- Refresh tokens are issued alongside access tokens and can be exchanged for a new access token without redoing the full flow.
- Tokens can be revoked by an admin at any time.
Rate limiting
The API does not currently enforce a rate limit. Be reasonable — if you start making thousands of requests per second, expect a conversation.
Versioning
The current version is v1. When breaking changes are needed, a v2 namespace will be introduced — v1 will continue to function for a deprecation window.
Non-breaking additions (new endpoints, new optional fields) are made within v1 without a version bump.
Getting an API integration set up
To start using the API:
- Email a CIC contact with your integration's purpose, the data you need, and a contact for ongoing coordination.
- Engineering registers the OAuth application and shares credentials with you securely.
- Test against the live endpoints (there's no separate sandbox today).
- Coordinate any change in scope through your CIC contact.
What the API doesn't (yet) do
- Webhooks for real-time events (planned)
- Write operations
- Bulk operations
- Direct call-recording downloads (recording URLs in responses are signed and time-limited)
If you need any of these, file a request through your CIC contact.
Next
- System Operations — admin-side view of API operations
- Security — OAuth token issuance and revocation