---
title: "Integrate Ubic with the Partner API"
description: "This article is for the administrator or developer connecting a business tool to Ubic. The Partner API can prepare calling sessions and then retrieve leads, calls, and their follow-up."
url: https://support.getubic.com/en/articles/53-integrate-ubic-with-the-partner-api
collection: "Connect your team's tools"
updated: 2026-09-26
language: en
alternates: [fr]
---

# Integrate Ubic with the Partner API

This article is for the administrator or developer connecting a business tool to Ubic. The Partner API can prepare calling sessions and then retrieve leads, calls, and their follow-up.

## 1\. Authenticate requests

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.

## 2\. Prepare a session and read its data

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.

## 3\. Create and retrieve tasks

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.

## 4\. Limits and errors

-   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](https://getubic.gitbook.io/ubic-partner-api).

## Related articles

> [**Connect a tool to Ubic with an API key**](https://support.getubic.com/en/articles/52-connect-a-tool-to-ubic-with-an-api-key.md)

> [**Start a calling session**](https://support.getubic.com/en/articles/1-start-a-calling-session.md)

> [**Find a call in the history**](https://support.getubic.com/en/articles/4-find-a-call-in-the-history.md)
