First create a key under Settings > Integrations > Ubic API. The key is linked to your workspace and must never be embedded in a browser-based application.
The base URL is https://app.getubic.com/api/partner/v1.
Add the key to every request with the Authorization: Bearer YOUR_API_KEY header. For requests with a JSON body, also add Content-Type: application/json.
A replaced or disabled key stops working immediately. All returned data remains restricted to the workspace linked to the key.
Create a session with POST /sessions. The request body must contain:
name: the session name;
owner_email: the email address of a user who belongs to the workspace;
contacts: between 1 and 200 contacts, each with at least phone;
either external_reference or the Idempotency-Key header to prevent the same session from being created twice;
optionally, metadata and contact details: external_id, first_name, last_name, email, company, job_title, and custom_fields.
For example, a session can use July campaign as its name, the agent’s email address as owner_email, and campaign-2026-07 as external_reference. Each object in contacts then contains the phone number and the available lead information.
The response includes the session id and open_url, which the agent can open in Ubic to start calling. The API prepares the session, but it never starts, controls, or ends calls on behalf of the signed-in agent.
Then use:
GET /sessions to list sessions, with created_since, page, and per_page;
GET /sessions/{id}/contacts to retrieve contacts in a session;
GET /sessions/{id}/calls to retrieve calls that were actually started, with since, page, and per_page.
created_since and since accept an ISO 8601 datetime with a timezone. Pagination contains page, per_page, and total. The default page size is 50 and the maximum is 100. Date filters are inclusive, so deduplicate results using their id field.
Contacts include identity, company, phone, email, note, custom fields, calling status, and current qualification. Calls also include timestamps, duration, agent, direction, and the result saved when the call was qualified.
Technical call statuses are queued, sent, received, delivered, initiated, ringing, in-progress, completed, failed, busy, no-answer, and canceled.
Contact calling statuses are not_started, ringing, connected, completed, deferred, and failed. Business qualifications and their labels depend on the statuses configured in the workspace. A meeting is identified through is_conversion and can be completed with custom fields, for example its date or external identifier.
Add include_transcriptions=true to request the transcription and include_recordings=true to retrieve recording metadata. The API does not return the audio file URL.
An API key with task read access can use:
GET /tasks to list workspace tasks, with updated_since, cursor, and per_page;
GET /tasks/{id} to retrieve one task.
updated_since accepts an ISO 8601 datetime with a timezone. To load the next page, send pagination.next_cursor back through the cursor parameter until it is empty. The cursor automatically retains the initial filter. A task changed during pagination may appear again; deduplicate it using its id.
Each task includes its ID, status, type, note, due date, creation and update dates, assigned agent, and the main details of the related lead.
To create a task, use POST /tasks with:
lead_id: the lead's Ubic ID;
due_at: the due date and time in ISO 8601 format with a timezone;
either external_reference or the Idempotency-Key header to prevent duplicate tasks;
optionally, assignee_email, type, and note.
The lead and assigned agent must belong to the API key's workspace. Without assignee_email, Ubic assigns the task to the owner of the lead's list. The request is rejected if no agent can be determined.
The type must match a value configured in the workspace. When omitted, Ubic uses the default task type. If the same reference is retried after a network failure, Ubic returns the existing task without creating a duplicate.
Reading requires the tasks:read permission and creation requires tasks:write. This first API version supports listing, reading, and creating tasks; tasks are still updated and deleted from Ubic.
If your key was created before tasks were added to the API, replace it under Settings > Integrations > Ubic API to grant these permissions.
Session or task creation: 30 requests per minute, per API key and IP address.
Reading sessions, contacts, calls, and tasks: 120 requests per minute, per API key and IP address.
When a limit is exceeded, the API returns 429 with a Retry-After header. Wait for the indicated number of seconds before retrying.
Other main status codes are 400 for invalid JSON, 401 for a missing or invalid key, 403 for a missing permission, 404 for an unknown resource, 409 for an idempotency conflict, and 422 for invalid data or parameters.
The full contract, response models, and available fields are also available in the Ubic Partner API developer documentation.
