> 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/models.md).

# Models

## The CreateSessionRequest object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"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"}}}}}}
```

## The ContactInput object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"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"}}},"ScalarMap":{"type":"object","maxProperties":20,"additionalProperties":{"type":["string","number","integer","boolean","null"]}}}}}
```

## The CreateTaskRequest object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"CreateTaskRequest":{"type":"object","additionalProperties":false,"required":["lead_id","due_at"],"properties":{"lead_id":{"type":"string","format":"uuid","description":"Ubic contact identifier returned by a session contact or call response."},"assignee_email":{"type":"string","format":"email","maxLength":180,"description":"Workspace member assigned to the task. Defaults to the contact list owner."},"due_at":{"type":"string","format":"date-time","description":"ISO-8601 date and time with an explicit timezone. Stored and returned in UTC."},"type":{"type":"string","maxLength":30,"description":"One of the task types configured in the workspace. Defaults to the workspace default."},"note":{"type":"string","maxLength":10000},"external_reference":{"type":"string","maxLength":255,"description":"Stable external task reference, required when the Idempotency-Key header is omitted."}}}}}}
```

## The ScalarMap object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"ScalarMap":{"type":"object","maxProperties":20,"additionalProperties":{"type":["string","number","integer","boolean","null"]}}}}}
```

## The Session object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"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"]}}}}}
```

## The Contact object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"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"]}}}}}
```

## The Call object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"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"}}}}}}
```

## The AttemptStatus object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"AttemptStatus":{"type":"string","enum":["queued","sent","received","delivered","initiated","ringing","in-progress","completed","failed","busy","no-answer","canceled"]}}}}
```

## The Agent object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"Agent":{"type":"object","required":["id","email"],"properties":{"id":{"type":["string","null"],"format":"uuid"},"email":{"type":["string","null"],"format":"email"}}}}}}
```

## The CallResult object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"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."}}},"AttemptStatus":{"type":"string","enum":["queued","sent","received","delivered","initiated","ringing","in-progress","completed","failed","busy","no-answer","canceled"]}}}}
```

## The Recording object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"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"]}}}}}}
```

## The Transcription object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"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"}}}}}}
```

## The Task object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"Task":{"type":"object","required":["id","status","type","type_label","due_at","created_at","updated_at","assignee","lead"],"properties":{"id":{"type":"string","format":"uuid"},"external_reference":{"type":["string","null"]},"status":{"type":"string","enum":["open","done","canceled"]},"type":{"type":"string","description":"Workspace task type identifier."},"type_label":{"type":"string","description":"Current workspace label for the task type."},"note":{"type":["string","null"]},"due_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"assignee":{"$ref":"#/components/schemas/Agent"},"lead":{"$ref":"#/components/schemas/TaskLead"}}},"Agent":{"type":"object","required":["id","email"],"properties":{"id":{"type":["string","null"],"format":"uuid"},"email":{"type":["string","null"],"format":"email"}}},"TaskLead":{"type":"object","required":["id","phone"],"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"]}}}}}}
```

## The TaskLead object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"TaskLead":{"type":"object","required":["id","phone"],"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"]}}}}}}
```

## The Pagination object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"Pagination":{"type":"object","required":["page","per_page","total"],"properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}}}}}
```

## The SessionPage object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"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"}}}}}}
```

## The ContactPage object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"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"}}}}}}
```

## The CallPage object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"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"}}}}}}
```

## The TaskPage object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"TaskPage":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"pagination":{"$ref":"#/components/schemas/CursorPagination"}}},"Task":{"type":"object","required":["id","status","type","type_label","due_at","created_at","updated_at","assignee","lead"],"properties":{"id":{"type":"string","format":"uuid"},"external_reference":{"type":["string","null"]},"status":{"type":"string","enum":["open","done","canceled"]},"type":{"type":"string","description":"Workspace task type identifier."},"type_label":{"type":"string","description":"Current workspace label for the task type."},"note":{"type":["string","null"]},"due_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"assignee":{"$ref":"#/components/schemas/Agent"},"lead":{"$ref":"#/components/schemas/TaskLead"}}},"Agent":{"type":"object","required":["id","email"],"properties":{"id":{"type":["string","null"],"format":"uuid"},"email":{"type":["string","null"],"format":"email"}}},"TaskLead":{"type":"object","required":["id","phone"],"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"]}}},"CursorPagination":{"type":"object","required":["per_page","next_cursor"],"properties":{"per_page":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass this value as `cursor` to retrieve the next page. Null means the end has been reached."}}}}}}
```

## The CursorPagination object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"CursorPagination":{"type":"object","required":["per_page","next_cursor"],"properties":{"per_page":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass this value as `cursor` to retrieve the next page. Null means the end has been reached."}}}}}}
```

## The Error object

```json
{"openapi":"3.1.0","info":{"title":"Ubic Partner API","version":"0.2.0"},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}
```


---

# 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/models.md?ask=<question>&goal=<endgoal>
```

`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.