) or admin URL.
**Example:**
```json
{
"listing": "",
"fields": {
"name": "",
"type": "business",
"specialty": null,
"phone": null,
"fax": null,
"email": "",
"website": null,
"address_1": null,
"address_2": null,
"city": null,
"state": null,
"zip": null,
"npis": [
""
]
}
}
```
#### Responses
##### Status: 200 Updated
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`id` (required)**
`string`
- **`updated` (required)**
`array`
**Items:**
`string`
- **`message` (required)**
`string`
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"updated": [
""
]
}
}
```
### Propose the cleanup for a claimed listing (wizard)
- **Method:** `GET`
- **Path:** `/providers/listings/{id}/cleanup`
- **Tags:** providers
The duplicate merges, sub-listings, NPI moves and suggested listings propose\_listing\_cleanup finds for a claimed listing, each with a tier and its reasons. Quilia wizard accounts only.
#### Parameters
##### `id` required
- **In:** `path`
The listing id
`string`, format: `uuid` — The listing id
#### Responses
##### Status: 200 Proposals
###### Content-Type: application/json
- **`data` (required)**
`array`
**Items:**
- **`id` (required)**
`string`
- **`kind` (required)**
`string`, possible values: `"merge", "set_parent", "move_npi", "suggest_listing"`
- **`listing_id` (required)**
`string`
- **`listing_name` (required)**
`string | null`
- **`patient_count` (required)**
`number`
- **`reasons` (required)**
`array`
**Items:**
`string`
- **`shared_firm_count` (required)**
`number`
- **`target_id` (required)**
`string`
- **`target_name` (required)**
`string | null`
- **`tier` (required)**
`string`, possible values: `"high", "medium", "low"`
- **`npi`**
`string`
- **`npi_type`**
`string`
- **`message` (required)**
`string`
**Example:**
```json
{
"message": "",
"data": [
{
"id": "",
"kind": "merge",
"listing_id": "",
"listing_name": null,
"target_id": "",
"target_name": null,
"tier": "high",
"reasons": [
""
],
"shared_firm_count": 1,
"patient_count": 1,
"npi": "",
"npi_type": ""
}
]
}
```
### Apply the proposed cleanup (wizard)
- **Method:** `POST`
- **Path:** `/providers/listings/{id}/cleanup`
- **Tags:** providers
Applies only the proposal ids passed, against a fresh proposal, merges first, then parents, then NPI moves, then suggestions. proposal\_ids is required, so nothing is applied that the caller did not name. An id no longer proposed is reported, not run. Recorded in listing\_cleanup\_runs. Quilia wizard accounts only.
#### Parameters
##### `id` required
- **In:** `path`
The listing id
`string`, format: `uuid` — The listing id
#### Request Body
##### Content-Type: application/json
- **`proposal_ids` (required)**
`array`
**Items:**
`string`
**Example:**
```json
{
"proposal_ids": [
""
]
}
```
#### Responses
##### Status: 200 Applied
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`outcome` (required)**
`string`, possible values: `"as_proposed", "edited"`
- **`results` (required)**
`array`
**Items:**
- **`id` (required)**
`string`
- **`ok` (required)**
`boolean`
- **`error`**
`string`
- **`message` (required)**
`string`
**Example:**
```json
{
"message": "",
"data": {
"outcome": "as_proposed",
"results": [
{
"id": "",
"ok": true,
"error": ""
}
]
}
}
```
### Report a misbehaving MCP tool
- **Method:** `POST`
- **Path:** `/reports/mcp-bug`
- **Tags:** reports
Files a structured bug report about a Quilia MCP tool that returned the wrong result. Intended to be called by an AI assistant on the user's behalf. Submitted text is rejected if it contains anything that identifies a person (email, phone, SSN, date of birth) — report defects generically.
#### Request Body
##### Content-Type: application/json
- **`actual` (required)**
`string` — What it actually returned or did
- **`expected` (required)**
`string` — What the tool should have returned or done
- **`tool_name` (required)**
`string` — The Quilia MCP tool that misbehaved, e.g. "find\_staff"
- **`arguments_used`**
`object` — Argument names mapped to value SHAPES, never values — {"name": "string(5)"}, not {"name": "Jane Doe"}
**Example:**
```json
{
"tool_name": "",
"expected": "",
"actual": "",
"arguments_used": {
"additionalProperty": ""
}
}
```
#### Responses
##### Status: 201 Report filed
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`filed` (required)**
`boolean`
**Example:**
```json
{
"data": {
"filed": true
}
}
```
### List request templates
- **Method:** `GET`
- **Path:** `/requests`
- **Tags:** requests
Retrieves the firm's saved request templates, newest first. Returns each template's fields so a caller can read a form back before editing it or sending it. Soft-deleted templates are excluded.
#### Parameters
##### `limit`
- **In:** `query`
The maximum number of request templates to return.
`[ "number", "null" ]`, default: `10` — The maximum number of request templates to return.
##### `offset`
- **In:** `query`
The number of request templates to skip before starting to return results.
`[ "number", "null" ]`, default: `0` — The number of request templates to skip before starting to return results.
##### `type`
- **In:** `query`
Only return templates of this kind. 'form' is a built field list, 'signature' places signatures on an uploaded document, 'task' asks the client to do something.
`string`, possible values: `"task", "form", "signature"` — Only return templates of this kind. 'form' is a built field list, 'signature' places signatures on an uploaded document, 'task' asks the client to do something.
#### Responses
##### Status: 200 List of request templates retrieved successfully
###### Content-Type: application/json
- **`data` (required)**
`array` — Array of request templates
**Items:**
- **`builder_url` (required)**
`string` — Portal link to open this template in the form builder
- **`created_at` (required)**
`string` — ISO timestamp when the template was created
- **`created_by` (required)**
`string` — The user ID of the template creator
- **`description` (required)**
`string` — The description of the request template
- **`fields` (required)**
`array` — The template fields, in display order
**Items:**
- **`id` (required)**
`string` — The unique identifier of the field
- **`label` (required)**
`string` — The question, as the client reads it
- **`required` (required)**
`boolean` — Whether the client must answer
- **`type` (required)**
`string`, possible values: `"text", "textarea", "file", "select", "date", "time", "datetime", "signature", "richtext", "ssn"` — The kind of answer this field takes
- **`description`**
`string` — Helper text shown under the question
- **`options`**
`array` — The choices for a 'select' field
**Items:**
`string`
- **`placeholder`**
`string` — Placeholder text inside the input
- **`show_when`**
`object` — Shown only when the field named by field\_id is answered with one of these options
- **`field_id` (required)**
`string` — The id of the earlier select field this depends on
- **`option_indexes` (required)**
`array` — 0-based indexes into that field's options
**Items:**
`integer`
- **`value`**
`string` — 'richtext' only: the HTML body clients read
- **`generate_pdf_on_completion` (required)**
`boolean` — Whether a PDF is produced when a client completes it
- **`id` (required)**
`string` — The unique identifier of the request template
- **`title` (required)**
`string` — The title of the request template
- **`type` (required)**
`string` — 'form' is a built field list, 'signature' places signatures on an uploaded document, 'task' asks the client to do something
- **`pages`**
`array` — Signature templates only: each PDF page's size in points
**Items:**
- **`height` (required)**
`number`
- **`page` (required)**
`number`
- **`width` (required)**
`number`
- **`placements`**
`array` — Signature templates only: the fields placed on the PDF, with the ids PATCH /requests/signature-templates/{id} takes
**Items:**
- **`height` (required)**
`number`
- **`id` (required)**
`string`
- **`label` (required)**
`string`
- **`page` (required)**
`number`
- **`required` (required)**
`boolean`
- **`type` (required)**
`string`, possible values: `"signature", "text", "textarea", "select", "datetime", "checkbox"`
- **`width` (required)**
`number`
- **`x` (required)**
`number`
- **`y` (required)**
`number`
- **`options`**
`array`
**Items:**
`string`
- **`message` (required)**
`string` — Success message confirming the retrieve operation
- **`pagination` (required)**
`object`
- **`has_more` (required)**
`boolean` — Whether there is more data to fetch
- **`limit` (required)**
`number` — Maximum number of items returned
- **`next` (required)**
`string | null` — URL for the next page of items, if available
- **`offset` (required)**
`number` — Number of items skipped
- **`previous` (required)**
`string | null` — URL for the previous page of items, if available
- **`total` (required)**
`number` — Total number of items available
**Example:**
```json
{
"message": "",
"data": [
{
"id": "",
"title": "",
"description": "",
"type": "",
"generate_pdf_on_completion": true,
"fields": [
{
"id": "",
"type": "text",
"label": "",
"value": "",
"description": "",
"placeholder": "",
"required": true,
"options": [
""
],
"show_when": {
"field_id": "",
"option_indexes": [
1
]
}
}
],
"created_by": "",
"created_at": "",
"builder_url": "",
"pages": [
{
"page": 1,
"width": 1,
"height": 1
}
],
"placements": [
{
"id": "",
"type": "signature",
"label": "",
"required": true,
"page": 1,
"x": 1,
"y": 1,
"width": 1,
"height": 1,
"options": [
""
]
}
]
}
],
"pagination": {
"total": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"previous": null,
"next": null
}
}
```
### Create a request form template
- **Method:** `POST`
- **Path:** `/requests/templates`
- **Tags:** requests
Builds a reusable form the firm can send to clients — the same thing the portal's form builder produces. Field ids are assigned server-side; describe each field by type, label and whether it is required. A follow-up question shown only for certain answers to an earlier select field carries `show_when`, naming that field by its position in the list. The template is saved to the firm's library and can be sent with POST /requests/send.
#### Request Body
##### Content-Type: application/json
- **`fields` (required)**
`array` — The fields, in the order the client will see them
**Items:**
- **`label` (required)**
`string` — The question, as the client will read it
- **`type` (required)**
`string`, possible values: `"text", "textarea", "file", "select", "date", "time", "datetime", "signature", "richtext", "ssn"` — The kind of answer this field takes. 'select' needs \`options\`; 'file' asks the client to upload; 'signature' captures a signature; 'ssn' encrypts the answer onto the client's own record and stores nothing on the submission, so only one per form is captured and it always belongs to the client filling it.
- **`description`**
`string` — Helper text shown under the question
- **`options`**
`array` — The choices for a 'select' field
**Items:**
`string`
- **`placeholder`**
`string` — Placeholder text inside the input
- **`required`**
`boolean`, default: `false` — Whether the client must answer before submitting
- **`show_when`**
`object` — Makes this a follow-up question, shown only when an earlier select field is answered with one of the chosen options, e.g. 'Which body parts?' only when 'Were you hurt?' is 'Yes'. While hidden it is skipped, even if required, and its answer is not kept. Omit it for a question every client sees.
- **`field_index` (required)**
`integer` — The 0-based position, in the full field list the form ends up with, of the earlier select field this question depends on
- **`option_indexes` (required)**
`array` — 0-based indexes into that select field's options. The question is shown when the client picks any of them
**Items:**
`integer`
- **`value`**
`string` — 'richtext' only: the HTML body clients read, e.g. '\Vision symptoms\
' for a section heading or '\Bring your insurance card.\
'. Scripts and styles are stripped. When omitted, the label becomes the body as one paragraph.
- **`title` (required)**
`string` — The template title
- **`description`**
`string`, default: `""` — Instructions shown to the client above the fields
- **`generate_pdf_on_completion`**
`boolean`, default: `false` — Produce a PDF of the client's answers when they complete it
- **`translations`**
`array` — Translations for this form template
**Items:**
- **`language` (required)**
`string`, possible values: `"es", "pt", "ht", "km", "ko", "th", "tl", "vi", "zh_CN", "zh_TW", "ru", "hy", "ar", "fa", "de", "pl", "it", "ja", "sr", "fr", "hmn", "mn", "hi", "pa"` — The language code
- **`description`**
`string` — The translated instructions
- **`fields`**
`array` — Translated fields, matching the order of the base fields array
**Items:**
- **`label` (required)**
`string` — The translated question
- **`description`**
`string` — Translated helper text
- **`options`**
`array` — Translated choices for a 'select' field
**Items:**
`string`
- **`placeholder`**
`string` — Translated placeholder text
- **`title`**
`string` — The translated title
**Example:**
```json
{
"title": "",
"description": "",
"fields": [
{
"type": "text",
"label": "",
"value": "",
"description": "",
"placeholder": "",
"required": false,
"options": [
""
],
"show_when": {
"field_index": 0,
"option_indexes": [
0
]
}
}
],
"generate_pdf_on_completion": false,
"translations": [
{
"language": "es",
"title": "",
"description": "",
"fields": [
{
"label": "",
"description": "",
"placeholder": "",
"options": [
""
]
}
]
}
]
}
```
#### Responses
##### Status: 201 Form template created successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`builder_url` (required)**
`string` — Portal link to open this template in the form builder
- **`created_at` (required)**
`string` — ISO timestamp when the template was created
- **`created_by` (required)**
`string` — The user ID of the template creator
- **`description` (required)**
`string` — The template description / instructions
- **`fields` (required)**
`array` — The fields, in display order
**Items:**
- **`id` (required)**
`string` — The unique identifier of the field
- **`label` (required)**
`string` — The question, as the client reads it
- **`required` (required)**
`boolean` — Whether the client must answer
- **`type` (required)**
`string`, possible values: `"text", "textarea", "file", "select", "date", "time", "datetime", "signature", "richtext", "ssn"` — The kind of answer this field takes
- **`description`**
`string` — Helper text shown under the question
- **`options`**
`array` — The choices for a 'select' field
**Items:**
`string`
- **`placeholder`**
`string` — Placeholder text inside the input
- **`show_when`**
`object` — Shown only when the field named by field\_id is answered with one of these options
- **`field_id` (required)**
`string` — The id of the earlier select field this depends on
- **`option_indexes` (required)**
`array` — 0-based indexes into that field's options
**Items:**
`integer`
- **`value`**
`string` — 'richtext' only: the HTML body clients read
- **`generate_pdf_on_completion` (required)**
`boolean` — Whether a PDF is produced when a client completes it
- **`id` (required)**
`string` — The unique identifier of the template
- **`title` (required)**
`string` — The template title
- **`type` (required)**
`string` — 'form' is a built field list, 'signature' places signatures on an uploaded document, 'task' asks the client to do something
- **`translations`**
`array` — Translations for this form template
**Items:**
- **`language` (required)**
`string`, possible values: `"es", "pt", "ht", "km", "ko", "th", "tl", "vi", "zh_CN", "zh_TW", "ru", "hy", "ar", "fa", "de", "pl", "it", "ja", "sr", "fr", "hmn", "mn", "hi", "pa"` — The language code
- **`description`**
`string` — The translated instructions
- **`fields`**
`array` — Translated fields, matching the order of the base fields array
**Items:**
- **`label` (required)**
`string` — The translated question
- **`description`**
`string` — Translated helper text
- **`options`**
`array` — Translated choices for a 'select' field
**Items:**
`string`
- **`placeholder`**
`string` — Translated placeholder text
- **`title`**
`string` — The translated title
- **`message` (required)**
`string` — Success message confirming the operation
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"title": "",
"description": "",
"type": "",
"generate_pdf_on_completion": true,
"fields": [
{
"id": "",
"type": "text",
"label": "",
"value": "",
"description": "",
"placeholder": "",
"required": true,
"options": [
""
],
"show_when": {
"field_id": "",
"option_indexes": [
1
]
}
}
],
"created_by": "",
"created_at": "",
"builder_url": "",
"translations": [
{
"language": "es",
"title": "",
"description": "",
"fields": [
{
"label": "",
"description": "",
"placeholder": "",
"options": [
""
]
}
]
}
]
}
}
```
### Update a request form template
- **Method:** `PATCH`
- **Path:** `/requests/templates/{id}`
- **Tags:** requests
Edits a form template in the firm's library. Use `append_fields` to add questions without disturbing the ones already there; use `fields` to replace the list outright when reordering or removing. Sending both is refused — they disagree about what the form should end up as. Templates already sent to clients keep the copy they were sent with, so editing does not rewrite a form somebody is midway through.
#### Parameters
##### `id` required
- **In:** `path`
The template to update
`string`, format: `uuid` — The template to update
#### Request Body
##### Content-Type: application/json
- **`append_fields`**
`array` — Adds these fields to the end, leaving the existing ones untouched. Use this to add a question rather than resending the whole form.
**Items:**
- **`label` (required)**
`string` — The question, as the client will read it
- **`type` (required)**
`string`, possible values: `"text", "textarea", "file", "select", "date", "time", "datetime", "signature", "richtext", "ssn"` — The kind of answer this field takes. 'select' needs \`options\`; 'file' asks the client to upload; 'signature' captures a signature; 'ssn' encrypts the answer onto the client's own record and stores nothing on the submission, so only one per form is captured and it always belongs to the client filling it.
- **`description`**
`string` — Helper text shown under the question
- **`options`**
`array` — The choices for a 'select' field
**Items:**
`string`
- **`placeholder`**
`string` — Placeholder text inside the input
- **`required`**
`boolean`, default: `false` — Whether the client must answer before submitting
- **`show_when`**
`object` — Makes this a follow-up question, shown only when an earlier select field is answered with one of the chosen options, e.g. 'Which body parts?' only when 'Were you hurt?' is 'Yes'. While hidden it is skipped, even if required, and its answer is not kept. Omit it for a question every client sees.
- **`field_index` (required)**
`integer` — The 0-based position, in the full field list the form ends up with, of the earlier select field this question depends on
- **`option_indexes` (required)**
`array` — 0-based indexes into that select field's options. The question is shown when the client picks any of them
**Items:**
`integer`
- **`value`**
`string` — 'richtext' only: the HTML body clients read, e.g. '\Vision symptoms\
' for a section heading or '\Bring your insurance card.\
'. Scripts and styles are stripped. When omitted, the label becomes the body as one paragraph.
- **`description`**
`string` — New instructions
- **`fields`**
`array` — Replaces the entire field list. Send every field you want the template to end up with, in order — anything omitted is removed.
**Items:**
- **`label` (required)**
`string` — The question, as the client will read it
- **`type` (required)**
`string`, possible values: `"text", "textarea", "file", "select", "date", "time", "datetime", "signature", "richtext", "ssn"` — The kind of answer this field takes. 'select' needs \`options\`; 'file' asks the client to upload; 'signature' captures a signature; 'ssn' encrypts the answer onto the client's own record and stores nothing on the submission, so only one per form is captured and it always belongs to the client filling it.
- **`description`**
`string` — Helper text shown under the question
- **`options`**
`array` — The choices for a 'select' field
**Items:**
`string`
- **`placeholder`**
`string` — Placeholder text inside the input
- **`required`**
`boolean`, default: `false` — Whether the client must answer before submitting
- **`show_when`**
`object` — Makes this a follow-up question, shown only when an earlier select field is answered with one of the chosen options, e.g. 'Which body parts?' only when 'Were you hurt?' is 'Yes'. While hidden it is skipped, even if required, and its answer is not kept. Omit it for a question every client sees.
- **`field_index` (required)**
`integer` — The 0-based position, in the full field list the form ends up with, of the earlier select field this question depends on
- **`option_indexes` (required)**
`array` — 0-based indexes into that select field's options. The question is shown when the client picks any of them
**Items:**
`integer`
- **`value`**
`string` — 'richtext' only: the HTML body clients read, e.g. '\Vision symptoms\
' for a section heading or '\Bring your insurance card.\
'. Scripts and styles are stripped. When omitted, the label becomes the body as one paragraph.
- **`generate_pdf_on_completion`**
`boolean` — Whether to produce a PDF on completion
- **`title`**
`string` — A new title
- **`translations`**
`array` — Translations to replace existing translations
**Items:**
- **`language` (required)**
`string`, possible values: `"es", "pt", "ht", "km", "ko", "th", "tl", "vi", "zh_CN", "zh_TW", "ru", "hy", "ar", "fa", "de", "pl", "it", "ja", "sr", "fr", "hmn", "mn", "hi", "pa"` — The language code
- **`description`**
`string` — The translated instructions
- **`fields`**
`array` — Translated fields, matching the order of the base fields array
**Items:**
- **`label` (required)**
`string` — The translated question
- **`description`**
`string` — Translated helper text
- **`options`**
`array` — Translated choices for a 'select' field
**Items:**
`string`
- **`placeholder`**
`string` — Translated placeholder text
- **`title`**
`string` — The translated title
**Example:**
```json
{
"title": "",
"description": "",
"fields": [
{
"type": "text",
"label": "",
"value": "",
"description": "",
"placeholder": "",
"required": false,
"options": [
""
],
"show_when": {
"field_index": 0,
"option_indexes": [
0
]
}
}
],
"append_fields": [
{
"type": "text",
"label": "",
"value": "",
"description": "",
"placeholder": "",
"required": false,
"options": [
""
],
"show_when": {
"field_index": 0,
"option_indexes": [
0
]
}
}
],
"generate_pdf_on_completion": true,
"translations": [
{
"language": "es",
"title": "",
"description": "",
"fields": [
{
"label": "",
"description": "",
"placeholder": "",
"options": [
""
]
}
]
}
]
}
```
#### Responses
##### Status: 200 Form template updated successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`builder_url` (required)**
`string` — Portal link to open this template in the form builder
- **`created_at` (required)**
`string` — ISO timestamp when the template was created
- **`created_by` (required)**
`string` — The user ID of the template creator
- **`description` (required)**
`string` — The template description / instructions
- **`fields` (required)**
`array` — The fields, in display order
**Items:**
- **`id` (required)**
`string` — The unique identifier of the field
- **`label` (required)**
`string` — The question, as the client reads it
- **`required` (required)**
`boolean` — Whether the client must answer
- **`type` (required)**
`string`, possible values: `"text", "textarea", "file", "select", "date", "time", "datetime", "signature", "richtext", "ssn"` — The kind of answer this field takes
- **`description`**
`string` — Helper text shown under the question
- **`options`**
`array` — The choices for a 'select' field
**Items:**
`string`
- **`placeholder`**
`string` — Placeholder text inside the input
- **`show_when`**
`object` — Shown only when the field named by field\_id is answered with one of these options
- **`field_id` (required)**
`string` — The id of the earlier select field this depends on
- **`option_indexes` (required)**
`array` — 0-based indexes into that field's options
**Items:**
`integer`
- **`value`**
`string` — 'richtext' only: the HTML body clients read
- **`generate_pdf_on_completion` (required)**
`boolean` — Whether a PDF is produced when a client completes it
- **`id` (required)**
`string` — The unique identifier of the template
- **`title` (required)**
`string` — The template title
- **`type` (required)**
`string` — 'form' is a built field list, 'signature' places signatures on an uploaded document, 'task' asks the client to do something
- **`translations`**
`array` — Translations for this form template
**Items:**
- **`language` (required)**
`string`, possible values: `"es", "pt", "ht", "km", "ko", "th", "tl", "vi", "zh_CN", "zh_TW", "ru", "hy", "ar", "fa", "de", "pl", "it", "ja", "sr", "fr", "hmn", "mn", "hi", "pa"` — The language code
- **`description`**
`string` — The translated instructions
- **`fields`**
`array` — Translated fields, matching the order of the base fields array
**Items:**
- **`label` (required)**
`string` — The translated question
- **`description`**
`string` — Translated helper text
- **`options`**
`array` — Translated choices for a 'select' field
**Items:**
`string`
- **`placeholder`**
`string` — Translated placeholder text
- **`title`**
`string` — The translated title
- **`message` (required)**
`string` — Success message confirming the operation
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"title": "",
"description": "",
"type": "",
"generate_pdf_on_completion": true,
"fields": [
{
"id": "",
"type": "text",
"label": "",
"value": "",
"description": "",
"placeholder": "",
"required": true,
"options": [
""
],
"show_when": {
"field_id": "",
"option_indexes": [
1
]
}
}
],
"created_by": "",
"created_at": "",
"builder_url": "",
"translations": [
{
"language": "es",
"title": "",
"description": "",
"fields": [
{
"label": "",
"description": "",
"placeholder": "",
"options": [
""
]
}
]
}
]
}
}
```
### Delete a request template
- **Method:** `DELETE`
- **Path:** `/requests/templates/{id}`
- **Tags:** requests
Moves a template (form, signature document or task) to Recently deleted, where it can be restored in the portal for 30 days, the same as deleting it in the portal. Refused with 409 when the template has ever been sent to a client or is an item in a task list template: those rows still point at it, and the 30-day purge could not remove it.
#### Parameters
##### `id` required
- **In:** `path`
The template to delete
`string`, format: `uuid` — The template to delete
#### Responses
##### Status: 200 Template moved to Recently deleted
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`id` (required)**
`string` — The deleted template
- **`title` (required)**
`string` — Its title
- **`message` (required)**
`string`
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"title": ""
}
}
```
### Create a signature template
- **Method:** `POST`
- **Path:** `/requests/signature-templates`
- **Tags:** requests
Creates a reusable signature template, the same thing the portal's Document signing builder makes: a PDF with fields placed on it for the client to fill in and sign. Placement ids are assigned server-side. Every field is checked against its page's size. A checkbox is always optional. Coordinates are PDF points (1/72 inch), the same numbers as the X, Y, W and H boxes in the portal builder: x from the left edge, y from the BOTTOM edge of the page to the bottom of the field. A US Letter page is 612 x 792.
#### Request Body
##### Content-Type: application/json
- **`pdf` (required)**
`object` — The PDF to sign: exactly one of url or asset\_id. 10 MB at most.
- **`asset_id`**
`string`, format: `uuid` — The id of a PDF already in the firm's documents.
- **`url`**
`string`, format: `uri` — A public https URL of the PDF.
- **`title` (required)**
`string` — The template name.
- **`auto_detect`**
`boolean`, default: `false` — Also add the PDF's own form fields (a fillable PDF's text boxes, checkboxes, dropdowns and signature fields). They are added next to \`placements\` and listed in \`detected\`.
- **`description`**
`string` — Shown to the client above the document.
- **`placements`**
`array`, default: `[]` — The fields to place. Coordinates are PDF points (1/72 inch), the same numbers as the X, Y, W and H boxes in the portal builder: x from the left edge, y from the BOTTOM edge of the page to the bottom of the field. A US Letter page is 612 x 792.
**Items:**
- **`height` (required)**
`number` — Height in PDF points. At least 20 (8 for a checkbox).
- **`label` (required)**
`string` — What the client sees for this field, e.g. "Client Signature".
- **`page` (required)**
`integer` — The page it sits on, from 1.
- **`type` (required)**
`string`, possible values: `"signature", "text", "textarea", "select", "datetime", "checkbox"` — signature, text (one line), textarea (several lines), select (a dropdown, needs options), datetime (a date) or checkbox.
- **`width` (required)**
`number` — Width in PDF points. At least 20 (8 for a checkbox).
- **`x` (required)**
`number` — Left edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
- **`y` (required)**
`number` — Bottom edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
- **`options`**
`array` — The choices of a select field. Only valid on a select.
**Items:**
`string`
- **`required`**
`boolean` — Whether the client must fill it in. Defaults to true. Ignored for a checkbox, which is always optional.
**Example:**
```json
{
"title": "",
"description": "",
"pdf": {
"url": "",
"asset_id": ""
},
"placements": [],
"auto_detect": false
}
```
#### Responses
##### Status: 201 Signature template created
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`message` (required)**
`string`
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"title": "",
"description": "",
"type": "signature",
"file_name": "",
"pages": [
{
"page": 1,
"width": 1,
"height": 1
}
],
"placements": [],
"builder_url": "",
"detected": [
{
"id": "",
"type": "signature",
"label": "",
"required": true,
"page": 1,
"x": 1,
"y": 1,
"width": 1,
"height": 1,
"options": [
""
]
}
]
}
}
```
### Update a signature template
- **Method:** `PATCH`
- **Path:** `/requests/signature-templates/{id}`
- **Tags:** requests
Edits a signature template: its title and description, and its fields by id (add, update, remove; applied as remove, then update, then add). The PDF itself can't be swapped; create a new template for a different document. Requests already sent keep the copy they were sent with. Coordinates are PDF points (1/72 inch), the same numbers as the X, Y, W and H boxes in the portal builder: x from the left edge, y from the BOTTOM edge of the page to the bottom of the field. A US Letter page is 612 x 792.
#### Parameters
##### `id` required
- **In:** `path`
The template to update
`string`, format: `uuid` — The template to update
#### Request Body
##### Content-Type: application/json
- **`add_placements`**
`array` — New fields. Coordinates are PDF points (1/72 inch), the same numbers as the X, Y, W and H boxes in the portal builder: x from the left edge, y from the BOTTOM edge of the page to the bottom of the field. A US Letter page is 612 x 792.
**Items:**
- **`height` (required)**
`number` — Height in PDF points. At least 20 (8 for a checkbox).
- **`label` (required)**
`string` — What the client sees for this field, e.g. "Client Signature".
- **`page` (required)**
`integer` — The page it sits on, from 1.
- **`type` (required)**
`string`, possible values: `"signature", "text", "textarea", "select", "datetime", "checkbox"` — signature, text (one line), textarea (several lines), select (a dropdown, needs options), datetime (a date) or checkbox.
- **`width` (required)**
`number` — Width in PDF points. At least 20 (8 for a checkbox).
- **`x` (required)**
`number` — Left edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
- **`y` (required)**
`number` — Bottom edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
- **`options`**
`array` — The choices of a select field. Only valid on a select.
**Items:**
`string`
- **`required`**
`boolean` — Whether the client must fill it in. Defaults to true. Ignored for a checkbox, which is always optional.
- **`description`**
`string`
- **`remove_placement_ids`**
`array` — Ids of fields to remove.
**Items:**
`string`
- **`title`**
`string`
- **`update_placements`**
`array` — Changes to existing fields by id. Only the properties sent change.
**Items:**
- **`id` (required)**
`string` — The id of the placement to change.
- **`height`**
`number` — Height in PDF points. At least 20 (8 for a checkbox).
- **`label`**
`string` — What the client sees for this field, e.g. "Client Signature".
- **`options`**
`array` — The choices of a select field. Only valid on a select.
**Items:**
`string`
- **`page`**
`integer` — The page it sits on, from 1.
- **`required`**
`boolean` — Whether the client must fill it in. Defaults to true. Ignored for a checkbox, which is always optional.
- **`type`**
`string`, possible values: `"signature", "text", "textarea", "select", "datetime", "checkbox"` — signature, text (one line), textarea (several lines), select (a dropdown, needs options), datetime (a date) or checkbox.
- **`width`**
`number` — Width in PDF points. At least 20 (8 for a checkbox).
- **`x`**
`number` — Left edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
- **`y`**
`number` — Bottom edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
**Example:**
```json
{
"title": "",
"description": "",
"add_placements": [
{
"type": "signature",
"label": "",
"page": 1,
"x": 1,
"y": 1,
"width": 1,
"height": 1,
"required": true,
"options": [
""
]
}
],
"update_placements": [
{
"type": "signature",
"label": "",
"page": 1,
"x": 1,
"y": 1,
"width": 1,
"height": 1,
"required": true,
"options": [
""
],
"id": ""
}
],
"remove_placement_ids": [
""
]
}
```
#### Responses
##### Status: 200 Signature template updated
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`message` (required)**
`string`
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"title": "",
"description": "",
"type": "signature",
"file_name": "",
"pages": [
{
"page": 1,
"width": 1,
"height": 1
}
],
"placements": [],
"builder_url": "",
"detected": [
{
"id": "",
"type": "signature",
"label": "",
"required": true,
"page": 1,
"x": 1,
"y": 1,
"width": 1,
"height": 1,
"options": [
""
]
}
]
}
}
```
### Create and send a request (existing template, or a freeform task)
- **Method:** `POST`
- **Path:** `/requests/send`
- **Tags:** requests
Sends a request to a client in a case. Refused (400) when the case is closed or archived. A client still pending on the case is marked invited once the notification goes out. Provide a `templateId` to send an existing form / signature / task-list template, OR `type: "task"` with a `title` (+ optional description / url) to create and send a freeform one-off action task with no template. The request is created with 'pending' status and the client is notified. All caller-supplied IDs are verified against the authenticated org.
#### Request Body
##### Content-Type: application/json
**Any of:**
- **`caseId` (required)**
`string` — The case ID to associate with this request
- **`recipientId` (required)**
`string` — The user ID of the client who will receive the request
- **`senderId` (required)**
`string` — The user ID of the staff member sending the request
- **`templateId` (required)**
`string` — The ID of an existing request template to send
* **`caseId` (required)**
`string` — The case ID to associate with this request
* **`recipientId` (required)**
`string` — The user ID of the client who will receive the request
* **`senderId` (required)**
`string` — The user ID of the staff member sending the request
* **`title` (required)**
`string` — The task title shown to the client
* **`type` (required)**
`string`, possible values: `"task"` — Create a freeform one-off action task (no template required)
* **`description`**
`string` — Optional instructions shown with the task
* **`url`**
`string`, format: `uri` — Optional http(s) link the client is sent to
**Example:**
```json
{
"templateId": "",
"recipientId": "",
"senderId": "",
"caseId": ""
}
```
#### Responses
##### Status: 200 Request sent successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`id` (required)**
`string` — The unique identifier of the sent request
- **`status` (required)**
`string` — The status of the request (typically 'pending')
- **`message` (required)**
`string` — Success message confirming the send operation
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"status": ""
}
}
```
### List a case's requests
- **Method:** `GET`
- **Path:** `/requests/list`
- **Tags:** requests
Lists the requests sent on a case — summaries only (no response payload). Filter by status and type. Fetch GET /requests/{type}/{id} for a request's full detail + response.
#### Parameters
##### `caseId` required
- **In:** `query`
The case to list requests for
`string`, format: `uuid` — The case to list requests for
##### `status`
- **In:** `query`
Filter by status (e.g. 'pending', 'completed')
`string` — Filter by status (e.g. 'pending', 'completed')
##### `type`
- **In:** `query`
Filter by request type (task / form / signature)
`string`, possible values: `"task", "form", "signature"` — Filter by request type (task / form / signature)
##### `limit`
- **In:** `query`
The maximum number of requests to return.
`[ "number", "null" ]`, default: `25` — The maximum number of requests to return.
##### `offset`
- **In:** `query`
The number of requests to skip before returning results.
`[ "number", "null" ]`, default: `0` — The number of requests to skip before returning results.
#### Responses
##### Status: 200 Requests retrieved successfully
###### Content-Type: application/json
- **`data` (required)**
`array` — Array of request summaries
**Items:**
- **`case_id` (required)**
`string` — The case this request belongs to
- **`created_at` (required)**
`string` — ISO timestamp when the request was created
- **`id` (required)**
`string` — The unique identifier of the request
- **`recipient_id` (required)**
`string | null` — The client the request was sent to
- **`status` (required)**
`string` — The request status (e.g. 'pending', 'completed')
- **`submitted_at` (required)**
`string | null` — ISO timestamp when the client completed it, if completed
- **`task_list_id` (required)**
`string | null` — The parent task list id, if this request is part of one
- **`title` (required)**
`string` — The request title
- **`type` (required)**
`string` — The request type (task / form / signature)
- **`message` (required)**
`string` — Success message confirming the retrieve
- **`pagination` (required)**
`object`
- **`has_more` (required)**
`boolean` — Whether there is more data to fetch
- **`limit` (required)**
`number` — Maximum number of items returned
- **`next` (required)**
`string | null` — URL for the next page of items, if available
- **`offset` (required)**
`number` — Number of items skipped
- **`previous` (required)**
`string | null` — URL for the previous page of items, if available
- **`total` (required)**
`number` — Total number of items available
**Example:**
```json
{
"message": "",
"data": [
{
"id": "",
"type": "",
"status": "",
"title": "",
"case_id": "",
"recipient_id": null,
"task_list_id": null,
"created_at": "",
"submitted_at": null
}
],
"pagination": {
"total": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"previous": null,
"next": null
}
}
```
### Get request response by request ID
- **Method:** `GET`
- **Path:** `/requests/{requestId}/responses`
- **Tags:** requests
Retrieves the response submission for a specific request. Returns the most recent submission if multiple exist. Returns 404 if the request doesn't exist or has no submission.
#### Parameters
##### `requestId` required
- **In:** `path`
The unique identifier of the request to retrieve responses for
`string`, format: `uuid` — The unique identifier of the request to retrieve responses for
#### Responses
##### Status: 200 Request response retrieved successfully
###### Content-Type: application/json
- **`data` (required)**
`object` — The request response data
- **`duration` (required)**
`number` — Time taken to complete the submission in milliseconds
- **`fields` (required)**
`array` — Array of field responses submitted by the client
**Items:**
- **`id` (required)**
`string` — The unique identifier of the field
- **`type` (required)**
`string` — The type of the field (e.g., 'text', 'file', 'select')
- **`files`**
`array` — Array of uploaded files (for file type fields)
**Items:**
- **`name` (required)**
`string` — The original filename
- **`path` (required)**
`string` — The storage path of the file
- **`type` (required)**
`string` — The MIME type of the file
- **`label`**
`string` — The label of the field
- **`value`**
`string` — The value entered by the user
- **`id` (required)**
`string` — The unique identifier of the submission
- **`platform` (required)**
`string` — Platform where the submission was made (e.g., 'web', 'mobile')
- **`request` (required)**
`object`
- **`case_id` (required)**
`string` — The ID of the case associated with this request
- **`created_at` (required)**
`string` — ISO timestamp when the request was created
- **`id` (required)**
`string` — The unique identifier of the request
- **`status` (required)**
`string` — The status of the request (e.g., 'pending', 'completed')
- **`request_id` (required)**
`string` — The ID of the request this submission belongs to
- **`submitted_at` (required)**
`string` — ISO timestamp when the submission was created
- **`template` (required)**
`object`
- **`description` (required)**
`string` — The description of the template
- **`id` (required)**
`string` — The unique identifier of the template
- **`title` (required)**
`string` — The title of the template
- **`template_id` (required)**
`string` — The ID of the template used for this request
- **`message` (required)**
`string` — Success message confirming the retrieve operation
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"request_id": "",
"template_id": "",
"fields": [
{
"id": "",
"type": "",
"label": "",
"value": "",
"files": [
{
"path": "",
"name": "",
"type": ""
}
]
}
],
"submitted_at": "",
"duration": 1,
"platform": "",
"request": {
"id": "",
"status": "",
"case_id": "",
"created_at": ""
},
"template": {
"id": "",
"title": "",
"description": ""
}
}
}
```
### List request responses by client ID
- **Method:** `GET`
- **Path:** `/requests/responses/{clientId}`
- **Tags:** requests
Retrieves a paginated list of all request responses submitted by a specific client. Returns full response data including submission details, related request information, and template metadata.
#### Parameters
##### `clientId` required
- **In:** `path`
The unique identifier of the client (user\_id) to retrieve responses for
`string`, format: `uuid` — The unique identifier of the client (user\_id) to retrieve responses for
##### `limit`
- **In:** `query`
The maximum number of request responses to return.
`[ "number", "null" ]`, default: `10` — The maximum number of request responses to return.
##### `offset`
- **In:** `query`
The number of request responses to skip before starting to return results.
`[ "number", "null" ]`, default: `0` — The number of request responses to skip before starting to return results.
#### Responses
##### Status: 200 List of request responses retrieved successfully
###### Content-Type: application/json
- **`data` (required)**
`array` — Array of request responses
**Items:**
- **`duration` (required)**
`number` — Time taken to complete the submission in milliseconds
- **`fields` (required)**
`array` — Array of field responses submitted by the client
**Items:**
- **`id` (required)**
`string` — The unique identifier of the field
- **`type` (required)**
`string` — The type of the field (e.g., 'text', 'file', 'select')
- **`files`**
`array` — Array of uploaded files (for file type fields)
**Items:**
- **`name` (required)**
`string` — The original filename
- **`path` (required)**
`string` — The storage path of the file
- **`type` (required)**
`string` — The MIME type of the file
- **`label`**
`string` — The label of the field
- **`value`**
`string` — The value entered by the user
- **`id` (required)**
`string` — The unique identifier of the submission
- **`platform` (required)**
`string` — Platform where the submission was made (e.g., 'web', 'mobile')
- **`request` (required)**
`object`
- **`case_id` (required)**
`string` — The ID of the case associated with this request
- **`created_at` (required)**
`string` — ISO timestamp when the request was created
- **`id` (required)**
`string` — The unique identifier of the request
- **`status` (required)**
`string` — The status of the request (e.g., 'pending', 'completed')
- **`request_id` (required)**
`string` — The ID of the request this submission belongs to
- **`submitted_at` (required)**
`string` — ISO timestamp when the submission was created
- **`template` (required)**
`object`
- **`description` (required)**
`string` — The description of the template
- **`id` (required)**
`string` — The unique identifier of the template
- **`title` (required)**
`string` — The title of the template
- **`template_id` (required)**
`string` — The ID of the template used for this request
- **`message` (required)**
`string` — Success message confirming the retrieve operation
- **`pagination` (required)**
`object`
- **`has_more` (required)**
`boolean` — Whether there is more data to fetch
- **`limit` (required)**
`number` — Maximum number of items returned
- **`next` (required)**
`string | null` — URL for the next page of items, if available
- **`offset` (required)**
`number` — Number of items skipped
- **`previous` (required)**
`string | null` — URL for the previous page of items, if available
- **`total` (required)**
`number` — Total number of items available
**Example:**
```json
{
"message": "",
"data": [
{
"id": "",
"request_id": "",
"template_id": "",
"fields": [
{
"id": "",
"type": "",
"label": "",
"value": "",
"files": [
{
"path": "",
"name": "",
"type": ""
}
]
}
],
"submitted_at": "",
"duration": 1,
"platform": "",
"request": {
"id": "",
"status": "",
"case_id": "",
"created_at": ""
},
"template": {
"id": "",
"title": "",
"description": ""
}
}
],
"pagination": {
"total": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"previous": null,
"next": null
}
}
```
### Resend a request notification
- **Method:** `POST`
- **Path:** `/requests/{id}/resend`
- **Tags:** requests
Re-fires the client notification for a pending request — a nudge. Only pending, standalone requests on a case that is not closed or archived can be resent (task-list items are notified at the list level).
#### Parameters
##### `id` required
- **In:** `path`
The request id to resend
`string`, format: `uuid` — The request id to resend
#### Responses
##### Status: 200 Notification resent successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`id` (required)**
`string` — The unique identifier of the request
- **`status` (required)**
`string` — The request status
- **`message` (required)**
`string` — Success message confirming the resend
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"status": ""
}
}
```
### Get a request by type and id
- **Method:** `GET`
- **Path:** `/requests/{type}/{id}`
- **Tags:** requests
Retrieves a single request by id, namespaced by type. Returns the request's status and — once the client has completed it — the response payload (form fields / signed document) plus any completion note. 404 if the id doesn't exist in this org or isn't of the given type. (Task lists are a separate resource — a request is an item, not a list.)
#### Parameters
##### `type` required
- **In:** `path`
The request type (task / form / signature)
`string`, possible values: `"task", "form", "signature"` — The request type (task / form / signature)
##### `id` required
- **In:** `path`
The request id
`string`, format: `uuid` — The request id
#### Responses
##### Status: 200 Request retrieved successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`case_id` (required)**
`string` — The case this request belongs to
- **`completion_note` (required)**
`string | null` — Optional note the client left when completing a task
- **`created_at` (required)**
`string` — ISO timestamp when the request was created
- **`description` (required)**
`string | null` — The request instructions / description
- **`id` (required)**
`string` — The unique identifier of the request
- **`recipient_id` (required)**
`string | null` — The client the request was sent to
- **`response` (required)**
`object | null` — The client submission (form / signature), null until completed
- **`fields` (required)**
`array` — The fields the client submitted
**Items:**
- **`id` (required)**
`string` — The unique identifier of the field
- **`type` (required)**
`string` — The type of the field (e.g., 'text', 'file', 'select')
- **`files`**
`array` — Array of uploaded files (for file type fields)
**Items:**
- **`name` (required)**
`string` — The original filename
- **`path` (required)**
`string` — The storage path of the file
- **`type` (required)**
`string` — The MIME type of the file
- **`label`**
`string` — The label of the field
- **`value`**
`string` — The value entered by the user
- **`submitted_at` (required)**
`string` — ISO timestamp of the submission
- **`status` (required)**
`string` — The request status (e.g. 'pending', 'completed')
- **`submitted_at` (required)**
`string | null` — ISO timestamp when the client completed it, if completed
- **`title` (required)**
`string` — The request title
- **`type` (required)**
`string` — The request type (task / form / signature)
- **`message` (required)**
`string` — Success message confirming the retrieve
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"type": "",
"status": "",
"title": "",
"description": null,
"case_id": "",
"recipient_id": null,
"created_at": "",
"submitted_at": null,
"completion_note": null,
"response": {
"submitted_at": "",
"fields": [
{
"id": "",
"type": "",
"label": "",
"value": "",
"files": [
{
"path": "",
"name": "",
"type": ""
}
]
}
]
}
}
}
```
### Search users
- **Method:** `GET`
- **Path:** `/search`
- **Tags:** search
Search for users (all roles) within the authenticated organization.
This endpoint provides fuzzy search across all organization members including clients, staff, attorneys, and other roles. Results are returned in order of membership creation date (most recent first).
## Search Behavior
The search query (`q` parameter) performs **case-insensitive partial matching** against multiple user fields simultaneously. If a UUID is provided, an exact match is attempted against the user ID.
## Searchable Fields
| Field | Match Type | Description |
| ------------- | ---------- | --------------- |
| `id` | Exact | User's UUID |
| `name` | Partial | Full name |
| `name_first` | Partial | First name |
| `name_last` | Partial | Last name |
| `email` | Partial | Email address |
| `phone` | Partial | Phone number |
| `address_1` | Partial | Address line 1 |
| `address_2` | Partial | Address line 2 |
| `city` | Partial | City |
| `state` | Partial | State/province |
| `postal_code` | Partial | Postal/zip code |
| `country` | Partial | Country |
## Filtering
Use `filter[field]` query parameters to narrow results:
- **`filter[role]`** - Filter by user role. Supports comma-separated values for OR matching.
- **`filter[active]`** - Filter by active status (`true` or `false`).
- **`filter[created_at]`** - Filter by membership creation date (supports wildcards).
- **`filter[updated_at]`** - Filter by membership update date (supports wildcards).
## Examples
```ini
# Search for users named "John"
GET /v2/search?q=john
# Search for users in Chicago
GET /v2/search?q=chicago
# Search for clients only
GET /v2/search?q=john&filter[role]=client
# Search for active attorneys or legal staff
GET /v2/search?q=john&filter[role]=attorney,legal staff&filter[active]=true
# Paginate results
GET /v2/search?q=john&limit=20&offset=40
```
#### Parameters
##### `q` required
- **In:** `query`
Search query string (minimum 2 characters). Searches across multiple user fields using case-insensitive partial matching.
**Searched fields:**
- `id` - Exact UUID match only
- `name`, `name_first`, `name_last` - Full and partial names
- `email` - Email address
- `phone` - Phone number
- `address_1`, `address_2` - Address lines
- `city`, `state`, `postal_code`, `country` - Location fields
**Examples:**
- `q=john` - Matches "John Doe", "", etc.
- `q=chicago` - Matches users in Chicago
- `q=14aec6c6-9562-4990-9f66-7411187c4d27` - Exact user ID match
`string` — Search query string (minimum 2 characters). Searches across multiple user fields using case-insensitive partial matching. \*\*Searched fields:\*\* - \`id\` - Exact UUID match only - \`name\`, \`name\_first\`, \`name\_last\` - Full and partial names - \`email\` - Email address - \`phone\` - Phone number - \`address\_1\`, \`address\_2\` - Address lines - \`city\`, \`state\`, \`postal\_code\`, \`country\` - Location fields \*\*Examples:\*\* - \`q=john\` - Matches "John Doe", "johnny\@email.com", etc. - \`q=chicago\` - Matches users in Chicago - \`q=14aec6c6-9562-4990-9f66-7411187c4d27\` - Exact user ID match
##### `limit`
- **In:** `query`
Maximum number of results to return (1-50, default 10)
`number`, default: `10` — Maximum number of results to return (1-50, default 10)
##### `offset`
- **In:** `query`
Number of results to skip for pagination
`[ "number", "null" ]`, default: `0` — Number of results to skip for pagination
##### `filter[role]`
- **In:** `query`
Filter by user role. Supports comma-separated values for OR matching.
**Valid values:** wizard, admin, attorney, client, legal staff, provider, provider admin, medical staff, third party
**Examples:**
- `filter[role]=client` - Only clients
- `filter[role]=client,attorney` - Clients OR attorneys
`string` — Filter by user role. Supports comma-separated values for OR matching. \*\*Valid values:\*\* wizard, admin, attorney, client, legal staff, provider, provider admin, medical staff, third party \*\*Examples:\*\* - \`filter\[role]=client\` - Only clients - \`filter\[role]=client,attorney\` - Clients OR attorneys
##### `filter[active]`
- **In:** `query`
Filter by active status within the organization.
**Valid values:** `true`, `false`
**Examples:**
- `filter[active]=true` - Only active members
- `filter[active]=false` - Only inactive members
`string` — Filter by active status within the organization. \*\*Valid values:\*\* \`true\`, \`false\` \*\*Examples:\*\* - \`filter\[active]=true\` - Only active members - \`filter\[active]=false\` - Only inactive members
##### `filter[created_at]`
- **In:** `query`
Filter by membership creation date. Supports wildcards (\*) for partial matching.
**Examples:**
- `filter[created_at]=2024*` - Created in 2024
- `filter[created_at]=2024-01*` - Created in January 2024
`string` — Filter by membership creation date. Supports wildcards (\*) for partial matching. \*\*Examples:\*\* - \`filter\[created\_at]=2024\*\` - Created in 2024 - \`filter\[created\_at]=2024-01\*\` - Created in January 2024
##### `filter[updated_at]`
- **In:** `query`
Filter by membership last updated date. Supports wildcards (\*) for partial matching.
**Examples:**
- `filter[updated_at]=2024*` - Updated in 2024
- `filter[updated_at]=2024-01*` - Updated in January 2024
`string` — Filter by membership last updated date. Supports wildcards (\*) for partial matching. \*\*Examples:\*\* - \`filter\[updated\_at]=2024\*\` - Updated in 2024 - \`filter\[updated\_at]=2024-01\*\` - Updated in January 2024
#### Responses
##### Status: 200 Search completed successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`results` (required)**
`array` — Array of users matching the search query, ordered by membership creation date (most recent first)
**Items:**
- **`active` (required)**
`boolean` — Whether the user is currently active in the organization. Inactive users may have been deactivated but not deleted.
- **`address_1` (required)**
`string | null` — First line of the user's address
- **`address_2` (required)**
`string | null` — Second line of the user's address (apartment, suite, etc.)
- **`city` (required)**
`string | null` — User's city
- **`country` (required)**
`string | null` — User's country
- **`created_at` (required)**
`string | null` — ISO 8601 timestamp of when the organization membership was created
- **`email` (required)**
`string | null` — User's email address
- **`job_title` (required)**
`string | null` — User's job title (primarily for staff members)
- **`matched_field` (required)**
`string` — The field that matched the search query. Useful for highlighting or understanding why a result was returned. \*\*Possible values:\*\* id, name, name\_first, name\_last, email, phone, address\_1, address\_2, city, state, postal\_code, country, unknown
- **`member_id` (required)**
`string` — Organization membership ID (organization\_members.id). Use this to reference the user within the organization context.
- **`name` (required)**
`string | null` — User's full name
- **`name_first` (required)**
`string | null` — User's first name
- **`name_last` (required)**
`string | null` — User's last name
- **`phone` (required)**
`string | null` — User's phone number
- **`postal_code` (required)**
`string | null` — User's postal/zip code
- **`profile_image` (required)**
`string | null` — URL to the user's profile image
- **`role` (required)**
`string | null`, possible values: `"wizard", "admin", "attorney", "client", "legal staff", "provider", "provider admin", "medical staff", "third party", null` — User's role within the organization. \*\*Possible values:\*\* wizard, admin, attorney, client, legal staff, provider, provider admin, medical staff, third party
- **`state` (required)**
`string | null` — User's state or province
- **`updated_at` (required)**
`string | null` — ISO 8601 timestamp of when the organization membership was last updated
- **`user_id` (required)**
`string` — Unique identifier of the user (UUID)
- **`message` (required)**
`string` — Success message indicating the search completed
- **`pagination` (required)**
`object`
- **`has_more` (required)**
`boolean` — Whether more results are available beyond the current page. Use offset + limit to fetch the next page.
- **`limit` (required)**
`number` — Maximum results returned per page
- **`offset` (required)**
`number` — Current offset (number of results skipped)
- **`total` (required)**
`number` — Total number of users matching the search query
- **`query` (required)**
`string` — The search query that was executed (echoed back for reference)
**Example:**
```json
{
"message": "Search completed",
"data": {
"results": [
{
"user_id": "14aec6c6-9562-4990-9f66-7411187c4d27",
"member_id": "25bfd7d7-a673-5a01-a077-8c22298d5e38",
"name": "John Doe",
"name_first": "John",
"name_last": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890",
"address_1": "123 Main Street",
"address_2": "Suite 100",
"city": "Chicago",
"state": "IL",
"postal_code": "60601",
"country": "USA",
"role": "client",
"active": true,
"job_title": "Paralegal",
"profile_image": "https://storage.example.com/profiles/user123.jpg",
"matched_field": "name",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-06-20T14:45:00Z"
}
]
},
"query": "john",
"pagination": {
"total": 25,
"offset": 0,
"limit": 10,
"has_more": true
}
}
```
### Create a new staff member
- **Method:** `POST`
- **Path:** `/staff`
- **Tags:** staff
Creates a staff member, idempotent on repeat calls for the same email. The `invite` field controls email behavior: `'send'` always sends an invitation email, `'skip'` never does, `'auto'` (default) sends only when the user is new or has never signed in — safe for nightly staff-sync integrations.
#### Request Body
##### Content-Type: application/json
- **`email` (required)**
`string`, format: `email` — The email address of the staff member
- **`name` (required)**
`string` — The full name of the staff member
- **`role` (required)**
`string`, possible values: `"admin", "attorney", "legal staff"` — The role of the staff member (admin, attorney, or legal staff)
- **`external_id`**
`string` — The partner's own identifier for this staff member (used for idempotent creation across mutable fields like email)
- **`invite`**
`string`, possible values: `"send", "skip", "auto"`, default: `"auto"` — Controls invitation email behavior. \`'send'\` always sends an invite, even if the user already exists. \`'skip'\` never sends an invite — silent create for new users, no-op for existing. \`'auto'\` (default) sends an invite only when the user is net-new OR has never signed in, making it safe for repeated staff-sync calls without spamming active members.
- **`job_title`**
`string` — The job title of the staff member
- **`location_id`**
`number` — The ID of the office location to assign, from GET /org/locations. Use 0 for the firm's primary office — that is stored as no sub-location, so it reads back as null.
- **`name_first`**
`string` — The first name of the staff member
- **`name_last`**
`string` — The last name of the staff member
- **`permission_id`**
`string`, format: `uuid` — The ID of the permission set to assign
- **`phone`**
`string` — The phone number of the staff member
**Example:**
```json
{
"name": "",
"name_first": "",
"name_last": "",
"email": "",
"phone": "",
"job_title": "",
"role": "admin",
"location_id": 1,
"permission_id": "",
"external_id": "",
"invite": "auto"
}
```
#### Responses
##### Status: 200 Staff member created successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`member_id` (required)**
`string` — The organization membership ID of the staff member
- **`user_id` (required)**
`string` — The unique identifier of the created staff member
- **`message` (required)**
`string` — Success message confirming the creation operation
**Example:**
```json
{
"message": "",
"data": {
"user_id": "",
"member_id": ""
}
}
```
### List staff members
- **Method:** `GET`
- **Path:** `/staff`
- **Tags:** staff
Retrieves a paginated list of staff members for the authenticated organization with optional field filtering. Staff members include admins, attorneys, and legal staff (not clients).
#### Parameters
##### `limit`
- **In:** `query`
The maximum number of staff members to return.
`[ "number", "null" ]`, default: `10` — The maximum number of staff members to return.
##### `offset`
- **In:** `query`
The number of staff members to skip before starting to return results.
`[ "number", "null" ]`, default: `0` — The number of staff members to skip before starting to return results.
##### `fields`
- **In:** `query`
Comma-separated list of user fields to include in the response
`string` — Comma-separated list of user fields to include in the response
##### `filter[name]`
- **In:** `query`
Filter by name. See endpoint description for syntax.
`string` — Filter by name. See endpoint description for syntax.
##### `filter[email]`
- **In:** `query`
Filter by email. See endpoint description for syntax.
`string` — Filter by email. See endpoint description for syntax.
##### `filter[role]`
- **In:** `query`
Filter by role. See endpoint description for syntax.
`string` — Filter by role. See endpoint description for syntax.
##### `filter[active]`
- **In:** `query`
Filter by active. See endpoint description for syntax.
`string` — Filter by active. See endpoint description for syntax.
##### `filter[location_id]`
- **In:** `query`
Filter by location\_id. See endpoint description for syntax.
`string` — Filter by location\_id. See endpoint description for syntax.
#### Responses
##### Status: 200 Staff data retrieved successfully
###### Content-Type: application/json
- **`data` (required)**
`array` — Array of staff members
**Items:**
- **`member_id` (required)**
`string` — The organization membership ID of the staff member
- **`user_id` (required)**
`string` — The unique identifier of the staff member
- **`active`**
`boolean | null` — Whether the staff member is currently active
- **`auto_add_to_cases`**
`boolean` — On every case, so they get every case's notifications (Settings > Team, "Add to every case")
- **`auto_add_visible_to_client`**
`boolean` — While on every case: whether the client sees them as a contact on those cases
- **`bio`**
`string | null` — The staff member's bio — the 'About' field in the portal
- **`city`**
`string | null` — The staff member's city
- **`country`**
`string | null` — The staff member's country
- **`created_at`**
`string | null` — When the staff member was created
- **`email`**
`string | null` — The staff member's email address
- **`external_id`**
`string | null` — The partner's own identifier for this staff member, matching organization\_members.metadata.external\_id
- **`facebook`**
`string | null` — The staff member's Facebook profile
- **`instagram`**
`string | null` — The staff member's Instagram profile
- **`job_title`**
`string | null` — The staff member's job title
- **`linkedin`**
`string | null` — The staff member's LinkedIn profile
- **`location_id`**
`number | null` — The ID of the office location the staff member is assigned to. Null means no sub-location, which is the firm's primary office.
- **`name`**
`string | null` — The staff member's full name
- **`name_first`**
`string | null` — The staff member's first name
- **`name_last`**
`string | null` — The staff member's last name
- **`permission_id`**
`string | null` — The ID of the permission set assigned to the staff member
- **`phone`**
`string | null` — The staff member's phone number
- **`phone_receives_texts`**
`boolean` — Whether their phone can receive text messages ("Receives text messages" in Settings > Team). Turn it on only for a cell phone; clients are then offered Text beside Call, and the person joins "Text my team" group texts
- **`profile_image`**
`string | null` — URL to the staff member's profile image
- **`role`**
`string | null`, possible values: `"admin", "attorney", "legal staff", null` — The staff member's role in the organization
- **`state`**
`string | null` — The staff member's state or province
- **`timezone`**
`string | null` — The staff member's IANA timezone
- **`twitter`**
`string | null` — The staff member's X/Twitter profile
- **`updated_at`**
`string | null` — When the staff member was last updated
- **`message` (required)**
`string` — Success message confirming the retrieve operation
- **`pagination` (required)**
`object`
- **`has_more` (required)**
`boolean` — Whether there is more data to fetch
- **`limit` (required)**
`number` — Maximum number of items returned
- **`next` (required)**
`string | null` — URL for the next page of items, if available
- **`offset` (required)**
`number` — Number of items skipped
- **`previous` (required)**
`string | null` — URL for the previous page of items, if available
- **`total` (required)**
`number` — Total number of items available
**Example:**
```json
{
"message": "",
"data": [
{
"user_id": "",
"member_id": "",
"name": null,
"name_first": null,
"name_last": null,
"email": null,
"phone": null,
"phone_receives_texts": true,
"profile_image": null,
"external_id": null,
"role": "admin",
"active": null,
"job_title": null,
"city": null,
"state": null,
"country": null,
"timezone": null,
"bio": null,
"linkedin": null,
"twitter": null,
"facebook": null,
"instagram": null,
"location_id": null,
"permission_id": null,
"auto_add_to_cases": true,
"auto_add_visible_to_client": true,
"created_at": null,
"updated_at": null
}
],
"pagination": {
"total": 1,
"offset": 1,
"limit": 1,
"has_more": true,
"previous": null,
"next": null
}
}
```
### Delete a staff member
- **Method:** `DELETE`
- **Path:** `/staff/{id}`
- **Tags:** staff
Removes a staff member from the organization. By default, this performs a soft delete (sets active=false). Use soft\_delete=false query parameter to permanently remove the organization membership.
#### Parameters
##### `id` required
- **In:** `path`
The unique identifier of the staff member to delete
`string`, format: `uuid` — The unique identifier of the staff member to delete
##### `soft_delete`
- **In:** `query`
When true (default), deactivates the staff member. When false, permanently removes the organization membership.
`[ "boolean", "null" ]`, default: `true` — When true (default), deactivates the staff member. When false, permanently removes the organization membership.
#### Responses
##### Status: 200 Staff member successfully deleted/deactivated
###### Content-Type: application/json
- **`message` (required)**
`string` — Success message confirming the delete operation
**Example:**
```json
{
"message": ""
}
```
### Retrieve a single staff member
- **Method:** `GET`
- **Path:** `/staff/{id}`
- **Tags:** staff
Retrieves detailed information for a specific staff member using either user\_id or member\_id.
#### Parameters
##### `id` required
- **In:** `path`
The unique identifier of the staff member to retrieve
`string`, format: `uuid` — The unique identifier of the staff member to retrieve
#### Responses
##### Status: 200 Staff member retrieved successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`member_id` (required)**
`string` — The organization membership ID of the staff member
- **`user_id` (required)**
`string` — The unique identifier of the staff member
- **`active`**
`boolean | null` — Whether the staff member is currently active
- **`auto_add_to_cases`**
`boolean` — On every case, so they get every case's notifications (Settings > Team, "Add to every case")
- **`auto_add_visible_to_client`**
`boolean` — While on every case: whether the client sees them as a contact on those cases
- **`bio`**
`string | null` — The staff member's bio — the 'About' field in the portal
- **`city`**
`string | null` — The staff member's city
- **`country`**
`string | null` — The staff member's country
- **`created_at`**
`string | null` — When the staff member was created
- **`email`**
`string | null` — The staff member's email address
- **`external_id`**
`string | null` — The partner's own identifier for this staff member, matching organization\_members.metadata.external\_id
- **`facebook`**
`string | null` — The staff member's Facebook profile
- **`instagram`**
`string | null` — The staff member's Instagram profile
- **`job_title`**
`string | null` — The staff member's job title
- **`linkedin`**
`string | null` — The staff member's LinkedIn profile
- **`location_id`**
`number | null` — The ID of the office location the staff member is assigned to. Null means no sub-location, which is the firm's primary office.
- **`name`**
`string | null` — The staff member's full name
- **`name_first`**
`string | null` — The staff member's first name
- **`name_last`**
`string | null` — The staff member's last name
- **`permission_id`**
`string | null` — The ID of the permission set assigned to the staff member
- **`phone`**
`string | null` — The staff member's phone number
- **`phone_receives_texts`**
`boolean` — Whether their phone can receive text messages ("Receives text messages" in Settings > Team). Turn it on only for a cell phone; clients are then offered Text beside Call, and the person joins "Text my team" group texts
- **`profile_image`**
`string | null` — URL to the staff member's profile image
- **`role`**
`string | null`, possible values: `"admin", "attorney", "legal staff", null` — The staff member's role in the organization
- **`state`**
`string | null` — The staff member's state or province
- **`timezone`**
`string | null` — The staff member's IANA timezone
- **`twitter`**
`string | null` — The staff member's X/Twitter profile
- **`updated_at`**
`string | null` — When the staff member was last updated
- **`message` (required)**
`string` — Success message confirming the retrieve operation
**Example:**
```json
{
"message": "",
"data": {
"user_id": "",
"member_id": "",
"name": null,
"name_first": null,
"name_last": null,
"email": null,
"phone": null,
"phone_receives_texts": true,
"profile_image": null,
"external_id": null,
"role": "admin",
"active": null,
"job_title": null,
"city": null,
"state": null,
"country": null,
"timezone": null,
"bio": null,
"linkedin": null,
"twitter": null,
"facebook": null,
"instagram": null,
"location_id": null,
"permission_id": null,
"auto_add_to_cases": true,
"auto_add_visible_to_client": true,
"created_at": null,
"updated_at": null
}
}
```
### Update staff member information
- **Method:** `PATCH`
- **Path:** `/staff/{id}`
- **Tags:** staff
Updates specific fields of an existing staff member record. Allows modification of user details (name, email, phone, job\_title) and membership details (role, active status, location, permissions).
#### Parameters
##### `id` required
- **In:** `path`
The unique identifier of the staff member to update
`string`, format: `uuid` — The unique identifier of the staff member to update
#### Request Body
##### Content-Type: application/json
- **`active`**
`boolean` — Whether the staff member is active
- **`allow_messages`**
`boolean` — Whether the staff member can send messages in this case (requires case\_id)
- **`auto_add_to_cases`**
`boolean` — Put this member on every case, so they get every case's notifications (Settings > Team, "Add to every case"). Turning it on also adds them to the firm's existing cases that are not closed. Separate from an integration's per-person staff overrides, which only apply when the CMS lists the person on the case.
- **`auto_add_visible_to_client`**
`boolean` — While auto\_add\_to\_cases is on: whether the client sees this member as a contact on those cases. Cleared when auto\_add\_to\_cases is turned off.
- **`avatar_url`**
`object` — The staff member's headshot. Either a publicly reachable https image URL (PNG, JPG, GIF or WebP, 10MB max), which we download, or the image itself as { data: \, mime\_type: "image/png" | "image/jpeg" | "image/webp" } (3MB max), for an image with no public URL. Either way Quilia hosts its own copy. Pass null to remove the current image. A URL image over 1600px is resized; a headshot sent as data is center-cropped to a 512px square JPEG, the same as the portal's photo cropper. Square works best; it is rendered as a circle.
- **`bio`**
`string | null` — The staff member's bio — the 'About' field in the portal
- **`case_id`**
`string`, format: `uuid` — The case ID to update case-level settings for this staff member
- **`city`**
`string | null` — The staff member's city
- **`contactable`**
`boolean` — Whether the staff member's contact info is visible to clients in the app (requires case\_id)
- **`country`**
`string | null` — The staff member's country
- **`email`**
`string`, format: `email` — The staff member's email address
- **`facebook`**
`string | null` — The staff member's Facebook profile
- **`instagram`**
`string | null` — The staff member's Instagram profile
- **`job_title`**
`string | null` — The staff member's job title
- **`linkedin`**
`string | null` — The staff member's LinkedIn profile
- **`location_id`**
`number | null` — The ID of the office location, from GET /org/locations. Use 0 for the firm's primary office — that is stored as no sub-location, so it reads back as null. Null clears the assignment.
- **`name`**
`string` — The staff member's full name
- **`name_first`**
`string` — The staff member's first name
- **`name_last`**
`string` — The staff member's last name
- **`permission_id`**
`string | null`, format: `uuid` — The ID of the permission set
- **`phone`**
`string | null` — The staff member's phone number
- **`phone_receives_texts`**
`boolean` — Whether their phone can receive text messages ("Receives text messages" in Settings > Team). Turn it on only for a cell phone; clients are then offered Text beside Call, and the person joins "Text my team" group texts
- **`role`**
`string`, possible values: `"admin", "attorney", "legal staff"` — The staff member's role (must be admin, attorney, or legal staff)
- **`state`**
`string | null` — The staff member's state or province
- **`timezone`**
`string | null` — The staff member's IANA timezone, e.g. 'America/Denver'
- **`twitter`**
`string | null` — The staff member's X/Twitter profile
**Example:**
```json
{
"name": "",
"name_first": "",
"name_last": "",
"email": "",
"phone": null,
"phone_receives_texts": true,
"job_title": null,
"city": null,
"state": null,
"country": null,
"timezone": null,
"bio": null,
"linkedin": null,
"twitter": null,
"facebook": null,
"instagram": null,
"avatar_url": "",
"role": "admin",
"active": true,
"location_id": null,
"permission_id": null,
"auto_add_to_cases": true,
"auto_add_visible_to_client": true,
"case_id": "",
"contactable": true,
"allow_messages": true
}
```
#### Responses
##### Status: 200 Staff member updated successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`member_id` (required)**
`string` — The organization membership ID of the staff member
- **`user_id` (required)**
`string` — The unique identifier of the updated staff member
- **`message` (required)**
`string` — Success message confirming the update operation
**Example:**
```json
{
"message": "",
"data": {
"user_id": "",
"member_id": ""
}
}
```
### Create a task list
- **Method:** `POST`
- **Path:** `/task-lists`
- **Tags:** task-lists
Create a list of things a client has to do, as a DRAFT.
Each item becomes one request the client works through — a document to upload, or an action to mark done. The list is attached to a case and a client but is **not sent**: nothing reaches the client until a human opens `builder_url` and sends it.
That is deliberate. This endpoint exists so a firm can turn its onboarding email into a client checklist automatically, and a checklist generated from prose should get one human glance before it lands on a client's phone.
#### Request Body
##### Content-Type: application/json
- **`case_id` (required)**
`string`, format: `uuid` — The case this list belongs to.
- **`items` (required)**
`array` — The things the client has to do, in order.
**Items:**
- **`kind` (required)**
`string`, possible values: `"documents", "action"` — documents = upload a file. action = do something and mark it done.
- **`title` (required)**
`string` — What the client sees as the name of this item.
- **`count`**
`integer` — Documents items only: how many files the item asks for, e.g. 12 for "12 months of statements" or 3 for "3 years of tax returns". The client sees "3 of 12 uploaded" and the item completes when the last one lands. Omit for one file.
- **`description`**
`string` — Optional detail shown under the title.
- **`required`**
`boolean`, default: `true` — Whether the list can be completed without this item.
- **`url`**
`string`, format: `uri` — Action items only: a link the client opens before marking it done.
- **`recipient_id` (required)**
`string`, format: `uuid` — The client who receives it. Must be a member of the case.
- **`title` (required)**
`string` — The name of the list, shown to the client.
- **`description`**
`string`
- **`reminder_interval_days`**
`integer` — How often to remind the client while items stay open. Omit for the firm default.
**Example:**
```json
{
"title": "Estate planning — what we need from you",
"description": "",
"case_id": "",
"recipient_id": "",
"reminder_interval_days": 1,
"items": [
{
"kind": "documents",
"title": "Upload your most recent bank statement",
"description": "Any account held in your name, most recent month.",
"required": true,
"url": "https://example.com/intake",
"count": 12
}
]
}
```
#### Responses
##### Status: 201 The created draft.
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`builder_url` (required)**
`string` — Where a human reviews and sends it. Give this to the caller — a list created by an agent should get one look before it reaches a client.
- **`case_id` (required)**
`string | null`, format: `uuid`
- **`id` (required)**
`string`, format: `uuid`
- **`item_ids` (required)**
`array`
**Items:**
`string`, format: `uuid`
- **`recipient_id` (required)**
`string | null`, format: `uuid`
- **`status` (required)**
`string` — Always "draft" on create. Nothing reaches the client until it is sent from the builder.
- **`title` (required)**
`string`
- **`message` (required)**
`string`
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"title": "",
"status": "",
"case_id": null,
"recipient_id": null,
"item_ids": [
""
],
"builder_url": ""
}
}
```
##### Status: 400
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "bad_request",
"message": ""
}
```
##### Status: 401
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "unauthorized",
"message": ""
}
```
##### Status: 402
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "payment_required",
"message": ""
}
```
##### Status: 403
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "forbidden",
"message": ""
}
```
##### Status: 404
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "not_found",
"message": ""
}
```
##### Status: 405
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "method_not_allowed",
"message": ""
}
```
##### Status: 409
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "conflict",
"message": ""
}
```
##### Status: 429
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "too_many_requests",
"message": ""
}
```
##### Status: 500
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "internal_server_error",
"message": ""
}
```
### Create a task-list template
- **Method:** `POST`
- **Path:** `/task-list-templates`
- **Tags:** task-list-templates
Create a reusable task list: a checklist the firm starts from on every new case of a kind ("New MVA case"), each item a document to upload or an action to mark done.
A template belongs to no case and no client, so **creating one sends nothing to anyone**. Staff start a list from it with "New from template" on the portal's Tasks page, attach it to a client there, and send it from the builder.
Writes the same rows as the portal's "Save as template": the template, one library copy of each item (`as_template: true`), and the ordered links between them. To draft a list on one case instead, use `POST /task-lists`.
#### Request Body
##### Content-Type: application/json
- **`items` (required)**
`array` — The things the client will have to do, in order.
**Items:**
- **`kind` (required)**
`string`, possible values: `"documents", "action"` — documents = upload a file. action = do something and mark it done.
- **`title` (required)**
`string` — What the client sees as the name of this item.
- **`count`**
`integer` — Documents items only: how many files the item asks for, e.g. 12 for "12 months of statements" or 3 for "3 years of tax returns". The client sees "3 of 12 uploaded" and the item completes when the last one lands. Omit for one file.
- **`description`**
`string` — Optional detail shown under the title.
- **`required`**
`boolean`, default: `true` — Whether the list can be completed without this item.
- **`url`**
`string`, format: `uri` — Action items only: a link the client opens before marking it done.
- **`title` (required)**
`string` — The template name staff pick from "New from template". It also becomes the title of every list created from it, which the client sees.
- **`description`**
`string` — Optional intro, copied onto every list created from the template.
**Example:**
```json
{
"title": "New MVA case: what we need from you",
"description": "",
"items": [
{
"kind": "documents",
"title": "Upload your most recent bank statement",
"description": "Any account held in your name, most recent month.",
"required": true,
"url": "https://example.com/intake",
"count": 12
}
]
}
```
#### Responses
##### Status: 201 The created template.
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`description` (required)**
`string | null`
- **`id` (required)**
`string`, format: `uuid`
- **`item_count` (required)**
`integer`
- **`portal_url` (required)**
`string` — The portal Tasks page, where the template appears under "New from template".
- **`title` (required)**
`string`
- **`message` (required)**
`string`
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"title": "",
"description": null,
"item_count": 1,
"portal_url": ""
}
}
```
##### Status: 400
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "bad_request",
"message": ""
}
```
##### Status: 401
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "unauthorized",
"message": ""
}
```
##### Status: 402
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "payment_required",
"message": ""
}
```
##### Status: 403
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "forbidden",
"message": ""
}
```
##### Status: 404
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "not_found",
"message": ""
}
```
##### Status: 405
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "method_not_allowed",
"message": ""
}
```
##### Status: 409
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "conflict",
"message": ""
}
```
##### Status: 429
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "too_many_requests",
"message": ""
}
```
##### Status: 500
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "internal_server_error",
"message": ""
}
```
### List task-list templates
- **Method:** `GET`
- **Path:** `/task-list-templates`
- **Tags:** task-list-templates
The firm's reusable task lists, newest first: the ones staff pick from "New from template". Read one with `GET /task-list-templates/{id}` to see its items.
#### Responses
##### Status: 200 The templates.
###### Content-Type: application/json
- **`data` (required)**
`array`
**Items:**
- **`created_at` (required)**
`string`
- **`description` (required)**
`string | null`
- **`id` (required)**
`string`, format: `uuid`
- **`item_count` (required)**
`integer`
- **`title` (required)**
`string`
**Example:**
```json
{
"data": [
{
"id": "",
"title": "",
"description": null,
"item_count": 1,
"created_at": ""
}
]
}
```
##### Status: 400
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "bad_request",
"message": ""
}
```
##### Status: 401
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "unauthorized",
"message": ""
}
```
##### Status: 402
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "payment_required",
"message": ""
}
```
##### Status: 403
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "forbidden",
"message": ""
}
```
##### Status: 404
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "not_found",
"message": ""
}
```
##### Status: 405
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "method_not_allowed",
"message": ""
}
```
##### Status: 409
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "conflict",
"message": ""
}
```
##### Status: 429
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "too_many_requests",
"message": ""
}
```
##### Status: 500
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "internal_server_error",
"message": ""
}
```
### Get a task-list template
- **Method:** `GET`
- **Path:** `/task-list-templates/{id}`
- **Tags:** task-list-templates
One template with its items in order. Each item has the `id` that `PATCH /task-list-templates/{id}` takes to keep or change it.
#### Parameters
##### `id` required
- **In:** `path`
The template id.
`string`, format: `uuid` — The template id.
#### Responses
##### Status: 200 The template.
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`description` (required)**
`string | null`
- **`id` (required)**
`string`, format: `uuid`
- **`items` (required)**
`array`
**Items:**
- **`count` (required)**
`integer | null` — Documents items: how many files it asks for. Null means one.
- **`description` (required)**
`string | null`
- **`id` (required)**
`string`, format: `uuid` — The item id. Send it back in PATCH to keep or change this item.
- **`kind` (required)**
`string`, possible values: `"documents", "action", "form", "signature"`
- **`required` (required)**
`boolean | null` — Documents items: whether it must be done. Null otherwise.
- **`title` (required)**
`string`
- **`url` (required)**
`string | null` — Action items: the link the client opens first.
- **`portal_url` (required)**
`string`
- **`title` (required)**
`string`
**Example:**
```json
{
"data": {
"id": "",
"title": "",
"description": null,
"items": [],
"portal_url": ""
}
}
```
##### Status: 400
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "bad_request",
"message": ""
}
```
##### Status: 401
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "unauthorized",
"message": ""
}
```
##### Status: 402
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "payment_required",
"message": ""
}
```
##### Status: 403
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "forbidden",
"message": ""
}
```
##### Status: 404
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "not_found",
"message": ""
}
```
##### Status: 405
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "method_not_allowed",
"message": ""
}
```
##### Status: 409
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "conflict",
"message": ""
}
```
##### Status: 429
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "too_many_requests",
"message": ""
}
```
##### Status: 500
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "internal_server_error",
"message": ""
}
```
### Update a task-list template
- **Method:** `PATCH`
- **Path:** `/task-list-templates/{id}`
- **Tags:** task-list-templates
Change a template's title, intro or items. Read it first with `GET /task-list-templates/{id}`.
`items`, when sent, is the whole list in order after the change: `{ "id": "..." }` keeps an item as it is, an item with an `id` and content rewrites it (send the whole item), an item without an `id` is added, and any existing item left out is removed.
A template reaches no client, so this sends nothing. Lists already started from the template keep their own copy of the items and do not change.
#### Parameters
##### `id` required
- **In:** `path`
The template id.
`string`, format: `uuid` — The template id.
#### Request Body
##### Content-Type: application/json
- **`description`**
`string | null` — The intro. null clears it; omit to leave it.
- **`items`**
`array` — The full list, in order, after the change. \`{ "id": ... }\` keeps an item as it is; an item with an id and content rewrites it; an item without an id is added. Any existing item left out is removed. Omit \`items\` to change only the title or description.
**Items:**
**Any of:**
- **`id` (required)**
`string`, format: `uuid` — An existing item id.
**All of:**
- **`kind` (required)**
`string`, possible values: `"documents", "action"` — documents = upload a file. action = do something and mark it done.
- **`title` (required)**
`string` — What the client sees as the name of this item.
- **`count`**
`integer` — Documents items only: how many files the item asks for, e.g. 12 for "12 months of statements" or 3 for "3 years of tax returns". The client sees "3 of 12 uploaded" and the item completes when the last one lands. Omit for one file.
- **`description`**
`string` — Optional detail shown under the title.
- **`required`**
`boolean`, default: `true` — Whether the list can be completed without this item.
- **`url`**
`string`, format: `uri` — Action items only: a link the client opens before marking it done.
* **`id`**
`string`, format: `uuid` — An existing item id to rewrite in place. Omit to add a new item.
- **`title`**
`string`
**Example:**
```json
{
"title": "",
"description": null,
"items": [
{
"id": ""
}
]
}
```
#### Responses
##### Status: 200 The template after the change.
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`description` (required)**
`string | null`
- **`id` (required)**
`string`, format: `uuid`
- **`items` (required)**
`array`
**Items:**
- **`count` (required)**
`integer | null` — Documents items: how many files it asks for. Null means one.
- **`description` (required)**
`string | null`
- **`id` (required)**
`string`, format: `uuid` — The item id. Send it back in PATCH to keep or change this item.
- **`kind` (required)**
`string`, possible values: `"documents", "action", "form", "signature"`
- **`required` (required)**
`boolean | null` — Documents items: whether it must be done. Null otherwise.
- **`title` (required)**
`string`
- **`url` (required)**
`string | null` — Action items: the link the client opens first.
- **`portal_url` (required)**
`string`
- **`title` (required)**
`string`
- **`message` (required)**
`string`
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"title": "",
"description": null,
"items": [],
"portal_url": ""
}
}
```
##### Status: 400
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "bad_request",
"message": ""
}
```
##### Status: 401
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "unauthorized",
"message": ""
}
```
##### Status: 402
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "payment_required",
"message": ""
}
```
##### Status: 403
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "forbidden",
"message": ""
}
```
##### Status: 404
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "not_found",
"message": ""
}
```
##### Status: 405
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "method_not_allowed",
"message": ""
}
```
##### Status: 409
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "conflict",
"message": ""
}
```
##### Status: 429
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "too_many_requests",
"message": ""
}
```
##### Status: 500
###### Content-Type: application/json
- **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
- **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "internal_server_error",
"message": ""
}
```
### Create a webhook subscription
- **Method:** `POST`
- **Path:** `/webhooks`
- **Tags:** webhooks
Creates a new webhook subscription for the authenticated organization. The subscription connects a webhook template to an external endpoint with custom configuration. The system will automatically generate a webhook secret for signature verification.
#### Request Body
##### Content-Type: application/json
- **`endpoint` (required)**
`string`, format: `uri` — The HTTPS endpoint URL to receive webhook payloads
- **`event_name` (required)**
`string` — The name of the event to subscribe to (e.g., 'client.action.created')
- **`retry_attempts`**
`integer`, default: `3` — Number of retry attempts for failed webhook deliveries (0-5)
**Example:**
```json
{
"event_name": "",
"endpoint": "",
"retry_attempts": 3
}
```
#### Responses
##### Status: 201 Webhook subscription created successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`created_at` (required)**
`string` — When the subscription was created
- **`endpoint` (required)**
`string | null`, format: `uri` — Subscription endpoint
- **`event_name` (required)**
`string` — The name of the event subscribed to
- **`id` (required)**
`string` — The unique identifier of the webhook subscription
- **`shared_secret` (required)**
`string | null` — Shared secret to verify the webhook payload
- **`status` (required)**
`string | null`, possible values: `"pending", "enabled", "disabled", null` — Status of the webhook subscription: pending, enabled, disabled
- **`updated_at` (required)**
`string | null` — When the subscription was last updated
- **`retry_attempts`**
`integer`, default: `3` — Number of retry attempts for failed webhook deliveries (0-5)
- **`message` (required)**
`string` — Success message confirming the create operation
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"event_name": "",
"endpoint": null,
"status": "pending",
"shared_secret": null,
"retry_attempts": 3,
"created_at": "",
"updated_at": null
}
}
```
### List webhook subscriptions
- **Method:** `GET`
- **Path:** `/webhooks`
- **Tags:** webhooks
Retrieves a list of all webhook subscriptions for the authenticated organization. Returns subscription details including webhook template information, endpoint configuration, and status.
#### Responses
##### Status: 200 List of webhook subscriptions retrieved successfully
###### Content-Type: application/json
- **`data` (required)**
`array` — Array of webhook subscriptions
**Items:**
- **`created_at` (required)**
`string` — When the subscription was created
- **`endpoint` (required)**
`string | null`, format: `uri` — Subscription endpoint
- **`event_name` (required)**
`string` — The name of the event subscribed to
- **`id` (required)**
`string` — The unique identifier of the webhook subscription
- **`shared_secret` (required)**
`string | null` — Shared secret to verify the webhook payload
- **`status` (required)**
`string | null`, possible values: `"pending", "enabled", "disabled", null` — Status of the webhook subscription: pending, enabled, disabled
- **`updated_at` (required)**
`string | null` — When the subscription was last updated
- **`webhook` (required)**
`object` — The webhook template details
- **`description` (required)**
`string | null` — The webhook description
- **`id` (required)**
`string` — The webhook template ID
- **`name` (required)**
`string | null` — The webhook event name
- **`body_schema`**
`object` — JSON schema for the webhook payload
- **`retry_attempts`**
`integer`, default: `3` — Number of retry attempts for failed webhook deliveries (0-5)
- **`message` (required)**
`string` — Success message confirming the list operation
**Example:**
```json
{
"message": "",
"data": [
{
"id": "",
"event_name": "",
"endpoint": null,
"status": "pending",
"shared_secret": null,
"retry_attempts": 3,
"created_at": "",
"updated_at": null,
"webhook": {
"id": "",
"name": null,
"description": null,
"body_schema": null
}
}
]
}
```
### Delete a webhook subscription
- **Method:** `DELETE`
- **Path:** `/webhooks/{id}`
- **Tags:** webhooks
Deletes a webhook subscription for the authenticated organization. This will stop all webhook deliveries for this subscription immediately.
#### Parameters
##### `id` required
- **In:** `path`
The unique identifier of the webhook subscription
`string` — The unique identifier of the webhook subscription
#### Responses
##### Status: 200 Webhook subscription deleted successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`endpoint` (required)**
`string | null`, format: `uri` — Subscription endpoint
- **`event_name` (required)**
`string` — The name of the event subscribed to
- **`id` (required)**
`string` — The unique identifier of the webhook subscription
- **`message` (required)**
`string` — Success message confirming the delete operation
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"event_name": "",
"endpoint": null
}
}
```
### Retrieve a webhook subscription
- **Method:** `GET`
- **Path:** `/webhooks/{id}`
- **Tags:** webhooks
Retrieves a specific webhook subscription by its ID for the authenticated organization. Returns subscription details including configuration and associated webhook template information.
#### Parameters
##### `id` required
- **In:** `path`
The unique identifier of the webhook subscription
`string` — The unique identifier of the webhook subscription
#### Responses
##### Status: 200 Webhook subscription retrieved successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`created_at` (required)**
`string` — When the subscription was created
- **`endpoint` (required)**
`string | null`, format: `uri` — Subscription endpoint
- **`event_name` (required)**
`string` — The name of the event subscribed to
- **`id` (required)**
`string` — The unique identifier of the webhook subscription
- **`shared_secret` (required)**
`string | null` — Shared secret to verify the webhook payload
- **`status` (required)**
`string | null`, possible values: `"pending", "enabled", "disabled", null` — Status of the webhook subscription: pending, enabled, disabled
- **`updated_at` (required)**
`string | null` — When the subscription was last updated
- **`webhook` (required)**
`object` — The webhook template details
- **`body_schema` (required)**
`object` — JSON schema for the webhook payload
- **`description` (required)**
`string | null` — The webhook description
- **`id` (required)**
`string` — The webhook template ID
- **`name` (required)**
`string | null` — The webhook event name
- **`params`**
`object` — Parameters schema for the webhook
- **`retry_attempts`**
`integer`, default: `3` — Number of retry attempts for failed webhook deliveries (0-5)
- **`message` (required)**
`string` — Success message confirming the retrieve operation
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"event_name": "",
"endpoint": null,
"status": "pending",
"shared_secret": null,
"retry_attempts": 3,
"created_at": "",
"updated_at": null,
"webhook": {
"id": "",
"name": null,
"description": null,
"body_schema": {},
"params": null
}
}
}
```
### Update a webhook subscription
- **Method:** `PATCH`
- **Path:** `/webhooks/{id}`
- **Tags:** webhooks
Updates a webhook subscription's configuration for the authenticated organization. The updated configuration must still conform to the webhook template's params schema.
#### Parameters
##### `id` required
- **In:** `path`
The unique identifier of the webhook subscription
`string` — The unique identifier of the webhook subscription
#### Request Body
##### Content-Type: application/json
- **`endpoint`**
`string | null`, format: `uri` — Subscription endpoint
- **`retry_attempts`**
`integer`, default: `3` — Number of retry attempts for failed webhook deliveries (0-5)
- **`status`**
`string | null`, possible values: `"pending", "enabled", "disabled", null` — Status of the webhook subscription: pending, enabled, disabled
**Example:**
```json
{
"endpoint": null,
"retry_attempts": 3,
"status": "pending"
}
```
#### Responses
##### Status: 200 Webhook subscription updated successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`created_at` (required)**
`string` — When the subscription was created
- **`endpoint` (required)**
`string | null`, format: `uri` — Subscription endpoint
- **`event_name` (required)**
`string` — The name of the event subscribed to
- **`id` (required)**
`string` — The unique identifier of the webhook subscription
- **`shared_secret` (required)**
`string | null` — Shared secret to verify the webhook payload
- **`status` (required)**
`string | null`, possible values: `"pending", "enabled", "disabled", null` — Status of the webhook subscription: pending, enabled, disabled
- **`updated_at` (required)**
`string | null` — When the subscription was last updated
- **`retry_attempts`**
`integer`, default: `3` — Number of retry attempts for failed webhook deliveries (0-5)
- **`message` (required)**
`string` — Success message confirming the update operation
**Example:**
```json
{
"message": "",
"data": {
"id": "",
"event_name": "",
"endpoint": null,
"status": "pending",
"shared_secret": null,
"retry_attempts": 3,
"created_at": "",
"updated_at": null
}
}
```
### List available webhook events
- **Method:** `GET`
- **Path:** `/webhooks/events`
- **Tags:** webhooks
Retrieves a list of available webhook events that organizations can subscribe to. Returns event definitions including event names, descriptions, and payload schemas for Quilia outgoing webhooks.
#### Responses
##### Status: 200 List of available webhook events retrieved successfully
###### Content-Type: application/json
- **`data` (required)**
`array` — Array of available webhook events
**Items:**
- **`body_schema` (required)**
`object | null` — JSON schema describing the event payload structure
- **`description` (required)**
`string | null` — Human-readable description of when this event is triggered
- **`id` (required)**
`string` — The unique identifier of the webhook event
- **`name` (required)**
`string` — Unique event name identifier
**Example:**
```json
{
"data": [
{
"id": "",
"name": "",
"description": null,
"body_schema": null
}
]
}
```
### Regenerate webhook secret
- **Method:** `POST`
- **Path:** `/webhooks/{id}/regenerate-secret`
- **Tags:** webhooks
Regenerates the shared secret for a webhook subscription. This will invalidate the previous secret and generate a new one for signature verification.
#### Parameters
##### `id` required
- **In:** `path`
The unique identifier of the webhook subscription
`string` — The unique identifier of the webhook subscription
#### Responses
##### Status: 200 Webhook secret regenerated successfully
###### Content-Type: application/json
- **`data` (required)**
`object`
- **`id` (required)**
`string`
- **`new_secret` (required)**
`string`
**Example:**
```json
{
"data": {
"id": "",
"new_secret": ""
}
}
```
### Simulate webhook event
- **Method:** `POST`
- **Path:** `/webhooks/simulate`
- **Tags:** webhooks
Simulates a webhook event by sending the example payload from the event's schema to a specified endpoint. Useful for testing webhook integrations during development.
#### Request Body
##### Content-Type: application/json
- **`endpoint` (required)**
`string`, format: `uri` — The endpoint URL to send the simulated webhook to
- **`event_name` (required)**
`string` — The name of the webhook event to simulate (e.g., 'document.created', 'case.updated')
- **`use_example`**
`boolean`, default: `true` — Whether to use the example payload from the schema (default: true)
**Example:**
```json
{
"event_name": "",
"endpoint": "",
"use_example": true
}
```
#### Responses
##### Status: 200 Webhook simulation completed
###### Content-Type: application/json
- **`endpoint` (required)**
`string` — The endpoint that received the webhook
- **`event_name` (required)**
`string` — The event that was simulated
- **`message` (required)**
`string` — Human-readable message about the simulation result
- **`payload` (required)**
`object` — The payload that was sent
- **`success` (required)**
`boolean` — Whether the webhook simulation was successful
- **`error`**
`string` — Error message if the simulation failed
- **`response`**
`object` — Response details from the endpoint
- **`status` (required)**
`number` — HTTP status code from the endpoint
- **`body`**
`string` — Response body from the endpoint
- **`headers`**
`object` — Response headers from the endpoint
**Example:**
```json
{
"success": true,
"message": "",
"event_name": "",
"endpoint": "",
"payload": {},
"response": {
"status": 1,
"body": "",
"headers": {
"additionalProperty": ""
}
},
"error": ""
}
```
### Test webhook endpoint
- **Method:** `POST`
- **Path:** `/webhooks/test`
- **Tags:** webhooks
Tests a webhook endpoint by sending a test payload. Can be used to verify endpoint connectivity before creating a subscription.
#### Request Body
##### Content-Type: application/json
- **`endpoint` (required)**
`string`, format: `uri` — The webhook endpoint URL to test
**Example:**
```json
{
"endpoint": ""
}
```
#### Responses
##### Status: 200 Webhook test completed
###### Content-Type: application/json
- **`message` (required)**
`string`
- **`success` (required)**
`boolean`
- **`details`**
`string`
- **`response`**
`string`
**Example:**
```json
{
"success": true,
"message": "",
"response": "",
"details": ""
}
```
### Test webhook subscription
- **Method:** `POST`
- **Path:** `/webhooks/{id}/test`
- **Tags:** webhooks
Tests a specific webhook subscription by sending a test payload to the configured endpoint. If the endpoint returns a 2xx response, the subscription status will be updated to 'enabled'.
#### Parameters
##### `id` required
- **In:** `path`
The unique identifier of the webhook subscription
`string` — The unique identifier of the webhook subscription
#### Responses
##### Status: 200 Webhook subscription test completed
###### Content-Type: application/json
- **`message` (required)**
`string`
- **`success` (required)**
`boolean`
- **`activation`**
`boolean`
- **`data`**
`object`
- **`id` (required)**
`string`
- **`activated_at`**
`string`
- **`status`**
`string`, possible values: `"enabled", "pending", "disabled"`
- **`details`**
`string`
- **`response`**
`string`
**Example:**
```json
{
"success": true,
"message": "",
"activation": true,
"response": "",
"details": "",
"data": {
"id": "",
"status": "enabled",
"activated_at": ""
}
}
```
## Schemas
### ErrorBadRequest
- **Type:**`object`
* **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
* **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "bad_request",
"message": ""
}
```
### ErrorUnauthorized
- **Type:**`object`
* **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
* **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "unauthorized",
"message": ""
}
```
### ErrorPaymentRequired
- **Type:**`object`
* **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
* **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "payment_required",
"message": ""
}
```
### ErrorForbidden
- **Type:**`object`
* **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
* **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "forbidden",
"message": ""
}
```
### ErrorNotFound
- **Type:**`object`
* **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
* **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "not_found",
"message": ""
}
```
### ErrorMethodNotAllowed
- **Type:**`object`
* **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
* **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "method_not_allowed",
"message": ""
}
```
### ErrorConflict
- **Type:**`object`
* **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
* **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "conflict",
"message": ""
}
```
### ErrorTooManyRequests
- **Type:**`object`
* **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
* **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "too_many_requests",
"message": ""
}
```
### ErrorInternalServerError
- **Type:**`object`
* **`code` (required)**
`string`, possible values: `"bad_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "conflict", "too_many_requests", "payment_required", "internal_server_error"` — The error code related to the error.
* **`message` (required)**
`string` — A human-readable error message.
**Example:**
```json
{
"code": "internal_server_error",
"message": ""
}
```
### SignaturePlacement
- **Type:**`object`
* **`height` (required)**
`number`
* **`id` (required)**
`string`
* **`label` (required)**
`string`
* **`page` (required)**
`number`
* **`required` (required)**
`boolean`
* **`type` (required)**
`string`, possible values: `"signature", "text", "textarea", "select", "datetime", "checkbox"`
* **`width` (required)**
`number`
* **`x` (required)**
`number`
* **`y` (required)**
`number`
* **`options`**
`array`
**Items:**
`string`
**Example:**
```json
{
"id": "",
"type": "signature",
"label": "",
"required": true,
"page": 1,
"x": 1,
"y": 1,
"width": 1,
"height": 1,
"options": [
""
]
}
```
### SignatureTemplate
- **Type:**`object`
* **`builder_url` (required)**
`string`
* **`description` (required)**
`string`
* **`file_name` (required)**
`string`
* **`id` (required)**
`string`
* **`pages` (required)**
`array`
**Items:**
- **`height` (required)**
`number`
- **`page` (required)**
`number`
- **`width` (required)**
`number`
* **`placements` (required)**
`array`
**Items:**
- **`height` (required)**
`number`
- **`id` (required)**
`string`
- **`label` (required)**
`string`
- **`page` (required)**
`number`
- **`required` (required)**
`boolean`
- **`type` (required)**
`string`, possible values: `"signature", "text", "textarea", "select", "datetime", "checkbox"`
- **`width` (required)**
`number`
- **`x` (required)**
`number`
- **`y` (required)**
`number`
- **`options`**
`array`
**Items:**
`string`
* **`title` (required)**
`string`
* **`type` (required)**
`string`, possible values: `"signature"`
**Example:**
```json
{
"id": "",
"title": "",
"description": "",
"type": "signature",
"file_name": "",
"pages": [
{
"page": 1,
"width": 1,
"height": 1
}
],
"placements": [
{
"id": "",
"type": "signature",
"label": "",
"required": true,
"page": 1,
"x": 1,
"y": 1,
"width": 1,
"height": 1,
"options": [
""
]
}
],
"builder_url": ""
}
```
### CreateSignatureTemplateBody
- **Type:**`object`
* **`pdf` (required)**
`object` — The PDF to sign: exactly one of url or asset\_id. 10 MB at most.
- **`asset_id`**
`string`, format: `uuid` — The id of a PDF already in the firm's documents.
- **`url`**
`string`, format: `uri` — A public https URL of the PDF.
* **`title` (required)**
`string` — The template name.
* **`auto_detect`**
`boolean`, default: `false` — Also add the PDF's own form fields (a fillable PDF's text boxes, checkboxes, dropdowns and signature fields). They are added next to \`placements\` and listed in \`detected\`.
* **`description`**
`string` — Shown to the client above the document.
* **`placements`**
`array`, default: `[]` — The fields to place. Coordinates are PDF points (1/72 inch), the same numbers as the X, Y, W and H boxes in the portal builder: x from the left edge, y from the BOTTOM edge of the page to the bottom of the field. A US Letter page is 612 x 792.
**Items:**
- **`height` (required)**
`number` — Height in PDF points. At least 20 (8 for a checkbox).
- **`label` (required)**
`string` — What the client sees for this field, e.g. "Client Signature".
- **`page` (required)**
`integer` — The page it sits on, from 1.
- **`type` (required)**
`string`, possible values: `"signature", "text", "textarea", "select", "datetime", "checkbox"` — signature, text (one line), textarea (several lines), select (a dropdown, needs options), datetime (a date) or checkbox.
- **`width` (required)**
`number` — Width in PDF points. At least 20 (8 for a checkbox).
- **`x` (required)**
`number` — Left edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
- **`y` (required)**
`number` — Bottom edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
- **`options`**
`array` — The choices of a select field. Only valid on a select.
**Items:**
`string`
- **`required`**
`boolean` — Whether the client must fill it in. Defaults to true. Ignored for a checkbox, which is always optional.
**Example:**
```json
{
"title": "",
"description": "",
"pdf": {
"url": "",
"asset_id": ""
},
"placements": [],
"auto_detect": false
}
```
### SignaturePlacementInput
- **Type:**`object`
* **`height` (required)**
`number` — Height in PDF points. At least 20 (8 for a checkbox).
* **`label` (required)**
`string` — What the client sees for this field, e.g. "Client Signature".
* **`page` (required)**
`integer` — The page it sits on, from 1.
* **`type` (required)**
`string`, possible values: `"signature", "text", "textarea", "select", "datetime", "checkbox"` — signature, text (one line), textarea (several lines), select (a dropdown, needs options), datetime (a date) or checkbox.
* **`width` (required)**
`number` — Width in PDF points. At least 20 (8 for a checkbox).
* **`x` (required)**
`number` — Left edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
* **`y` (required)**
`number` — Bottom edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
* **`options`**
`array` — The choices of a select field. Only valid on a select.
**Items:**
`string`
* **`required`**
`boolean` — Whether the client must fill it in. Defaults to true. Ignored for a checkbox, which is always optional.
**Example:**
```json
{
"type": "signature",
"label": "",
"page": 1,
"x": 1,
"y": 1,
"width": 1,
"height": 1,
"required": true,
"options": [
""
]
}
```
### UpdateSignatureTemplateBody
- **Type:**`object`
* **`add_placements`**
`array` — New fields. Coordinates are PDF points (1/72 inch), the same numbers as the X, Y, W and H boxes in the portal builder: x from the left edge, y from the BOTTOM edge of the page to the bottom of the field. A US Letter page is 612 x 792.
**Items:**
- **`height` (required)**
`number` — Height in PDF points. At least 20 (8 for a checkbox).
- **`label` (required)**
`string` — What the client sees for this field, e.g. "Client Signature".
- **`page` (required)**
`integer` — The page it sits on, from 1.
- **`type` (required)**
`string`, possible values: `"signature", "text", "textarea", "select", "datetime", "checkbox"` — signature, text (one line), textarea (several lines), select (a dropdown, needs options), datetime (a date) or checkbox.
- **`width` (required)**
`number` — Width in PDF points. At least 20 (8 for a checkbox).
- **`x` (required)**
`number` — Left edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
- **`y` (required)**
`number` — Bottom edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
- **`options`**
`array` — The choices of a select field. Only valid on a select.
**Items:**
`string`
- **`required`**
`boolean` — Whether the client must fill it in. Defaults to true. Ignored for a checkbox, which is always optional.
* **`description`**
`string`
* **`remove_placement_ids`**
`array` — Ids of fields to remove.
**Items:**
`string`
* **`title`**
`string`
* **`update_placements`**
`array` — Changes to existing fields by id. Only the properties sent change.
**Items:**
- **`id` (required)**
`string` — The id of the placement to change.
- **`height`**
`number` — Height in PDF points. At least 20 (8 for a checkbox).
- **`label`**
`string` — What the client sees for this field, e.g. "Client Signature".
- **`options`**
`array` — The choices of a select field. Only valid on a select.
**Items:**
`string`
- **`page`**
`integer` — The page it sits on, from 1.
- **`required`**
`boolean` — Whether the client must fill it in. Defaults to true. Ignored for a checkbox, which is always optional.
- **`type`**
`string`, possible values: `"signature", "text", "textarea", "select", "datetime", "checkbox"` — signature, text (one line), textarea (several lines), select (a dropdown, needs options), datetime (a date) or checkbox.
- **`width`**
`number` — Width in PDF points. At least 20 (8 for a checkbox).
- **`x`**
`number` — Left edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
- **`y`**
`number` — Bottom edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
**Example:**
```json
{
"title": "",
"description": "",
"add_placements": [
{
"type": "signature",
"label": "",
"page": 1,
"x": 1,
"y": 1,
"width": 1,
"height": 1,
"required": true,
"options": [
""
]
}
],
"update_placements": [
{
"type": "signature",
"label": "",
"page": 1,
"x": 1,
"y": 1,
"width": 1,
"height": 1,
"required": true,
"options": [
""
],
"id": ""
}
],
"remove_placement_ids": [
""
]
}
```
### SignaturePlacementUpdate
- **Type:**`object`
* **`id` (required)**
`string` — The id of the placement to change.
* **`height`**
`number` — Height in PDF points. At least 20 (8 for a checkbox).
* **`label`**
`string` — What the client sees for this field, e.g. "Client Signature".
* **`options`**
`array` — The choices of a select field. Only valid on a select.
**Items:**
`string`
* **`page`**
`integer` — The page it sits on, from 1.
* **`required`**
`boolean` — Whether the client must fill it in. Defaults to true. Ignored for a checkbox, which is always optional.
* **`type`**
`string`, possible values: `"signature", "text", "textarea", "select", "datetime", "checkbox"` — signature, text (one line), textarea (several lines), select (a dropdown, needs options), datetime (a date) or checkbox.
* **`width`**
`number` — Width in PDF points. At least 20 (8 for a checkbox).
* **`x`**
`number` — Left edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
* **`y`**
`number` — Bottom edge in PDF points (1 pt = 1/72 inch). X is measured from the page's left edge, Y from its BOTTOM edge to the bottom of the box.
**Example:**
```json
{
"type": "signature",
"label": "",
"page": 1,
"x": 1,
"y": 1,
"width": 1,
"height": 1,
"required": true,
"options": [
""
],
"id": ""
}
```
### TaskList
- **Type:**`object`
* **`builder_url` (required)**
`string` — Where a human reviews and sends it. Give this to the caller — a list created by an agent should get one look before it reaches a client.
* **`case_id` (required)**
`string | null`, format: `uuid`
* **`id` (required)**
`string`, format: `uuid`
* **`item_ids` (required)**
`array`
**Items:**
`string`, format: `uuid`
* **`recipient_id` (required)**
`string | null`, format: `uuid`
* **`status` (required)**
`string` — Always "draft" on create. Nothing reaches the client until it is sent from the builder.
* **`title` (required)**
`string`
**Example:**
```json
{
"id": "",
"title": "",
"status": "",
"case_id": null,
"recipient_id": null,
"item_ids": [
""
],
"builder_url": ""
}
```
### CreateTaskListBody
- **Type:**`object`
* **`case_id` (required)**
`string`, format: `uuid` — The case this list belongs to.
* **`items` (required)**
`array` — The things the client has to do, in order.
**Items:**
- **`kind` (required)**
`string`, possible values: `"documents", "action"` — documents = upload a file. action = do something and mark it done.
- **`title` (required)**
`string` — What the client sees as the name of this item.
- **`count`**
`integer` — Documents items only: how many files the item asks for, e.g. 12 for "12 months of statements" or 3 for "3 years of tax returns". The client sees "3 of 12 uploaded" and the item completes when the last one lands. Omit for one file.
- **`description`**
`string` — Optional detail shown under the title.
- **`required`**
`boolean`, default: `true` — Whether the list can be completed without this item.
- **`url`**
`string`, format: `uri` — Action items only: a link the client opens before marking it done.
* **`recipient_id` (required)**
`string`, format: `uuid` — The client who receives it. Must be a member of the case.
* **`title` (required)**
`string` — The name of the list, shown to the client.
* **`description`**
`string`
* **`reminder_interval_days`**
`integer` — How often to remind the client while items stay open. Omit for the firm default.
**Example:**
```json
{
"title": "Estate planning — what we need from you",
"description": "",
"case_id": "",
"recipient_id": "",
"reminder_interval_days": 1,
"items": [
{
"kind": "documents",
"title": "Upload your most recent bank statement",
"description": "Any account held in your name, most recent month.",
"required": true,
"url": "https://example.com/intake",
"count": 12
}
]
}
```
### TaskListItem
- **Type:**`object`
* **`kind` (required)**
`string`, possible values: `"documents", "action"` — documents = upload a file. action = do something and mark it done.
* **`title` (required)**
`string` — What the client sees as the name of this item.
* **`count`**
`integer` — Documents items only: how many files the item asks for, e.g. 12 for "12 months of statements" or 3 for "3 years of tax returns". The client sees "3 of 12 uploaded" and the item completes when the last one lands. Omit for one file.
* **`description`**
`string` — Optional detail shown under the title.
* **`required`**
`boolean`, default: `true` — Whether the list can be completed without this item.
* **`url`**
`string`, format: `uri` — Action items only: a link the client opens before marking it done.
**Example:**
```json
{
"kind": "documents",
"title": "Upload your most recent bank statement",
"description": "Any account held in your name, most recent month.",
"required": true,
"url": "https://example.com/intake",
"count": 12
}
```
### TaskListTemplate
- **Type:**`object`
* **`description` (required)**
`string | null`
* **`id` (required)**
`string`, format: `uuid`
* **`item_count` (required)**
`integer`
* **`portal_url` (required)**
`string` — The portal Tasks page, where the template appears under "New from template".
* **`title` (required)**
`string`
**Example:**
```json
{
"id": "",
"title": "",
"description": null,
"item_count": 1,
"portal_url": ""
}
```
### CreateTaskListTemplateBody
- **Type:**`object`
* **`items` (required)**
`array` — The things the client will have to do, in order.
**Items:**
- **`kind` (required)**
`string`, possible values: `"documents", "action"` — documents = upload a file. action = do something and mark it done.
- **`title` (required)**
`string` — What the client sees as the name of this item.
- **`count`**
`integer` — Documents items only: how many files the item asks for, e.g. 12 for "12 months of statements" or 3 for "3 years of tax returns". The client sees "3 of 12 uploaded" and the item completes when the last one lands. Omit for one file.
- **`description`**
`string` — Optional detail shown under the title.
- **`required`**
`boolean`, default: `true` — Whether the list can be completed without this item.
- **`url`**
`string`, format: `uri` — Action items only: a link the client opens before marking it done.
* **`title` (required)**
`string` — The template name staff pick from "New from template". It also becomes the title of every list created from it, which the client sees.
* **`description`**
`string` — Optional intro, copied onto every list created from the template.
**Example:**
```json
{
"title": "New MVA case: what we need from you",
"description": "",
"items": [
{
"kind": "documents",
"title": "Upload your most recent bank statement",
"description": "Any account held in your name, most recent month.",
"required": true,
"url": "https://example.com/intake",
"count": 12
}
]
}
```
### TaskListTemplateSummary
- **Type:**`object`
* **`created_at` (required)**
`string`
* **`description` (required)**
`string | null`
* **`id` (required)**
`string`, format: `uuid`
* **`item_count` (required)**
`integer`
* **`title` (required)**
`string`
**Example:**
```json
{
"id": "",
"title": "",
"description": null,
"item_count": 1,
"created_at": ""
}
```
### TaskListTemplateDetail
- **Type:**`object`
* **`description` (required)**
`string | null`
* **`id` (required)**
`string`, format: `uuid`
* **`items` (required)**
`array`
**Items:**
- **`count` (required)**
`integer | null` — Documents items: how many files it asks for. Null means one.
- **`description` (required)**
`string | null`
- **`id` (required)**
`string`, format: `uuid` — The item id. Send it back in PATCH to keep or change this item.
- **`kind` (required)**
`string`, possible values: `"documents", "action", "form", "signature"`
- **`required` (required)**
`boolean | null` — Documents items: whether it must be done. Null otherwise.
- **`title` (required)**
`string`
- **`url` (required)**
`string | null` — Action items: the link the client opens first.
* **`portal_url` (required)**
`string`
* **`title` (required)**
`string`
**Example:**
```json
{
"id": "",
"title": "",
"description": null,
"items": [
{
"id": "",
"kind": "documents",
"title": "",
"description": null,
"required": null,
"url": null,
"count": null
}
],
"portal_url": ""
}
```
### TaskListTemplateItem
- **Type:**`object`
* **`count` (required)**
`integer | null` — Documents items: how many files it asks for. Null means one.
* **`description` (required)**
`string | null`
* **`id` (required)**
`string`, format: `uuid` — The item id. Send it back in PATCH to keep or change this item.
* **`kind` (required)**
`string`, possible values: `"documents", "action", "form", "signature"`
* **`required` (required)**
`boolean | null` — Documents items: whether it must be done. Null otherwise.
* **`title` (required)**
`string`
* **`url` (required)**
`string | null` — Action items: the link the client opens first.
**Example:**
```json
{
"id": "",
"kind": "documents",
"title": "",
"description": null,
"required": null,
"url": null,
"count": null
}
```
### UpdateTaskListTemplateBody
- **Type:**`object`
* **`description`**
`string | null` — The intro. null clears it; omit to leave it.
* **`items`**
`array` — The full list, in order, after the change. \`{ "id": ... }\` keeps an item as it is; an item with an id and content rewrites it; an item without an id is added. Any existing item left out is removed. Omit \`items\` to change only the title or description.
**Items:**
**Any of:**
- **`id` (required)**
`string`, format: `uuid` — An existing item id.
**All of:**
- **`kind` (required)**
`string`, possible values: `"documents", "action"` — documents = upload a file. action = do something and mark it done.
- **`title` (required)**
`string` — What the client sees as the name of this item.
- **`count`**
`integer` — Documents items only: how many files the item asks for, e.g. 12 for "12 months of statements" or 3 for "3 years of tax returns". The client sees "3 of 12 uploaded" and the item completes when the last one lands. Omit for one file.
- **`description`**
`string` — Optional detail shown under the title.
- **`required`**
`boolean`, default: `true` — Whether the list can be completed without this item.
- **`url`**
`string`, format: `uri` — Action items only: a link the client opens before marking it done.
* **`id`**
`string`, format: `uuid` — An existing item id to rewrite in place. Omit to add a new item.
* **`title`**
`string`
**Example:**
```json
{
"title": "",
"description": null,
"items": [
{
"id": ""
}
]
}
```