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.
To retrieve all call history for a period, use GET /calls with the required inclusive started_from and exclusive started_until parameters. The range is limited to 31 days and requires the workspace_calls:read permission. Each call also includes list, with the stable Ubic ID, current name, and external reference of its origin list when available. list is null if that list no longer exists.
To include calls without an identifiable contact, use GET /api/partner/v2/calls with the same key, permissions, and parameters. This response adds caller_identity; lead and list are null for an unidentified call. Track it using the call id, without creating an artificial lead. V1 preserves historical responses while a lead remains linked to the call. If a page contains a call without a lead, it returns 409 api_version_required and must be read through V2. Other routes remain on V1.
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 (`type_id` and label), note, due date, creation and update dates, assigned agent, and the main details of the related lead. `type_id` is `null` if the type has been removed from the workspace settings.
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_id, 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.
A task must belong to a real contact. An old shared record for unidentified callers is rejected with 422 identified_contact_required; an identified contact without a phone number remains eligible.
To find the right identifier, call GET /task-types with a key that has tasks:write permission. The response lists each configured type's id, technical value, label, and default flag. Send its id as type_id (for example, `"type_id": 2`); Make can also send a decimal string. Do not send a label such as `No-show` as the type identifier.
The existing type field still accepts the technical value for older integrations. Do not send type and type_id together. If both are omitted, Ubic uses the workspace default. Keep the same field and value when retrying a request with the same reference. 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 or a read that requires V2, 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.
