> For the complete documentation index, see [llms.txt](https://getubic.gitbook.io/ubic-partner-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://getubic.gitbook.io/ubic-partner-api/sessions.md).

# Sessions

## List prepared sessions in the API key workspace

> Requires \`calls:read\`. Sessions remain visible after API key rotation.\
> Results are ordered by \`created\_at\`, then \`id\`, ascending.\
> Rate limit: 120 requests per minute, per API key and IP.<br>

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.3.0"},"tags":[{"name":"Sessions"}],"servers":[{"url":"https://app.getubic.com/api/partner/v1"}],"security":[{"partnerApiKey":[]}],"components":{"securitySchemes":{"partnerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ubic_pk"}},"parameters":{"Page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"PerPage":{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}},"schemas":{"SessionPage":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Session"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Session":{"type":"object","required":["id","status","name","lead_list_id","contacts_count","metadata","open_url","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"external_reference":{"type":["string","null"]},"status":{"type":"string","enum":["ready"]},"name":{"type":"string"},"lead_list_id":{"type":"string","format":"uuid"},"owner_email":{"type":["string","null"],"format":"email"},"contacts_count":{"type":"integer"},"metadata":{"$ref":"#/components/schemas/ScalarMap"},"open_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"}}},"ScalarMap":{"type":"object","additionalProperties":{"type":["string","number","integer","boolean","null"]}},"Pagination":{"type":"object","required":["page","per_page","total"],"properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Missing scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Invalid payload or query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests for this API key and IP.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/sessions":{"get":{"tags":["Sessions"],"operationId":"listPartnerSessions","summary":"List prepared sessions in the API key workspace","description":"Requires `calls:read`. Sessions remain visible after API key rotation.\nResults are ordered by `created_at`, then `id`, ascending.\nRate limit: 120 requests per minute, per API key and IP.\n","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"},{"name":"created_since","in":"query","required":false,"description":"Inclusive ISO-8601 filter on `created_at`. A timezone is required; deduplicate on session `id`.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Prepared sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```

## Create a prepared calling session

> Requires \`sessions:write\`. Creates a lead list and contacts, but no live\
> call session or call attempts. Either \`Idempotency-Key\` or\
> \`external\_reference\` is required. Rate limit: 30 requests per minute,\
> per API key and IP.<br>

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.3.0"},"tags":[{"name":"Sessions"}],"servers":[{"url":"https://app.getubic.com/api/partner/v1"}],"security":[{"partnerApiKey":[]}],"components":{"securitySchemes":{"partnerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ubic_pk"}},"schemas":{"CreateSessionRequest":{"type":"object","additionalProperties":false,"required":["name","owner_email","contacts"],"properties":{"name":{"type":"string","maxLength":120},"owner_email":{"type":"string","format":"email","maxLength":180},"external_reference":{"type":"string","maxLength":255},"metadata":{"$ref":"#/components/schemas/InputScalarMap"},"contacts":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/ContactInput"}}}},"InputScalarMap":{"type":"object","maxProperties":20,"additionalProperties":{"type":["string","number","integer","boolean","null"]}},"ContactInput":{"type":"object","additionalProperties":false,"required":["phone"],"properties":{"phone":{"type":"string","maxLength":30},"external_id":{"type":"string","maxLength":255},"first_name":{"type":"string","maxLength":255},"last_name":{"type":"string","maxLength":255},"email":{"type":"string","format":"email","maxLength":255},"company":{"type":"string","maxLength":255},"job_title":{"type":"string","maxLength":255},"custom_fields":{"description":"Keys must match active lead data fields configured in the Ubic workspace. Workspace custom actions are not lead data and are rejected. Values must match the field type and configured choices.","$ref":"#/components/schemas/InputScalarMap"}}},"Session":{"type":"object","required":["id","status","name","lead_list_id","contacts_count","metadata","open_url","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"external_reference":{"type":["string","null"]},"status":{"type":"string","enum":["ready"]},"name":{"type":"string"},"lead_list_id":{"type":"string","format":"uuid"},"owner_email":{"type":["string","null"],"format":"email"},"contacts_count":{"type":"integer"},"metadata":{"$ref":"#/components/schemas/ScalarMap"},"open_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"}}},"ScalarMap":{"type":"object","additionalProperties":{"type":["string","number","integer","boolean","null"]}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Missing scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Idempotency key and external reference identify different resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Invalid payload or query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests for this API key and IP.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/sessions":{"post":{"tags":["Sessions"],"operationId":"createPartnerSession","summary":"Create a prepared calling session","description":"Requires `sessions:write`. Creates a lead list and contacts, but no live\ncall session or call attempts. Either `Idempotency-Key` or\n`external_reference` is required. Rate limit: 30 requests per minute,\nper API key and IP.\n","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionRequest"}}}},"responses":{"201":{"description":"Session created or returned idempotently.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```

## List contacts in a prepared session

> Requires \`calls:read\`. Rate limit: 120 requests per minute, per API key\
> and IP.<br>

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.3.0"},"tags":[{"name":"Sessions"}],"servers":[{"url":"https://app.getubic.com/api/partner/v1"}],"security":[{"partnerApiKey":[]}],"components":{"securitySchemes":{"partnerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ubic_pk"}},"parameters":{"SessionId":{"name":"id","in":"path","required":true,"description":"Partner API session UUID.","schema":{"type":"string","format":"uuid"}},"Page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"PerPage":{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}},"schemas":{"ContactPage":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Contact":{"type":"object","required":["id","phone","is_conversion","call_status","custom_fields"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":["string","null"]},"phone":{"type":"string"},"email":{"type":["string","null"],"format":"email"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"company":{"type":["string","null"]},"job_title":{"type":["string","null"]},"lead_status":{"type":["string","null"]},"lead_status_label":{"type":["string","null"]},"is_conversion":{"type":"boolean"},"call_status":{"type":"string","enum":["not_started","ringing","connected","completed","deferred","failed"]},"note":{"type":["string","null"]},"custom_fields":{"description":"Workspace custom fields, including optional meeting details configured by the workspace.","$ref":"#/components/schemas/ScalarMap"},"last_called_at":{"type":["string","null"],"format":"date-time"}}},"ScalarMap":{"type":"object","additionalProperties":{"type":["string","number","integer","boolean","null"]}},"Pagination":{"type":"object","required":["page","per_page","total"],"properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Missing scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Requested resource not found in the API key workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Invalid payload or query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests for this API key and IP.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/sessions/{id}/contacts":{"get":{"tags":["Sessions"],"operationId":"listPartnerSessionContacts","summary":"List contacts in a prepared session","description":"Requires `calls:read`. Rate limit: 120 requests per minute, per API key\nand IP.\n","parameters":[{"$ref":"#/components/parameters/SessionId"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"Session contacts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```

## List calls made from a prepared session

> Requires \`calls:read\`. Only calls actually started by an agent in Ubic\
> are returned. Results are ordered by \`started\_at\`, then \`id\`, ascending.\
> Rate limit: 120 requests per minute, per API key and IP.<br>

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.3.0"},"tags":[{"name":"Sessions"}],"servers":[{"url":"https://app.getubic.com/api/partner/v1"}],"security":[{"partnerApiKey":[]}],"components":{"securitySchemes":{"partnerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ubic_pk"}},"parameters":{"SessionId":{"name":"id","in":"path","required":true,"description":"Partner API session UUID.","schema":{"type":"string","format":"uuid"}},"Page":{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},"PerPage":{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}},"schemas":{"CallPage":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Call"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Call":{"type":"object","required":["id","status","channel","direction","duration_seconds","agent","list","lead","result"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/AttemptStatus"},"channel":{"type":"string","enum":["call"]},"direction":{"type":"string","enum":["outbound","inbound"]},"started_at":{"type":["string","null"],"format":"date-time"},"ended_at":{"type":["string","null"],"format":"date-time"},"duration_seconds":{"type":"integer"},"agent":{"$ref":"#/components/schemas/Agent"},"list":{"oneOf":[{"$ref":"#/components/schemas/CallList"},{"type":"null"}],"description":"Origin list for the call, or null when the list no longer exists."},"lead":{"$ref":"#/components/schemas/Contact"},"result":{"$ref":"#/components/schemas/CallResult"},"recording":{"$ref":"#/components/schemas/Recording"},"transcription":{"$ref":"#/components/schemas/Transcription"}}},"AttemptStatus":{"type":"string","enum":["queued","sent","received","delivered","initiated","ringing","in-progress","completed","failed","busy","no-answer","canceled"]},"Agent":{"type":"object","required":["id","email"],"properties":{"id":{"type":["string","null"],"format":"uuid"},"email":{"type":["string","null"],"format":"email"}}},"CallList":{"type":"object","required":["id","name","external_reference"],"properties":{"id":{"type":"string","format":"uuid","description":"Stable Ubic list identifier."},"name":{"type":"string","description":"Current display name of the origin list."},"external_reference":{"type":["string","null"],"description":"Provider list identifier when the source integration supplies one."}}},"Contact":{"type":"object","required":["id","phone","is_conversion","call_status","custom_fields"],"properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":["string","null"]},"phone":{"type":"string"},"email":{"type":["string","null"],"format":"email"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"company":{"type":["string","null"]},"job_title":{"type":["string","null"]},"lead_status":{"type":["string","null"]},"lead_status_label":{"type":["string","null"]},"is_conversion":{"type":"boolean"},"call_status":{"type":"string","enum":["not_started","ringing","connected","completed","deferred","failed"]},"note":{"type":["string","null"]},"custom_fields":{"description":"Workspace custom fields, including optional meeting details configured by the workspace.","$ref":"#/components/schemas/ScalarMap"},"last_called_at":{"type":["string","null"],"format":"date-time"}}},"ScalarMap":{"type":"object","additionalProperties":{"type":["string","number","integer","boolean","null"]}},"CallResult":{"type":"object","required":["attempt_status","is_conversion"],"properties":{"attempt_status":{"$ref":"#/components/schemas/AttemptStatus"},"qualification_status":{"type":["string","null"],"description":"Workspace-specific prospect qualification identifier."},"qualification_label":{"type":["string","null"],"description":"Workspace-specific prospect qualification label."},"qualified_at":{"type":["string","null"],"format":"date-time"},"current_lead_status":{"type":["string","null"]},"current_lead_status_label":{"type":["string","null"]},"is_conversion":{"type":"boolean","description":"Whether the current workspace qualification is configured as a conversion."}}},"Recording":{"type":"object","description":"Present only when requested with `recordings:read`. No audio URL is returned.","required":["available"],"properties":{"available":{"type":"boolean"},"status":{"type":["string","null"]},"duration_seconds":{"type":["integer","null"]}}},"Transcription":{"type":"object","description":"Present only when requested with `transcriptions:read`.","properties":{"status":{"type":["string","null"]},"text":{"type":["string","null"]},"completed_at":{"type":["string","null"],"format":"date-time"}}},"Pagination":{"type":"object","required":["page","per_page","total"],"properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Missing scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Requested resource not found in the API key workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Invalid payload or query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests for this API key and IP.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/sessions/{id}/calls":{"get":{"tags":["Sessions"],"operationId":"listPartnerSessionCalls","summary":"List calls made from a prepared session","description":"Requires `calls:read`. Only calls actually started by an agent in Ubic\nare returned. Results are ordered by `started_at`, then `id`, ascending.\nRate limit: 120 requests per minute, per API key and IP.\n","parameters":[{"$ref":"#/components/parameters/SessionId"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"},{"name":"since","in":"query","required":false,"description":"Inclusive ISO-8601 filter on `started_at`. Deduplicate on call `id`.","schema":{"type":"string","format":"date-time"}},{"name":"include_recordings","in":"query","required":false,"description":"Requires `recordings:read`. Returns metadata only, without an audio URL.","schema":{"type":"boolean","default":false}},{"name":"include_transcriptions","in":"query","required":false,"description":"Requires `transcriptions:read`.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Calls associated with the session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```
