> 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.
```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.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","maxProperties":20,"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.
```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.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/ScalarMap"},"contacts":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/ContactInput"}}}},"ScalarMap":{"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/ScalarMap"}}},"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"}}},"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.
```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.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","maxProperties":20,"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.
```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.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","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"},"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"}}},"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","maxProperties":20,"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"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://getubic.gitbook.io/ubic-partner-api/sessions.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.