> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to VSCO Workspace (Tave)

The VSCO Workspace (Tave) connector lets your AI agent act in each user's VSCO Workspace (Tave) account. Each user connects their own VSCO Workspace (Tave) API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 165 tools.

**Authentication:** API Key
**Categories:** Project Management, CRM & Sales
**Tools:** 165: 75 read, 63 write, 27 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=TAVE)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the VSCO Workspace (Tave) connection

   In **AgentKit > Connections**, create a VSCO Workspace (Tave) connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'tave'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize VSCO Workspace (Tave):', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'tave_brands_list',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "tave"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize VSCO Workspace (Tave):", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="tave_brands_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their VSCO Workspace (Tave) credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'tave_brand_get',
  toolInput: {
    id: '<id>',
  },
  connector: 'tave',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="tave_brand_get",
    tool_input={
        "id": "<id>",
    },
    connection_name="tave",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `tave_brand_get`

Get Brand · Read-only

Get one brand by ID.
Returns the brand with name, alias, emails, phones, office hours, custom domain and theme colors.
Use tave_brand_get when you have the ID. Use tave_brands_list to browse brands.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the brand. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_brands_list`

List Brands · Read-only

List the studio's brands (the business identities used on client-facing pages and emails).
Returns the page of brands with id, name, alias, contact emails, phones and theme.
Use tave_brands_list to find a brand_id for tave_job_create or tave_contact_create. Use tave_brand_get for one brand by ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `external_mapping_id` (`string`, optional): Only objects linked to this ID in an external system (external mapping ID, up to 64 characters). Example: crm-1234.
- `include_hidden` (`boolean`, optional): true to include hidden brands. Example: false.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page, from 10 to 100 (default 100). Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified, created or name, optionally followed by asc or desc (default id). Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_contact_get`

Get Address Book Entry · Read-only

Get one address book entry by ID.
Returns the contact with name, emails, phones, address, custom fields and jobs.
Use tave_contact_get when you have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the address book entry. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.

Example input: `{"id":"<id>"}`

### `tave_contacts_list`

List Address Book · Read-only

List address book entries (people, companies and locations), optionally by email.
Returns the page of contacts with id, kind, name, email and phones.
Use tave_contacts_list to browse or match an email. Use tave_search for free-text search.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `email` (`string`, optional): Email address to match; results are ranked by match. Example: jamie@example.com.
- `include_hidden` (`boolean`, optional): true to include hidden entries. Example: false.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified, created, name, kind, accountBalance, anniversary, anonymized, bestDayToCall, bestTimeToCall, cellPhone, companyName, contactPreference, creditBalance, email, fax, firstName, gender, homePhone, jobTitle, lastName, maidenName, previousClient, privacyOptIn, requireStrictPrivacy, salutation, schoolGradYear, schoolName, sport, teamName, teamPosition or workPhone, optionally followed by asc or desc (default id). Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`, `kind`, `kind asc`, `kind desc`, `accountBalance`, `accountBalance asc`, `accountBalance desc`, `anniversary`, `anniversary asc`, `anniversary desc`, `anonymized`, `anonymized asc`, `anonymized desc`, `bestDayToCall`, `bestDayToCall asc`, `bestDayToCall desc`, `bestTimeToCall`, `bestTimeToCall asc`, `bestTimeToCall desc`, `cellPhone`, `cellPhone asc`, `cellPhone desc`, `companyName`, `companyName asc`, `companyName desc`, `contactPreference`, `contactPreference asc`, `contactPreference desc`, `creditBalance`, `creditBalance asc`, `creditBalance desc`, `email`, `email asc`, `email desc`, `fax`, `fax asc`, `fax desc`, `firstName`, `firstName asc`, `firstName desc`, `gender`, `gender asc`, `gender desc`, `homePhone`, `homePhone asc`, `homePhone desc`, `jobTitle`, `jobTitle asc`, `jobTitle desc`, `lastName`, `lastName asc`, `lastName desc`, `maidenName`, `maidenName asc`, `maidenName desc`, `previousClient`, `previousClient asc`, `previousClient desc`, `privacyOptIn`, `privacyOptIn asc`, `privacyOptIn desc`, `requireStrictPrivacy`, `requireStrictPrivacy asc`, `requireStrictPrivacy desc`, `salutation`, `salutation asc`, `salutation desc`, `schoolGradYear`, `schoolGradYear asc`, `schoolGradYear desc`, `schoolName`, `schoolName asc`, `schoolName desc`, `sport`, `sport asc`, `sport desc`, `teamName`, `teamName asc`, `teamName desc`, `teamPosition`, `teamPosition asc`, `teamPosition desc`, `workPhone`, `workPhone asc`, `workPhone desc`.

Example input: `{}`

### `tave_contract_get`

Get Contract · Read-only

Get one contract by ID.
Returns the contract with status, signatures and clientUrl.
Use tave_contract_get to check whether a contract was signed.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the contract. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_custom_field_get`

Get Custom Field · Read-only

Get one custom field definition by ID.
Returns the field with name, kind, canApplyTo, clientAccess, clientLabel, choices and token.
Use tave_custom_field_get when you have the ID. Use tave_custom_fields_list to browse fields.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the custom field. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_custom_fields_list`

List Custom Fields · Read-only

List the studio's custom fields for jobs and contacts, optionally by record type or kind.
Returns custom fields with id, name, kind, canApplyTo, clientAccess, choices and token.
Use tave_custom_fields_list to find which custom fields exist. Use tave_custom_field_get for one field by ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `can_apply_to` (`string`, optional): Only custom fields that apply to this record type: contact or job. Example: job. One of: `contact`, `job`.
- `kind` (`array`, optional): Only custom fields of these kinds: textfield, textbox, number, money, checkbox, date, decimal, dropdown, time. Example: ["dropdown", "date"].
- `sort_by` (`string`, optional): Sort order: id, modified, created or name, optionally followed by asc or desc (default id). Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_discount_get`

Get Discount · Read-only

Get one discount by ID.
Returns the discount with name, typeId, kind, price, description, sku and rebate flag.
Use tave_discount_get when you have the ID. Use tave_discounts_list to browse discounts.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the discount. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_discount_type_get`

Get Discount Type · Read-only

Get one discount type by ID.
Returns the discount type with name and parentId.
Use tave_discount_type_get when you have the ID. Use tave_discount_types_list to browse types.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the discount type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_discount_types_list`

List Discount Types · Read-only

List the studio's discount types (categories that group discounts).
Returns discount types with id, name and parentId.
Use tave_discount_types_list to get a type_id for tave_discount_create. Use tave_discounts_list for the discounts themselves.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sort_by` (`string`, optional): Sort order: id, modified, created or name, optionally followed by asc or desc (default id). Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_discounts_list`

List Discounts · Read-only

List the studio's discounts.
Returns discounts with id, name, typeId, kind, price, sku and rebate flag.
Use tave_discounts_list to find a discount. Use tave_discount_get for one discount by ID; use tave_discount_types_list for discount categories.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sort_by` (`string`, optional): Sort order: id, modified, created or name, optionally followed by asc or desc (default id). Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_event_get`

Get Event · Read-only

Get one event by ID.
Returns the event with type, times, timezone, location and job.
Use tave_event_get when you have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the event. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_event_type_get`

Get Event Type · Read-only

Get one event type by ID.
Returns the event type with name, kind, color, default duration, attendees, location and tokenPrefix.
Use tave_event_type_get when you have the ID. Use tave_event_types_list to browse types.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the event type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_event_types_list`

List Event Types · Read-only

List the studio's event types (for example engagement session, consultation, wedding).
Returns event types with id, name, kind, color, default duration and tokenPrefix.
Use tave_event_types_list to get the type_id for tave_event_create. Use tave_event_type_get for one type by ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `external_mapping_id` (`string`, optional): Only objects linked to this ID in an external system (external mapping ID, up to 64 characters). Example: crm-1234.
- `include_hidden` (`boolean`, optional): true to include hidden event types. Example: false.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page, from 10 to 100 (default 100). Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified, created or name, optionally followed by asc or desc (default id). Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_events_list`

List Events · Read-only

List calendar events (sessions, meetings, weddings), by job or date range.
Returns events with id, name, type, start, end, location and job.
Use tave_events_list for a schedule.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `job_id` (`string`, optional): Only records attached to this job ID. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `occurs_from` (`string`, optional): Only events ending on or after this date (YYYY-MM-DD). Example: 2026-12-01.
- `occurs_to` (`string`, optional): Only events starting on or before this date (YYYY-MM-DD). Example: 2026-12-31.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified, created, name or startDate, optionally followed by asc or desc (default id). Example: startDate asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`, `startDate`, `startDate asc`, `startDate desc`.

Example input: `{}`

### `tave_file_get`

Get File · Read-only

Get one file by ID.
Returns the file with filename, name, description, MIME type, size, download URL, file type and attachments.
Use tave_file_get when you already have the ID. Use tave_files_list to find files on a job or contact.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the file. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_file_type_get`

Get File Type · Read-only

Get one file type by ID.
Returns the file type with id, code name, name and description.
Use tave_file_type_get when you already have the ID. Use tave_file_types_list to browse file types.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the file type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_file_types_list`

List File Types · Read-only

List the studio's file types (the purpose categories files can be given).
Returns the page of file types with id, code name, name and description.
Use tave_file_types_list to get type_id for tave_file_create or tave_file_update. Use tave_file_type_get for one file type.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `include_hidden` (`boolean`, optional): true to include hidden (archived) records (default false). Example: false.
- `page` (`integer`, optional): Page of results, starting at 1 (default 1). Example: 1.
- `page_size` (`integer`, optional): Results per page, from 10 to 100 (default 100). Example: 50.
- `sort_by` (`string`, optional): Property to sort by (id, modified, created, name), optionally followed by a space and asc or desc. Default id. Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_files_list`

List Files · Read-only

List the studio's files, optionally filtered by job or contact.
Returns the page of files with id, filename, name, MIME type, size, URL, file type and attachments.
Use tave_files_list to find files on a job or contact. Use tave_file_get for one file by ID and tave_galleries_list for client photo galleries.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `contact_id` (`string`, optional): Only files attached to this address book contact (ULID). Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `external_mapping_id` (`string`, optional): Only records linked to this ID in your external system (set through an integration). Example: crm-12345.
- `include_hidden` (`boolean`, optional): true to include hidden (archived) records (default false). Example: false.
- `job_id` (`string`, optional): Only files attached to this job (ULID). Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `page` (`integer`, optional): Page of results, starting at 1 (default 1). Example: 1.
- `page_size` (`integer`, optional): Results per page, from 10 to 100 (default 100). Example: 50.
- `sort_by` (`string`, optional): Property to sort by (id, modified, created, name), optionally followed by a space and asc or desc. Default id. Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_galleries_list`

List Galleries · Read-only

List the studio's client galleries, optionally by name.
Returns galleries with id, name, job and status.
Use tave_galleries_list to find a gallery.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `name` (`string`, optional): Text the gallery name contains. Example: Rivera.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified, created or name, optionally followed by asc or desc (default name asc). Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_gallery_get`

Get Gallery · Read-only

Get one client gallery by ID.
Returns the gallery with name, status, URLs, job, event, dates, passcode settings and photo, order and visitor counts.
Use tave_gallery_get when you already have the ID. Use tave_galleries_list to find a gallery by name.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the gallery. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_invoice_get`

Get Invoice · Read-only

Get one invoice (order installment) by ID.
Returns the invoice with amount, due date, status and payments.
Use tave_invoice_get when you have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the invoice. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_invoices_list`

List Invoices · Read-only

List invoices (order installments), by status, due date range, job or past-due state.
Returns invoices with amount, due date, status, order and job.
Use tave_invoices_list with past_due true to chase late payments.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `due_from` (`string`, optional): Only invoices due on or after this date (YYYY-MM-DD). Example: 2026-11-01.
- `due_to` (`string`, optional): Only invoices due on or before this date (YYYY-MM-DD). Example: 2026-11-30.
- `job_id` (`string`, optional): Only records attached to this job ID. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `past_due` (`boolean`, optional): true for open invoices that are past due. Example: true.
- `sort_by` (`string`, optional): Sort order: id, modified, created, name, sortPosition or dueDate, optionally followed by asc or desc (default sortPosition). Example: dueDate asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`, `sortPosition`, `sortPosition asc`, `sortPosition desc`, `dueDate`, `dueDate asc`, `dueDate desc`.
- `status` (`string`, optional): Comma-separated statuses to include, for example draft,open. Example: open.

Example input: `{}`

### `tave_job_closed_reason_get`

Get Job Closed Reason · Read-only

Get one job closed reason by ID.
Returns the closed reason with name, description and whether it counts in reporting.
Use tave_job_closed_reason_get when you already have the ID. Use tave_job_closed_reasons_list to browse reasons.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job closed reason. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_job_closed_reasons_list`

List Job Closed Reasons · Read-only

List the studio's job closed reasons (why a lead or job was closed).
Returns the page of closed reasons with id, name, description and whether each counts in reporting.
Use tave_job_closed_reasons_list to get closed_reason_id for tave_job_update. Use tave_job_closed_reason_get for one reason.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `external_mapping_id` (`string`, optional): Only records linked to this ID in your external system (set through an integration). Example: crm-12345.
- `include_hidden` (`boolean`, optional): true to include hidden (archived) records (default false). Example: false.
- `page` (`integer`, optional): Page of results, starting at 1 (default 1). Example: 1.
- `page_size` (`integer`, optional): Results per page, from 10 to 100 (default 100). Example: 50.
- `sort_by` (`string`, optional): Property to sort by (id, modified, created, name), optionally followed by a space and asc or desc. Default id. Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_job_contact_get`

Get Job Contact · Read-only

Get one job contact (the link between a job and an address book contact) by ID.
Returns the job contact with job id, contact id, client flag, job roles and role kinds.
Use tave_job_contact_get when you already have the ID. Use tave_job_contacts_list to find the contacts on a job and tave_contact_get for the person's details.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job contact. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_job_contacts_list`

List Job Contacts · Read-only

List the contacts linked to jobs, by job or by contact.
Returns job contacts with jobId, contactId, client flag and roles.
Use tave_job_contacts_list to see who is on a job.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `contact_id` (`string`, optional): Only links for this contact ID. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `job_id` (`string`, optional): Only records attached to this job ID. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified or created, optionally followed by asc or desc (default id). Example: created desc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`.

Example input: `{}`

### `tave_job_get`

Get Job · Read-only

Get one job by ID.
Returns the job with name, stage, dates, lead details, totals and balances.
Use tave_job_get for job details.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.

Example input: `{"id":"<id>"}`

### `tave_job_orders_list`

List Job Orders · Read-only

List the orders (booked packages and invoices) on a job.
Returns orders with id, status, totals and balance.
Use tave_job_orders_list before applying a payment with tave_payment_apply.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `job_id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `sort_by` (`string`, optional): Sort order: id, modified, created, name, sortPosition or dueDate, optionally followed by asc or desc (default sortPosition). Example: created desc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`, `sortPosition`, `sortPosition asc`, `sortPosition desc`, `dueDate`, `dueDate asc`, `dueDate desc`.

Example input: `{"job_id":"<job_id>"}`

### `tave_job_payments_list`

List Job Payments · Read-only

List the payments on a job.
Returns payments with amount, status, received date and method.
Use tave_job_payments_list to check what a client has paid.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `sort_by` (`string`, optional): Sort order: id, modified or created, optionally followed by asc or desc (default id). Example: created desc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`.

Example input: `{"id":"<id>"}`

### `tave_job_role_get`

Get Job Role · Read-only

Get one job role by ID.
Returns the job role with name, kind, token prefix and sort position.
Use tave_job_role_get when you already have the ID. Use tave_job_roles_list to browse roles.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job role. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_job_roles_list`

List Job Roles · Read-only

List the studio's job roles (for example Bride, Groom, Planner, Second Shooter).
Returns the page of job roles with id, name, kind, token prefix and sort position.
Use tave_job_roles_list to get job role IDs for tave_job_contact_create or tave_job_contact_update. Use tave_job_role_get for one role.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `external_mapping_id` (`string`, optional): Only records linked to this ID in your external system (set through an integration). Example: crm-12345.
- `include_hidden` (`boolean`, optional): true to include hidden (archived) records (default false). Example: false.
- `page` (`integer`, optional): Page of results, starting at 1 (default 1). Example: 1.
- `page_size` (`integer`, optional): Results per page, from 10 to 100 (default 100). Example: 50.
- `sort_by` (`string`, optional): Property to sort by (id, modified, created, name, sortPosition), optionally followed by a space and asc or desc. Default sortPosition. Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`, `sortPosition`, `sortPosition asc`, `sortPosition desc`.

Example input: `{}`

### `tave_job_type_get`

Get Job Type · Read-only

Get one job type by ID.
Returns the job type with name, initial lead status, profit center, workflow, default contacts and default events.
Use tave_job_type_get when you already have the ID. Use tave_job_types_list to browse job types.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_job_types_list`

List Job Types · Read-only

List the studio's job types.
Returns job types with id and name.
Use tave_job_types_list to get job_type_id for tave_job_create.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.

Example input: `{}`

### `tave_job_worksheet_get`

Get Job Worksheet · Read-only

Get a job's worksheet: its contacts, events and custom fields in one document.
Returns the worksheet.
Use tave_job_worksheet_get for a full job overview.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `job_id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.

Example input: `{"job_id":"<job_id>"}`

### `tave_jobs_list`

List Jobs · Read-only

List jobs and leads, filtered by stage, lead status, event date range or stale date.
Returns the page of jobs with id, name, stage, event date, lead status and totals.
Use tave_jobs_list to find a job or pipeline. Use tave_search for free text.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `event_date_from` (`string`, optional): Only jobs with an event on or after this date (YYYY-MM-DD). Example: 2027-01-01.
- `event_date_to` (`string`, optional): Only jobs with an event on or before this date (YYYY-MM-DD). Example: 2027-12-31.
- `include_closed` (`boolean`, optional): true to include closed jobs. Example: false.
- `lead_status_id` (`string`, optional): Only jobs with this lead status ID. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified, created, name, accountBalance, bookingDate, closed, closedDate, completedDate, creditBalance, customNumber, eventDate, fulfillmentDate, guestCount, inquiryDate, lastClientActivity, leadConfidence, leadDecisionExpectedByDate, leadMaxBudget, leadRating, leadStatusChangedAt, pinned, previousInteractionDate, stage, staleDate, title, totalCost, totalGratuity, totalProfit, totalRevenue or webLead, optionally followed by asc or desc (default id). Example: eventDate desc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`, `accountBalance`, `accountBalance asc`, `accountBalance desc`, `bookingDate`, `bookingDate asc`, `bookingDate desc`, `closed`, `closed asc`, `closed desc`, `closedDate`, `closedDate asc`, `closedDate desc`, `completedDate`, `completedDate asc`, `completedDate desc`, `creditBalance`, `creditBalance asc`, `creditBalance desc`, `customNumber`, `customNumber asc`, `customNumber desc`, `eventDate`, `eventDate asc`, `eventDate desc`, `fulfillmentDate`, `fulfillmentDate asc`, `fulfillmentDate desc`, `guestCount`, `guestCount asc`, `guestCount desc`, `inquiryDate`, `inquiryDate asc`, `inquiryDate desc`, `lastClientActivity`, `lastClientActivity asc`, `lastClientActivity desc`, `leadConfidence`, `leadConfidence asc`, `leadConfidence desc`, `leadDecisionExpectedByDate`, `leadDecisionExpectedByDate asc`, `leadDecisionExpectedByDate desc`, `leadMaxBudget`, `leadMaxBudget asc`, `leadMaxBudget desc`, `leadRating`, `leadRating asc`, `leadRating desc`, `leadStatusChangedAt`, `leadStatusChangedAt asc`, `leadStatusChangedAt desc`, `pinned`, `pinned asc`, `pinned desc`, `previousInteractionDate`, `previousInteractionDate asc`, `previousInteractionDate desc`, `stage`, `stage asc`, `stage desc`, `staleDate`, `staleDate asc`, `staleDate desc`, `title`, `title asc`, `title desc`, `totalCost`, `totalCost asc`, `totalCost desc`, `totalGratuity`, `totalGratuity asc`, `totalGratuity desc`, `totalProfit`, `totalProfit asc`, `totalProfit desc`, `totalRevenue`, `totalRevenue asc`, `totalRevenue desc`, `webLead`, `webLead asc`, `webLead desc`.
- `stage` (`string`, optional): Comma-separated stages to include: lead, booked, fulfillment, completed. Example: lead,booked.

Example input: `{}`

### `tave_lead_source_get`

Get Lead Source · Read-only

Get one lead source by ID.
Returns the lead source with id, name, parent ID and hidden flag.
Use tave_lead_source_get for one source. Use tave_lead_sources_list to browse sources or find an ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the lead source. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_lead_sources_list`

List Lead Sources · Read-only

List the studio's lead sources.
Returns lead sources with id and name.
Use tave_lead_sources_list to get lead_source_id for tave_job_create.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.

Example input: `{}`

### `tave_lead_status_get`

Get Lead Status · Read-only

Get one lead status by ID.
Returns the lead status with name, kind, color, sort position and its automatic transition settings.
Use tave_lead_status_get for one status. Use tave_lead_statuses_list to browse statuses or find an ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the lead status. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_lead_statuses_list`

List Lead Statuses · Read-only

List the studio's lead statuses.
Returns lead statuses with id and name.
Use tave_lead_statuses_list to filter or set a lead's status.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.

Example input: `{}`

### `tave_location_address_get`

Get Location Address · Read-only

Get the street address of a location entry in the address book.
Returns the address with street, city, state, postal code, country code and country name.
Use tave_location_address_get for just the address of a venue. Use tave_contact_get for the full address book entry.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the address book entry of kind location (from tave_contacts_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_mail_message_get`

Get Mail Message · Read-only

Get one email message by ID.
Returns the message with subject, body, sender, recipients and attachments.
Use tave_mail_message_get to read a full email.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the mail message. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_mail_messages_list`

List Job Mail Messages · Read-only

List the email messages of a job, by direction, send status or thread.
Returns messages with subject, from, to, when, kind and sendStatus.
Use tave_mail_messages_list to read client correspondence.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `job_id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `kind` (`string`, optional): Message direction. Example: Incoming. One of: `Incoming`, `Outgoing`, `BCC`.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `send_status` (`string`, optional): Send status. Example: Sent. One of: `Draft`, `Queued`, `Sent`.
- `sort_by` (`string`, optional): Sort order: when, id, modified or created, optionally followed by asc or desc (default when desc). Example: when desc. One of: `when`, `when asc`, `when desc`, `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`.
- `thread_id` (`string`, optional): Only this conversation thread ID. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"job_id":"<job_id>"}`

### `tave_note_get`

Get Note · Read-only

Get one note by ID.
Returns the note with its HTML content, date, and linked job and contact.
Use tave_note_get to read one note. Use tave_notes_list to find notes on a job or contact.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the note. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `expand` (`string`, optional): Related object to include inline: Note.author adds the author's contact record. Example: Note.author. One of: `Note.author`.

Example input: `{"id":"<id>"}`

### `tave_notes_list`

List Notes · Read-only

List notes, optionally for a job.
Returns notes with contentHtml, date, author, job and contact.
Use tave_notes_list to read a job's history.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `job_id` (`string`, optional): Only records attached to this job ID. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified or created, optionally followed by asc or desc (default id). Example: created desc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`.

Example input: `{}`

### `tave_order_get`

Get Order · Read-only

Get one order by ID.
Returns the order with line items, totals, taxes, installments and balance.
Use tave_order_get for order details.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the order. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_orders_list`

List Orders · Read-only

List orders across the studio.
Returns orders with job, status, totals and balance.
Use tave_orders_list for sales; use tave_job_orders_list for one job.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified, created, name, sortPosition or dueDate, optionally followed by asc or desc (default sortPosition). Example: created desc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`, `sortPosition`, `sortPosition asc`, `sortPosition desc`, `dueDate`, `dueDate asc`, `dueDate desc`.

Example input: `{}`

### `tave_payment_get`

Get Payment · Read-only

Get one payment by ID.
Returns the payment with amount, refunded amount, status, received date, payer, payment method, allocations and refunds.
Use tave_payment_get for one payment. Use tave_payments_list or tave_job_payments_list to find payments.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the payment. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_payment_method_get`

Get Payment Method · Read-only

Get one payment method by ID.
Returns the payment method with id, name and kind (Cash, Check, CreditCard, EFT, PayPal or Google).
Use tave_payment_method_get to check one method. Use tave_payment_methods_list to find a payment_method_id.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the payment method. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_payment_methods_list`

List Payment Methods · Read-only

List the studio's payment methods.
Returns methods with id and name.
Use tave_payment_methods_list to get payment_method_id for tave_payment_create.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sort_by` (`string`, optional): Sort order: id, modified, created or sortPosition, optionally followed by asc or desc (default sortPosition). Example: created desc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `sortPosition`, `sortPosition asc`, `sortPosition desc`.

Example input: `{}`

### `tave_payments_list`

List Payments · Read-only

List payments across the studio.
Returns payments with job, amount, status, received date and method.
Use tave_payments_list for cash flow; use tave_job_payments_list for one job.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified or created, optionally followed by asc or desc (default id). Example: created desc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`.

Example input: `{}`

### `tave_product_get`

Get Product · Read-only

Get one product by ID.
Returns the product with price, description, tax and expenses.
Use tave_product_get when you have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the product. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_product_type_get`

Get Product Type · Read-only

Get one product type by ID.
Returns the product type with id, name, kind and parent ID.
Use tave_product_type_get for one type. Use tave_product_types_list to browse types or find an ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the product type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_product_types_list`

List Product Types · Read-only

List the studio's product types, the categories products belong to.
Returns product types with id, name, kind (Session, Album, Print, Service or Other) and parent ID.
Use tave_product_types_list to find the type ID for tave_product_create or tave_product_update. Use tave_product_type_get for one type.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sort_by` (`string`, optional): Property to sort by: id, modified, created or name, optionally followed by asc or desc. Defaults to id. Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_products_list`

List Products · Read-only

List the studio's products and services.
Returns products with name, price, sku and taxable.
Use tave_products_list to find product IDs for quotes.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sort_by` (`string`, optional): Sort order: id, modified, created or name, optionally followed by asc or desc (default id). Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_profit_center_get`

Get Profit Center · Read-only

Get one profit center by ID.
Returns the profit center with id, name and hidden flag.
Use tave_profit_center_get for one profit center. Use tave_profit_centers_list to browse or find IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the profit center. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_profit_centers_list`

List Profit Centers · Read-only

List the studio's profit centers, the revenue categories products are reported under.
Returns the page of profit centers with id, name and hidden flag.
Use tave_profit_centers_list to find a profit center ID. Use tave_profit_center_get for one profit center by ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `external_mapping_id` (`string`, optional): Only profit centers linked to this ID in an external system, up to 64 characters. Example: qb-income-4000.
- `include_hidden` (`boolean`, optional): true to include hidden (archived) entries. Defaults to false. Example: false.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page, from 10 to 100. Defaults to 100. Example: 50.
- `sort_by` (`string`, optional): Property to sort by, optionally followed by asc or desc: id, modified, created, name. Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_quote_get`

Get Quote · Read-only

Get one quote by ID.
Returns the quote with options, prices, recipients and status.
Use tave_quote_get before booking or sending a quote.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the quote. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_quotes_list`

List Quotes · Read-only

List quotes across the studio.
Returns quotes with job, name, status, expiration and options.
Use tave_quotes_list to follow up on open quotes.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified, created or name, optionally followed by asc or desc (default id). Example: created desc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_rest_hook_get`

Get REST Hook · Read-only

Get one REST Hook webhook subscription by ID.
Returns the subscription with id, event, target url and limitTo filters.
Use tave_rest_hook_get to inspect a subscription. Use tave_rest_hooks_list to find IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the REST Hook subscription. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_rest_hooks_list`

List REST Hooks · Read-only

List the studio's REST Hook webhook subscriptions.
Returns the page of subscriptions with id, event, target url and limitTo filters.
Use tave_rest_hooks_list to audit or find a subscription ID. Use tave_rest_hook_get for one subscription.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `include_hidden` (`boolean`, optional): true to include hidden (archived) entries. Defaults to false. Example: false.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page, from 10 to 100. Defaults to 100. Example: 50.
- `sort_by` (`string`, optional): Property to sort by, optionally followed by asc or desc: id, modified, created. Example: created desc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`.

Example input: `{}`

### `tave_search`

Search Studio · Read-only

Free-text search within one resource type: jobs, contacts, events, notes, orders, payments or addresses.
Returns ranked matches of that type.
Use tave_search when you know a name or phrase but not the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `q` (`string`, required): Text to search for. Example: Rivera.
- `scope` (`string`, required): Resource type to search. Example: job. One of: `job`, `contact`, `event`, `note`, `order`, `payment`, `address`.

Example input: `{"q":"<q>","scope":"job"}`

### `tave_studio_get`

Get My Studio · Read-only

Get the studio the API key belongs to.
Returns the studio with name, currency, timezone and settings.
Use tave_studio_get to check the connection and the studio's currency.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `tave_task_get`

Get Task · Read-only

Get one task by ID.
Returns the task with name, due date, assignee and completion.
Use tave_task_get when you have the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the task. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_task_list_get`

Get Task List · Read-only

Get one task list (a job workflow checklist) by ID.
Returns the task list with id, name, jobId, userId, dueDate, stage, completed and starred.
Use tave_task_list_get for one task list. Use tave_task_lists_list to find IDs and tave_tasks_list with task_list_id for its tasks.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the task list. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_task_lists_list`

List Task Lists · Read-only

List the studio's task lists.
Returns task lists with id and name.
Use tave_task_lists_list to get the task_list_id for tave_task_create.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.

Example input: `{}`

### `tave_tasks_list`

List Tasks · Read-only

List tasks, filtered by job, task list, assignee or completion.
Returns tasks with name, dueDate, completed, user and job.
Use tave_tasks_list for to-dos.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `completed` (`boolean`, optional): true for done tasks, false for open tasks. Example: false.
- `job_id` (`string`, optional): Only records attached to this job ID. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified, created, name or sortPosition, optionally followed by asc or desc (default sortPosition). Example: created desc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`, `sortPosition`, `sortPosition asc`, `sortPosition desc`.
- `task_list_id` (`string`, optional): Only tasks in this task list ID. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `user_id` (`string`, optional): Only tasks assigned to this user ID. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{}`

### `tave_tax_group_get`

Get Tax Group · Read-only

Get one tax group by ID.
Returns the tax group with id, name, taxRates, compounding and default.
Use tave_tax_group_get for one tax group. Use tave_tax_groups_list to find IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the tax group. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_tax_groups_list`

List Tax Groups · Read-only

List the studio's tax groups (sets of up to 3 tax rates applied together).
Returns tax groups with id, name, taxRates, compounding and default.
Use tave_tax_groups_list to find a tax group ID. Use tave_tax_rates_list for individual rates.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sort_by` (`string`, optional): Property to sort by, optionally followed by asc or desc: id, modified, created, name. Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_tax_rate_get`

Get Tax Rate · Read-only

Get one tax rate by ID.
Returns the tax rate with id, name, rate (percentage) and inclusive.
Use tave_tax_rate_get for one tax rate. Use tave_tax_rates_list to find IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the tax rate. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_tax_rates_list`

List Tax Rates · Read-only

List the studio's tax rates.
Returns tax rates with id, name, rate (percentage) and inclusive.
Use tave_tax_rates_list to find a tax rate ID. Use tave_tax_groups_list for grouped rates.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `sort_by` (`string`, optional): Property to sort by, optionally followed by asc or desc: id, modified, created, name. Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`.

Example input: `{}`

### `tave_timezone_get`

Get Timezone · Read-only

Get one timezone by ID.
Returns the timezone with name, displayName, code, daylightCode, city, country and region.
Use tave_timezone_get to resolve a timezoneId (for example from tave_studio_get). Use tave_timezones_list to search.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the timezone. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_timezones_list`

List Timezones · Read-only

List the timezones VSCO Workspace supports, optionally searched by name, code or country.
Returns the page of timezones with id, name (for example America/New_York), displayName, code, country and region.
Use tave_timezones_list to find a timezone ID for tave_studio_update. Use tave_timezone_get for one timezone by ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page, from 10 to 100. Defaults to 100. Example: 50.
- `search` (`string`, optional): Text to match against timezone name, code, country and other fields. Example: New_York.
- `sort_by` (`string`, optional): Property to sort by, optionally followed by asc or desc: id, modified, created, name, usage. Example: name asc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`, `name`, `name asc`, `name desc`, `usage`, `usage asc`, `usage desc`.

Example input: `{}`

### `tave_user_get`

Get User · Read-only

Get one studio user (team member) by ID.
Returns the user with id, username, contactId, isAdmin and isBillingContact.
Use tave_user_get for one user. Use tave_users_list to find IDs; read the user's name with tave_contact_get on contactId.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the user. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_users_list`

List Users · Read-only

List the studio's users (team members).
Returns users with id, name and email.
Use tave_users_list to get user IDs for task assignment.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page of results, starting at 1. Example: 1.
- `page_size` (`integer`, optional): Results per page. Example: 50.
- `sort_by` (`string`, optional): Sort order: id, modified or created, optionally followed by asc or desc (default id). Example: created desc. One of: `id`, `id asc`, `id desc`, `modified`, `modified asc`, `modified desc`, `created`, `created asc`, `created desc`.

Example input: `{}`

### `tave_brand_create`

Create Brand · Write

Create a brand: a business identity with its own name, emails, phones and theme for client-facing pages.
Returns the new brand with its id.
Use tave_brand_create to add a second business line. Use tave_brand_update to change an existing brand.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Brand name, 4 to 128 characters. Example: Rivera Photography.
- `alias` (`string`, optional): Short unique alias for the brand, 4 to 32 characters. Example: rivera.
- `bcc` (`string`, optional): Email address that is BCC'd on emails sent under this brand. Example: archive@riveraphoto.com.
- `breakout_package_pricing` (`boolean`, optional): true to show the price of each item inside a package. Example: false.
- `custom_domain` (`string`, optional): Custom domain for the brand's client portal, up to 128 characters. Example: clients.riveraphoto.com.
- `enable_profile_edit` (`boolean`, optional): true to let clients edit their profile in the client portal. Example: true.
- `forward_to` (`string`, optional): Email address that incoming brand email is forwarded to. Example: studio@riveraphoto.com.
- `google_analytics_id` (`string`, optional): Google Analytics tracking ID in the form UA-, YT- or MO- followed by two number groups. Example: UA-12345678-1.
- `location_id` (`string`, optional): ULID of a location entry in the address book (kind location, from tave_contacts_list) used as the brand's address. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `office_hours` (`string`, optional): Office hours text shown to clients, up to 255 characters. Example: Mon-Fri 9am-5pm.
- `phone1_label` (`string`, optional): Label for brand phone 1, 1 to 64 characters. Example: Office.
- `phone1_number` (`string`, optional): Brand phone 1 number as free text, up to 24 characters. Example: (555) 010-1234.
- `phone2_label` (`string`, optional): Label for brand phone 2, 1 to 64 characters. Example: Mobile.
- `phone2_number` (`string`, optional): Brand phone 2 number as free text, up to 24 characters. Example: (555) 010-5678.
- `phone3_label` (`string`, optional): Label for brand phone 3, 1 to 64 characters. Example: Fax.
- `phone3_number` (`string`, optional): Brand phone 3 number as free text, up to 24 characters. Example: (555) 010-9012.
- `reply_to` (`string`, optional): Reply-to email address for emails sent under this brand. Example: hello@riveraphoto.com.
- `root_contact_form_id` (`string`, optional): ULID of the brand's main contact form. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `short_name` (`string`, optional): Shorter brand name for constrained places in the UI, 4 to 128 characters. Example: Rivera Photo.
- `show_history_in_portal` (`boolean`, optional): true to show the job history in the client portal. Example: true.
- `theme_colors` (`object`, optional): Theme colors as an object of lowercase 6-digit hex values without #; keys: accent, background, box, error, footerText, link, print, text. Example: {"accent": "c0392b", "background": "ffffff", "text": "222222"}.

Example input: `{"name":"<name>"}`

### `tave_brand_update`

Update Brand · Write

Update a brand's name, emails, phones, portal settings or theme (PUT replaces the brand: read it with tave_brand_get first and resend fields you want to keep).
Returns the updated brand.
Use tave_brand_update to change an existing brand. Use tave_brand_create for a new one.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the brand. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `alias` (`string`, optional): Short unique alias for the brand, 4 to 32 characters. Example: rivera.
- `bcc` (`string`, optional): Email address that is BCC'd on emails sent under this brand. Example: archive@riveraphoto.com.
- `breakout_package_pricing` (`boolean`, optional): true to show the price of each item inside a package. Example: false.
- `custom_domain` (`string`, optional): Custom domain for the brand's client portal, up to 128 characters. Example: clients.riveraphoto.com.
- `enable_profile_edit` (`boolean`, optional): true to let clients edit their profile in the client portal. Example: true.
- `forward_to` (`string`, optional): Email address that incoming brand email is forwarded to. Example: studio@riveraphoto.com.
- `google_analytics_id` (`string`, optional): Google Analytics tracking ID in the form UA-, YT- or MO- followed by two number groups. Example: UA-12345678-1.
- `location_id` (`string`, optional): ULID of a location entry in the address book (kind location, from tave_contacts_list) used as the brand's address. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, optional): Brand name, 4 to 128 characters. Example: Rivera Photography.
- `office_hours` (`string`, optional): Office hours text shown to clients, up to 255 characters. Example: Mon-Fri 9am-5pm.
- `phone1_label` (`string`, optional): Label for brand phone 1, 1 to 64 characters. Example: Office.
- `phone1_number` (`string`, optional): Brand phone 1 number as free text, up to 24 characters. Example: (555) 010-1234.
- `phone2_label` (`string`, optional): Label for brand phone 2, 1 to 64 characters. Example: Mobile.
- `phone2_number` (`string`, optional): Brand phone 2 number as free text, up to 24 characters. Example: (555) 010-5678.
- `phone3_label` (`string`, optional): Label for brand phone 3, 1 to 64 characters. Example: Fax.
- `phone3_number` (`string`, optional): Brand phone 3 number as free text, up to 24 characters. Example: (555) 010-9012.
- `reply_to` (`string`, optional): Reply-to email address for emails sent under this brand. Example: hello@riveraphoto.com.
- `root_contact_form_id` (`string`, optional): ULID of the brand's main contact form. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `short_name` (`string`, optional): Shorter brand name for constrained places in the UI, 4 to 128 characters. Example: Rivera Photo.
- `show_history_in_portal` (`boolean`, optional): true to show the job history in the client portal. Example: true.
- `theme_colors` (`object`, optional): Theme colors as an object of lowercase 6-digit hex values without #; keys: accent, background, box, error, footerText, link, print, text. Example: {"accent": "c0392b", "background": "ffffff", "text": "222222"}.

Example input: `{"id":"<id>"}`

### `tave_contact_create`

Create Address Book Entry · Write

Create an address book entry: a person, company or location.
Returns the new contact with its id.
Use tave_contact_create before adding the contact to a job with tave_job_contact_create.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `brand_id` (`string`, optional): ULID of the studio brand the contact belongs to. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `cell_phone` (`string`, optional): Mobile phone number (person or company). Example: +15125550101.
- `company_name` (`string`, optional): Company a person works for. Example: Rivera Events.
- `email` (`string`, optional): Email address. Example: jamie@example.com.
- `first_name` (`string`, optional): First name of a person. Example: Jamie.
- `kind` (`string`, optional): Type of address book entry: person (default), company or location. Example: person. One of: `person`, `company`, `location`.
- `last_name` (`string`, optional): Last name of a person. Example: Rivera.
- `name` (`string`, optional): Name of a company or location (for a person it is built from first and last name). Example: Rivera Events.
- `notes` (`string`, optional): Notes about the contact. Example: Prefers email contact.

Example input: `{}`

### `tave_contact_update`

Update Address Book Entry · Write

Update an address book entry (PUT replaces the entry: read it with tave_contact_get first and resend fields you want to keep).
Returns the updated contact.
Use tave_contact_update to fix a name, email or phone.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the address book entry. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `brand_id` (`string`, optional): ULID of the studio brand the contact belongs to. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `cell_phone` (`string`, optional): Mobile phone number (person or company). Example: +15125550101.
- `company_name` (`string`, optional): Company a person works for. Example: Rivera Events.
- `email` (`string`, optional): Email address. Example: jamie@example.com.
- `first_name` (`string`, optional): First name of a person. Example: Jamie.
- `kind` (`string`, optional): Type of address book entry: person (default), company or location. Example: person. One of: `person`, `company`, `location`.
- `last_name` (`string`, optional): Last name of a person. Example: Rivera.
- `name` (`string`, optional): Name of a company or location (for a person it is built from first and last name). Example: Rivera Events.
- `notes` (`string`, optional): Notes about the contact. Example: Prefers email contact.

Example input: `{"id":"<id>"}`

### `tave_contract_create`

Create Contract · Write

Create a contract on a job, from a template or with its own text.
Returns the new contract with clientUrl.
Use tave_contract_create after booking; the client signs it at clientUrl.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `job_id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `body_html` (`string`, optional): Contract text (HTML), when not using a template. Example: This agreement is between...
.
- `contract_template_id` (`string`, optional): ULID of a contract template to copy. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `counter_signature_label` (`string`, optional): Studio countersignature label. Example: Photographer.
- `name` (`string`, optional): Contract name. Example: Wedding photography agreement.
- `order_id` (`string`, optional): ULID of the order the contract covers. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `recipient_id` (`string`, optional): ULID of the contact who signs. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `signature_labels` (`string`, optional): Client signature field labels, one per line. Example: Client 1
Client 2.

Example input: `{"job_id":"<job_id>"}`

### `tave_custom_field_create`

Create Custom Field · Write

Create a custom field for jobs or contacts, such as a text box, date or drop-down.
Returns the new custom field with its id.
Use tave_custom_field_create to track extra details. Use tave_custom_field_update to change an existing field.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Custom field name shown to the studio, up to 255 characters. Example: Venue Coordinator.
- `can_apply_to` (`string`, optional): Record type the field applies to: Job (default) or Contact. Example: Job. One of: `Job`, `Contact`.
- `choices` (`array`, optional): Options for a DropDown field. Example: ["Indoor", "Outdoor"].
- `client_access` (`string`, optional): What clients can do with the field in the client portal: None (default), Visible or Editable. Example: Visible. One of: `None`, `Visible`, `Editable`.
- `client_label` (`string`, optional): Label shown to clients instead of the name, up to 255 characters. Example: Your venue coordinator.
- `kind` (`string`, optional): Field type: TextField (default), TextBox, DropDown, Number, Decimal, Money, Date, Time or Checkbox. Example: DropDown. One of: `TextField`, `TextBox`, `DropDown`, `Number`, `Decimal`, `Money`, `Date`, `Time`, `Checkbox`.
- `token` (`string`, optional): Placeholder token used to insert the field's value in templates, up to 128 characters. Example: venue_coordinator.

Example input: `{"name":"<name>"}`

### `tave_custom_field_update`

Update Custom Field · Write

Update a custom field definition (PUT replaces the field: read it with tave_custom_field_get first and resend fields you want to keep).
Returns the updated custom field.
Use tave_custom_field_update to rename a field or change its choices or client access. Use tave_custom_field_create for a new field.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the custom field. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `can_apply_to` (`string`, optional): Record type the field applies to: Job (default) or Contact. Example: Job. One of: `Job`, `Contact`.
- `choices` (`array`, optional): Options for a DropDown field. Example: ["Indoor", "Outdoor"].
- `client_access` (`string`, optional): What clients can do with the field in the client portal: None (default), Visible or Editable. Example: Visible. One of: `None`, `Visible`, `Editable`.
- `client_label` (`string`, optional): Label shown to clients instead of the name, up to 255 characters. Example: Your venue coordinator.
- `kind` (`string`, optional): Field type: TextField (default), TextBox, DropDown, Number, Decimal, Money, Date, Time or Checkbox. Example: DropDown. One of: `TextField`, `TextBox`, `DropDown`, `Number`, `Decimal`, `Money`, `Date`, `Time`, `Checkbox`.
- `name` (`string`, optional): Custom field name shown to the studio, up to 255 characters. Example: Venue Coordinator.
- `token` (`string`, optional): Placeholder token used to insert the field's value in templates, up to 128 characters. Example: venue_coordinator.

Example input: `{"id":"<id>"}`

### `tave_discount_create`

Create Discount · Write

Create a discount (a fixed amount or percentage) under a discount type.
Returns the new discount with its id.
Use tave_discount_create to add a discount. Get type_id from tave_discount_types_list or create one with tave_discount_type_create.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Discount name, up to 128 characters. Example: Returning client.
- `price` (`integer`, required): Discount value, a non-negative integer. For kind Amount, an amount in the studio's currency in minor units (for example 15000 for 150.00; compare with an existing record from tave_discounts_list if unsure); for kind Percent, the percentage. Example: 15000.
- `type_id` (`string`, required): ULID of the discount type (from tave_discount_types_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `description_html` (`string`, optional): Description (HTML). Example: For past clients.
.
- `kind` (`string`, optional): How price is applied: Amount (fixed amount) or Percent. Example: Amount. One of: `Amount`, `Percent`.
- `manual_entry` (`boolean`, optional): true (default) to let the studio enter the amount when adding the discount. Example: true.
- `rebate` (`boolean`, optional): true if the discount is a rebate (default false). Example: false.
- `sku` (`string`, optional): Stock keeping unit, up to 48 characters. Example: DISC-RET.

Example input: `{"name":"<name>","price":15000,"type_id":"<type_id>"}`

### `tave_discount_type_create`

Create Discount Type · Write

Create a discount type, optionally nested under a parent type.
Returns the new discount type with its id.
Use tave_discount_type_create before tave_discount_create when no suitable type exists in tave_discount_types_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Discount type name, up to 255 characters. Example: Loyalty.
- `parent_id` (`string`, optional): ULID of a parent discount type, to nest this type under it. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"name":"<name>"}`

### `tave_event_create`

Create Event · Write

Create a calendar event, optionally on a job.
Returns the new event.
Use tave_event_create to schedule a session or consultation.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `all_day` (`boolean`, optional): true for an all-day event. Example: false.
- `channel` (`string`, optional): How the event happens. Example: InPerson. One of: `InPerson`, `Phone`, `Virtual`.
- `confirmed` (`boolean`, optional): true if the event is confirmed. Example: true.
- `description_html` (`string`, optional): Event description (HTML). Example: Meet at the park entrance.
.
- `end_date` (`string`, optional): End date (YYYY-MM-DD). Example: 2027-03-20.
- `end_time` (`string`, optional): End time, 24-hour HH:MM. Example: 16:00.
- `job_id` (`string`, optional): ULID of the job the event belongs to. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `name` (`string`, optional): Event name. Example: Engagement session.
- `start_date` (`string`, optional): Start date (YYYY-MM-DD). Example: 2027-03-20.
- `start_time` (`string`, optional): Start time, 24-hour HH:MM. Example: 14:00.
- `timezone_name` (`string`, optional): Timezone name, for example America/Chicago. Example: America/Chicago.
- `type_id` (`string`, optional): ULID of the event type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `virtual_url` (`string`, optional): Meeting link for a virtual event. Example: https://meet.example.com/abc.

Example input: `{}`

### `tave_event_type_create`

Create Event Type · Write

Create an event type for the calendar, with its kind, color, default duration and default attendees.
Returns the new event type with its id.
Use tave_event_type_create to add a new kind of session or meeting. Use tave_event_type_update to change an existing type.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Event type name, 1 to 24 characters. Example: Engagement Session.
- `token_prefix` (`string`, required): Unique placeholder prefix for this event type in templates: lowercase letters, digits and underscores, up to 32 characters. Reserved prefixes such as job, event, order, brand and client are not allowed. Example: engagement.
- `color` (`string`, optional): Calendar color as a lowercase 6-digit hex value without #. Example: 2e86c1.
- `default_attendees` (`array`, optional): Token prefixes of the job roles invited by default. Example: ["bride", "groom"].
- `default_duration` (`integer`, optional): Default event length in minutes, 5 to 86400 (default 60). Example: 90.
- `default_location_id` (`string`, optional): ULID of the default location (an address book entry of kind location, from tave_contacts_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `kind` (`string`, optional): Event kind: call, meeting (default), other or session. Example: session. One of: `call`, `meeting`, `other`, `session`.
- `sort_position` (`integer`, optional): Position in sorted lists, 0 to 65535 (default 100). Example: 100.

Example input: `{"name":"<name>","token_prefix":"<token_prefix>"}`

### `tave_event_type_update`

Update Event Type · Write

Update an event type (PUT replaces the type: read it with tave_event_type_get first and resend fields you want to keep; name and token_prefix are always required).
Returns the updated event type.
Use tave_event_type_update to rename a type or change its defaults. Use tave_event_type_create for a new type.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the event type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, required): Event type name, 1 to 24 characters. Example: Engagement Session.
- `token_prefix` (`string`, required): Unique placeholder prefix for this event type in templates: lowercase letters, digits and underscores, up to 32 characters. Reserved prefixes such as job, event, order, brand and client are not allowed. Example: engagement.
- `color` (`string`, optional): Calendar color as a lowercase 6-digit hex value without #. Example: 2e86c1.
- `default_attendees` (`array`, optional): Token prefixes of the job roles invited by default. Example: ["bride", "groom"].
- `default_duration` (`integer`, optional): Default event length in minutes, 5 to 86400 (default 60). Example: 90.
- `default_location_id` (`string`, optional): ULID of the default location (an address book entry of kind location, from tave_contacts_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `kind` (`string`, optional): Event kind: call, meeting (default), other or session. Example: session. One of: `call`, `meeting`, `other`, `session`.
- `sort_position` (`integer`, optional): Position in sorted lists, 0 to 65535 (default 100). Example: 100.

Example input: `{"id":"<id>","name":"<name>","token_prefix":"<token_prefix>"}`

### `tave_event_update`

Update Event · Write

Update an event (PUT replaces the event: read it with tave_event_get first and resend fields you want to keep).
Returns the updated event.
Use tave_event_update to reschedule.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the event. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `all_day` (`boolean`, optional): true for an all-day event. Example: false.
- `channel` (`string`, optional): How the event happens. Example: InPerson. One of: `InPerson`, `Phone`, `Virtual`.
- `confirmed` (`boolean`, optional): true if the event is confirmed. Example: true.
- `description_html` (`string`, optional): Event description (HTML). Example: Meet at the park entrance.
.
- `end_date` (`string`, optional): End date (YYYY-MM-DD). Example: 2027-03-20.
- `end_time` (`string`, optional): End time, 24-hour HH:MM. Example: 16:00.
- `job_id` (`string`, optional): ULID of the job the event belongs to. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `name` (`string`, optional): Event name. Example: Engagement session.
- `start_date` (`string`, optional): Start date (YYYY-MM-DD). Example: 2027-03-20.
- `start_time` (`string`, optional): Start time, 24-hour HH:MM. Example: 14:00.
- `timezone_name` (`string`, optional): Timezone name, for example America/Chicago. Example: America/Chicago.
- `type_id` (`string`, optional): ULID of the event type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `virtual_url` (`string`, optional): Meeting link for a virtual event. Example: https://meet.example.com/abc.

Example input: `{"id":"<id>"}`

### `tave_file_create`

Create File · Write

Upload a file from base64 content or a public URL and optionally attach it to a job, contact or other record.
Returns the new file with its id and download URL.
Use tave_file_create to add a file. Use tave_file_update to rename or re-attach an existing file and tave_gallery_create to link a client gallery.
Provide binary_data or remote_url; pick a type_id from tave_file_types_list if needed.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `filename` (`string`, required): File name including its extension. Example: contract-signed.pdf.
- `attached_to` (`array`, optional): Records the file is attached to. Each item has an entity (brand, contact, event, gallery, invoice, invoice-item, job, payment, product or product-option) and the record's ULID as id. Example: [{"entity": "job", "id": "01j8z3k4m5n6p7q8r9s0t1v2w3"}].
- `binary_data` (`string`, optional): Base64-encoded file content (max about 20 MB encoded). Provide either binary_data or remote_url so the file has content; one of the two is needed. Example: JVBERi0xLjQKJcfsj6IK.
- `created_by_contact_id` (`string`, optional): ULID of the address book contact who provided the file, if a client uploaded it. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `description` (`string`, optional): Description of the file. Example: Countersigned wedding contract.
- `mime_type` (`string`, optional): MIME type of the file. Example: application/pdf.
- `name` (`string`, optional): Display name of the file. Example: Signed contract.
- `remote_url` (`string`, optional): Public URL VSCO Workspace downloads the file from, instead of sending binary_data. Provide either remote_url or binary_data. Example: https://example.com/files/contract-signed.pdf.
- `type_id` (`string`, optional): ULID of the file type (from tave_file_types_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"filename":"<filename>"}`

### `tave_file_update`

Update File · Write

Update a file's name, description, type, attachments or content (PUT replaces the file: read it with tave_file_get first and resend fields you want to keep).
Returns the updated file.
Use tave_file_update to change an existing file. Use tave_file_create to upload a new one and tave_file_delete to remove one.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `filename` (`string`, required): File name including its extension. Example: contract-signed.pdf.
- `id` (`string`, required): ULID of the file. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `attached_to` (`array`, optional): Records the file is attached to. Each item has an entity (brand, contact, event, gallery, invoice, invoice-item, job, payment, product or product-option) and the record's ULID as id. Example: [{"entity": "job", "id": "01j8z3k4m5n6p7q8r9s0t1v2w3"}].
- `binary_data` (`string`, optional): Base64-encoded file content (max about 20 MB encoded). Provide either binary_data or remote_url so the file has content; leave both empty to keep the current content. Example: JVBERi0xLjQKJcfsj6IK.
- `created_by_contact_id` (`string`, optional): ULID of the address book contact who provided the file, if a client uploaded it. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `description` (`string`, optional): Description of the file. Example: Countersigned wedding contract.
- `mime_type` (`string`, optional): MIME type of the file. Example: application/pdf.
- `name` (`string`, optional): Display name of the file. Example: Signed contract.
- `remote_url` (`string`, optional): Public URL VSCO Workspace downloads the file from, instead of sending binary_data. Leave empty to keep the current content. Example: https://example.com/files/contract-signed.pdf.
- `type_id` (`string`, optional): ULID of the file type (from tave_file_types_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"filename":"<filename>","id":"<id>"}`

### `tave_gallery_create`

Create Gallery · Write

Link a client photo gallery hosted in a gallery service to the studio, optionally on a job or event.
Returns the new gallery with its id.
Use tave_gallery_create to record a new gallery. Use tave_gallery_update to change one and tave_galleries_list to find existing galleries.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `admin_url` (`string`, required): URL of the gallery's admin page in the gallery service, for studio staff. Example: https://admin.galleries.example.com/g/1234.
- `client_url` (`string`, required): Gallery URL for clients, used in emails and the client portal. Example: https://galleries.example.com/rivera-wedding.
- `name` (`string`, required): Name of the gallery. Example: Rivera Wedding Gallery.
- `category` (`string`, optional): Category text used to group galleries. Example: Weddings.
- `cover_photo_focal_point_x` (`number`, optional): Horizontal focal point of the cover photo, from 0 (left) to 1 (right). Used only with cover_photo_url. Example: 0.5.
- `cover_photo_focal_point_y` (`number`, optional): Vertical focal point of the cover photo, from 0 (top) to 1 (bottom). Used only with cover_photo_url. Example: 0.4.
- `cover_photo_url` (`string`, optional): Public URL of a cover photo to import (VSCO Workspace downsizes it below 2,000 pixels; avoid originals). Example: https://example.com/photos/cover.jpg.
- `event_date` (`string`, optional): Date of the event the gallery covers (YYYY-MM-DD). Example: 2027-06-12.
- `event_id` (`string`, optional): ULID of the event the gallery belongs to. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `expiration_date` (`string`, optional): Date the gallery stops being accessible (YYYY-MM-DD). Example: 2028-07-01.
- `headline` (`string`, optional): Headline shown instead of the name when present. Example: Jamie & Alex - June 12, 2027.
- `job_id` (`string`, optional): ULID of the job the gallery belongs to. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `order_count` (`integer`, optional): Number of orders placed from the gallery. Example: 3.
- `order_due_date` (`string`, optional): Date orders for the gallery are due (YYYY-MM-DD). Example: 2027-08-01.
- `password` (`string`, optional): Reusable plain-text passcode that unlocks the gallery. Example: rivera2027.
- `photo_count` (`integer`, optional): Number of photos in the gallery. Example: 450.
- `public` (`boolean`, optional): true if the gallery is publicly accessible. Example: false.
- `release_date` (`string`, optional): Date the gallery is released (YYYY-MM-DD). Example: 2027-07-01.
- `remote_created` (`string`, optional): When the gallery was created in the gallery service (ISO 8601 date-time, UTC). Example: 2027-06-20T18:00:00+00:00.
- `remote_id` (`string`, optional): ID of the gallery in the gallery service; must be unique for the studio. Example: gal_1234.
- `requires_password` (`boolean`, optional): true if a passcode is needed to open the gallery (default true). Example: true.
- `slug` (`string`, optional): URL slug: letters, numbers, dashes and underscores; converted to lowercase. Example: rivera-wedding.
- `status` (`string`, optional): Gallery status (default active). Example: active. One of: `pre-release`, `active`, `inactive`, `archived`.
- `visitor_count` (`integer`, optional): Number of visitors to the gallery. Example: 57.

Example input: `{"admin_url":"<admin_url>","client_url":"<client_url>","name":"<name>"}`

### `tave_gallery_update`

Update Gallery · Write

Update a client gallery (PUT replaces the gallery: read it with tave_gallery_get first and resend fields you want to keep).
Returns the updated gallery.
Use tave_gallery_update to change status, dates, URLs or counts. Use tave_gallery_create for a new gallery and tave_gallery_delete to remove one.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `admin_url` (`string`, required): URL of the gallery's admin page in the gallery service, for studio staff. Example: https://admin.galleries.example.com/g/1234.
- `client_url` (`string`, required): Gallery URL for clients, used in emails and the client portal. Example: https://galleries.example.com/rivera-wedding.
- `id` (`string`, required): ULID of the gallery. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, required): Name of the gallery. Example: Rivera Wedding Gallery.
- `category` (`string`, optional): Category text used to group galleries. Example: Weddings.
- `cover_photo_focal_point_x` (`number`, optional): Horizontal focal point of the cover photo, from 0 (left) to 1 (right). Used only with cover_photo_url. Example: 0.5.
- `cover_photo_focal_point_y` (`number`, optional): Vertical focal point of the cover photo, from 0 (top) to 1 (bottom). Used only with cover_photo_url. Example: 0.4.
- `cover_photo_url` (`string`, optional): Public URL of a cover photo to import (VSCO Workspace downsizes it below 2,000 pixels; avoid originals). Example: https://example.com/photos/cover.jpg.
- `event_date` (`string`, optional): Date of the event the gallery covers (YYYY-MM-DD). Example: 2027-06-12.
- `event_id` (`string`, optional): ULID of the event the gallery belongs to. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `expiration_date` (`string`, optional): Date the gallery stops being accessible (YYYY-MM-DD). Example: 2028-07-01.
- `headline` (`string`, optional): Headline shown instead of the name when present. Example: Jamie & Alex - June 12, 2027.
- `job_id` (`string`, optional): ULID of the job the gallery belongs to. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `order_count` (`integer`, optional): Number of orders placed from the gallery. Example: 3.
- `order_due_date` (`string`, optional): Date orders for the gallery are due (YYYY-MM-DD). Example: 2027-08-01.
- `password` (`string`, optional): Reusable plain-text passcode that unlocks the gallery. Example: rivera2027.
- `photo_count` (`integer`, optional): Number of photos in the gallery. Example: 450.
- `public` (`boolean`, optional): true if the gallery is publicly accessible. Example: false.
- `release_date` (`string`, optional): Date the gallery is released (YYYY-MM-DD). Example: 2027-07-01.
- `remote_created` (`string`, optional): When the gallery was created in the gallery service (ISO 8601 date-time, UTC). Example: 2027-06-20T18:00:00+00:00.
- `remote_id` (`string`, optional): ID of the gallery in the gallery service; must be unique for the studio. Example: gal_1234.
- `requires_password` (`boolean`, optional): true if a passcode is needed to open the gallery (default true). Example: true.
- `slug` (`string`, optional): URL slug: letters, numbers, dashes and underscores; converted to lowercase. Example: rivera-wedding.
- `status` (`string`, optional): Gallery status (default active). Example: active. One of: `pre-release`, `active`, `inactive`, `archived`.
- `visitor_count` (`integer`, optional): Number of visitors to the gallery. Example: 57.

Example input: `{"admin_url":"<admin_url>","client_url":"<client_url>","id":"<id>","name":"<name>"}`

### `tave_job_closed_reason_create`

Create Job Closed Reason · Write

Create a job closed reason.
Returns the new closed reason with its id.
Use tave_job_closed_reason_create to add a reason. Use tave_job_closed_reason_update or tave_job_closed_reason_partial_update to change one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Name of the closed reason (1 to 32 characters). Example: Went with another studio.
- `description` (`string`, optional): Longer description (up to 64 characters). Example: Client booked a different photographer.
- `included_in_reporting` (`boolean`, optional): true to count jobs closed with this reason in reports. Example: true.

Example input: `{"name":"<name>"}`

### `tave_job_closed_reason_partial_update`

Partially Update Job Closed Reason · Write

Change only the given fields of a job closed reason (PATCH: fields you leave out keep their values; send at least one).
Returns the updated closed reason.
Use tave_job_closed_reason_partial_update for small edits. Use tave_job_closed_reason_update to replace the whole reason.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job closed reason. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `description` (`string`, optional): Longer description (up to 64 characters). Example: Client booked a different photographer.
- `included_in_reporting` (`boolean`, optional): true to count jobs closed with this reason in reports. Example: true.
- `name` (`string`, optional): Name of the closed reason (1 to 32 characters). Example: Went with another studio.

Example input: `{"id":"<id>"}`

### `tave_job_closed_reason_update`

Update Job Closed Reason · Write

Replace a job closed reason (PUT: name is required and fields you leave out are cleared; read it with tave_job_closed_reason_get first).
Returns the updated closed reason.
Use tave_job_closed_reason_update to rewrite the whole reason. Use tave_job_closed_reason_partial_update to change only some fields.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job closed reason. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, required): Name of the closed reason (1 to 32 characters). Example: Went with another studio.
- `description` (`string`, optional): Longer description (up to 64 characters). Example: Client booked a different photographer.
- `included_in_reporting` (`boolean`, optional): true to count jobs closed with this reason in reports. Example: true.

Example input: `{"id":"<id>","name":"<name>"}`

### `tave_job_contact_create`

Add Contact to Job · Write

Link an address book contact to a job, optionally as a client and with roles.
Returns the job contact.
Use tave_job_contact_create after tave_contact_create and tave_job_create.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `contact_id` (`string`, required): ULID of the address book contact. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `job_id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `client` (`boolean`, optional): true if the contact is a client on the job. Example: true.
- `job_roles` (`array`, optional): ULIDs of job roles (from the studio's job roles). Example: ["01j8z3k4m5n6p7q8r9s0t1v2y5"].

Example input: `{"contact_id":"<contact_id>","job_id":"<job_id>"}`

### `tave_job_contact_update`

Update Job Contact · Write

Update how a contact is linked to a job: client flag and job roles (PUT replaces the job contact: read it with tave_job_contact_get first and resend fields you want to keep).
Returns the updated job contact.
Use tave_job_contact_update to change roles or client status. Use tave_job_contact_create to add a contact to a job and tave_job_contact_delete to remove one.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `contact_id` (`string`, required): ULID of the address book contact. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `id` (`string`, required): ULID of the job contact. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `job_id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `client` (`boolean`, optional): true if the contact is a client on the job. Example: true.
- `job_roles` (`array`, optional): ULIDs of job roles (from tave_job_roles_list). Example: ["01j8z3k4m5n6p7q8r9s0t1v2y5"].

Example input: `{"contact_id":"<contact_id>","id":"<id>","job_id":"<job_id>"}`

### `tave_job_create`

Create Job · Write

Create a job or lead.
Returns the new job with its id.
Use tave_job_create for a new inquiry, then link the client with tave_job_contact_create.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `booking_date` (`string`, optional): Booking date (YYYY-MM-DD). Example: 2026-12-01.
- `brand_id` (`string`, optional): ULID of the studio brand. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `closed` (`boolean`, optional): true to close the lead or job. Example: false.
- `closed_reason_id` (`string`, optional): ULID of the job closed reason, when closing. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `event_date` (`string`, optional): Main event date (YYYY-MM-DD). Example: 2027-06-12.
- `guest_count` (`integer`, optional): Number of guests. Example: 120.
- `inquiry_date` (`string`, optional): Inquiry date (YYYY-MM-DD). Example: 2026-11-16.
- `job_type_id` (`string`, optional): ULID of the job type (from tave_job_types_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `lead_confidence` (`string`, optional): How likely the lead is to book. Example: high. One of: `low`, `medium`, `high`.
- `lead_max_budget` (`integer`, optional): Lead's maximum budget. Integer amount in the studio's currency, in minor units (for example 15000 for 150.00); compare with an existing record from tave_payments_list if unsure. Example: 500000.
- `lead_notes` (`string`, optional): Notes about the lead. Example: Found us on Instagram.
- `lead_source_id` (`string`, optional): ULID of the lead source (from tave_lead_sources_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `lead_status_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, optional): Job name; overrides the generated title. Example: Rivera Wedding.
- `pinned` (`boolean`, optional): true to pin the job. Example: false.
- `stage` (`string`, optional): Job stage. Example: lead. One of: `lead`, `booked`, `fulfillment`, `completed`.

Example input: `{}`

### `tave_job_order_create`

Create Job Order · Write

Create an order (booked package or invoice of line items) on a job.
Returns the new order with its id, status, line items, taxes, totals and balance.
Use tave_job_order_create to bill a job directly. Use tave_quote_create to offer priced options first, tave_order_update to change an order and tave_job_orders_list to see a job's orders.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `job_id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `due_date` (`string`, optional): Due date (YYYY-MM-DD); when set, a single invoice for the whole order is created with this due date. Example: 2027-01-15.
- `line_items` (`array`, optional): Line items on the order. Each needs a name and can set productId (from tave_products_list), descriptionHtml, units, pricePerUnit and costPerUnit (integer minor units of the studio currency), taxable, and discount with discountKind (amount or percent) for a discount line. Example: [{"productId": "01j8z3k4m5n6p7q8r9s0t1v2y5", "name": "Full day coverage", "units": 1, "pricePerUnit": 350000, "taxable": true}].
- `name` (`string`, optional): Order name; overrides the generated title. Example: Wedding collection.
- `payment_terms_id` (`string`, optional): ULID of the payment terms (payment schedule) to use. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `recipient_id` (`string`, optional): ULID of the address book contact the order is billed to. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `tax_group_id` (`string`, optional): ULID of the tax group to apply (from tave_tax_groups_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"job_id":"<job_id>"}`

### `tave_job_role_create`

Create Job Role · Write

Create a job role that contacts can hold on a job.
Returns the new job role with its id.
Use tave_job_role_create to add a role. Use tave_job_role_update to change one and tave_job_roles_list to check existing roles first.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Name of the job role (1 to 24 characters). Example: Bride.
- `token_prefix` (`string`, required): Prefix for this role's email placeholders: 1 to 32 lowercase letters, digits or underscores, unique across job roles. Reserved: booked_order, brand, clients, contract, custom, customers, event, invoice, item, job, quote, order, payment, payment_schedule, primary_session, recipient, subjects, tave, team, vendors. Example: bride.
- `kind` (`string`, optional): What the role represents: customer, subject (default), team or vendor. Example: subject. One of: `customer`, `subject`, `team`, `vendor`.
- `sort_position` (`integer`, optional): Sort position, 0 to 65535 (default 100). Example: 100.

Example input: `{"name":"<name>","token_prefix":"<token_prefix>"}`

### `tave_job_role_update`

Update Job Role · Write

Update a job role (PUT replaces the job role: read it with tave_job_role_get first and resend fields you want to keep).
Returns the updated job role.
Use tave_job_role_update to rename or reorder a role. Use tave_job_role_create for a new role and tave_job_role_delete to remove one.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job role. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, required): Name of the job role (1 to 24 characters). Example: Bride.
- `token_prefix` (`string`, required): Prefix for this role's email placeholders: 1 to 32 lowercase letters, digits or underscores, unique across job roles. Reserved: booked_order, brand, clients, contract, custom, customers, event, invoice, item, job, quote, order, payment, payment_schedule, primary_session, recipient, subjects, tave, team, vendors. Example: bride.
- `kind` (`string`, optional): What the role represents: customer, subject (default), team or vendor. Example: subject. One of: `customer`, `subject`, `team`, `vendor`.
- `sort_position` (`integer`, optional): Sort position, 0 to 65535 (default 100). Example: 100.

Example input: `{"id":"<id>","name":"<name>","token_prefix":"<token_prefix>"}`

### `tave_job_type_create`

Create Job Type · Write

Create a job type, optionally with the contact roles and events new jobs of that type start with.
Returns the new job type with its id.
Use tave_job_type_create to add a type. Use tave_job_type_update to change one and tave_job_types_list to check existing types first.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Name of the job type (1 to 128 characters). Example: Wedding.
- `default_contacts` (`array`, optional): Contact slots added to new jobs of this type. Each item names a job role (jobRoleId, from tave_job_roles_list) and can set whether it is a client, how many slots (quantity, default 1) and a sort position. Example: [{"jobRoleId": "01j8z3k4m5n6p7q8r9s0t1v2y5", "client": true, "quantity": 2}].
- `default_events` (`array`, optional): Events added to new jobs of this type. Each item names an event type (eventTypeId, from tave_event_types_list) and can set whether it is the primary session, how many (quantity, default 1) and a sort position. Example: [{"eventTypeId": "01j8z3k4m5n6p7q8r9s0t1v2y5", "primarySession": true, "quantity": 1}].
- `initial_lead_status_id` (`string`, optional): ULID of the lead status new leads of this type start in (from tave_lead_statuses_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `primary_session_required` (`boolean`, optional): true if jobs of this type need a primary session (default true). Example: true.
- `profit_center_id` (`string`, optional): ULID of the profit center for this job type (from tave_profit_centers_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `sort_position` (`integer`, optional): Sort position, 0 to 65535 (default 100). Example: 100.
- `workflow_id` (`string`, optional): ULID of the workflow new jobs of this type use. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"name":"<name>"}`

### `tave_job_type_update`

Update Job Type · Write

Update a job type (PUT replaces the job type: read it with tave_job_type_get first and resend fields you want to keep).
Returns the updated job type.
Use tave_job_type_update to rename a type or change its defaults. Use tave_job_type_create for a new type and tave_job_type_delete to remove one.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, required): Name of the job type (1 to 128 characters). Example: Wedding.
- `default_contacts` (`array`, optional): Contact slots added to new jobs of this type. Each item names a job role (jobRoleId, from tave_job_roles_list) and can set whether it is a client, how many slots (quantity, default 1) and a sort position. Example: [{"jobRoleId": "01j8z3k4m5n6p7q8r9s0t1v2y5", "client": true, "quantity": 2}].
- `default_events` (`array`, optional): Events added to new jobs of this type. Each item names an event type (eventTypeId, from tave_event_types_list) and can set whether it is the primary session, how many (quantity, default 1) and a sort position. Example: [{"eventTypeId": "01j8z3k4m5n6p7q8r9s0t1v2y5", "primarySession": true, "quantity": 1}].
- `initial_lead_status_id` (`string`, optional): ULID of the lead status new leads of this type start in (from tave_lead_statuses_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `primary_session_required` (`boolean`, optional): true if jobs of this type need a primary session (default true). Example: true.
- `profit_center_id` (`string`, optional): ULID of the profit center for this job type (from tave_profit_centers_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `sort_position` (`integer`, optional): Sort position, 0 to 65535 (default 100). Example: 100.
- `workflow_id` (`string`, optional): ULID of the workflow new jobs of this type use. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>","name":"<name>"}`

### `tave_job_update`

Update Job · Write

Update a job (PUT replaces the job: read it with tave_job_get first and resend fields you want to keep).
Returns the updated job.
Use tave_job_update to change stage, dates, lead status or close a job.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `booking_date` (`string`, optional): Booking date (YYYY-MM-DD). Example: 2026-12-01.
- `brand_id` (`string`, optional): ULID of the studio brand. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `closed` (`boolean`, optional): true to close the lead or job. Example: false.
- `closed_reason_id` (`string`, optional): ULID of the job closed reason, when closing. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `event_date` (`string`, optional): Main event date (YYYY-MM-DD). Example: 2027-06-12.
- `guest_count` (`integer`, optional): Number of guests. Example: 120.
- `inquiry_date` (`string`, optional): Inquiry date (YYYY-MM-DD). Example: 2026-11-16.
- `job_type_id` (`string`, optional): ULID of the job type (from tave_job_types_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `lead_confidence` (`string`, optional): How likely the lead is to book. Example: high. One of: `low`, `medium`, `high`.
- `lead_max_budget` (`integer`, optional): Lead's maximum budget. Integer amount in the studio's currency, in minor units (for example 15000 for 150.00); compare with an existing record from tave_payments_list if unsure. Example: 500000.
- `lead_notes` (`string`, optional): Notes about the lead. Example: Found us on Instagram.
- `lead_source_id` (`string`, optional): ULID of the lead source (from tave_lead_sources_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `lead_status_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, optional): Job name; overrides the generated title. Example: Rivera Wedding.
- `pinned` (`boolean`, optional): true to pin the job. Example: false.
- `stage` (`string`, optional): Job stage. Example: lead. One of: `lead`, `booked`, `fulfillment`, `completed`.

Example input: `{"id":"<id>"}`

### `tave_job_worksheet_create`

Create Job From Worksheet · Write

Create a job together with its contacts and events in one request; if any part fails, nothing is created.
Returns the new job worksheet: the job with its id plus the created contacts and events.
Use tave_job_worksheet_create to book a new inquiry with its people and dates at once. Use tave_job_create for a bare job, then tave_job_contact_create and tave_event_create to add to it; use tave_job_worksheet_get to read a worksheet.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `booking_date` (`string`, optional): Booking date (YYYY-MM-DD). Example: 2026-12-01.
- `brand_id` (`string`, optional): ULID of the studio brand (from tave_brands_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `contacts` (`array`, optional): Contacts to add to the job. Each item needs a contact object with the address book details to create: kind (person, company or location) plus fields such as firstName, lastName, name and email. It can also set client (true for the paying client), jobRoles (job role ULIDs from tave_job_roles_list), attendingAllEvents and attendingAllSessions. Phone numbers inside contact are objects such as {"formatted": "+15125550101"}. Example: [{"client": true, "jobRoles": ["01j8z3k4m5n6p7q8r9s0t1v2y5"], "contact": {"kind": "person", "firstName": "Jamie", "lastName": "Rivera", "email": "jamie@example.com"}}].
- `custom_fields` (`array`, optional): Custom field values for the job. Each item has the custom field's ULID as fieldId (from tave_custom_fields_list) and a text value. Example: [{"fieldId": "01j8z3k4m5n6p7q8r9s0t1v2y5", "value": "Outdoor ceremony"}].
- `event_date` (`string`, optional): Main event date (YYYY-MM-DD). Example: 2027-06-12.
- `events` (`array`, optional): Events to create on the job. Each item can set name, typeId (from tave_event_types_list), startDate and endDate (YYYY-MM-DD), startTime and endTime (24-hour HH:MM), allDay, timezoneName, channel (InPerson, Phone or Virtual), virtualUrl, confirmed and descriptionHtml. Example: [{"name": "Wedding day", "typeId": "01j8z3k4m5n6p7q8r9s0t1v2y5", "startDate": "2027-06-12", "startTime": "14:00", "endDate": "2027-06-12", "endTime": "22:00"}].
- `guest_count` (`integer`, optional): Number of guests. Example: 120.
- `inquiry_date` (`string`, optional): Inquiry date (YYYY-MM-DD). Example: 2026-11-16.
- `job_type_id` (`string`, optional): ULID of the job type (from tave_job_types_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `lead_confidence` (`string`, optional): How likely the lead is to book. Example: high. One of: `low`, `medium`, `high`.
- `lead_decision_expected_by_date` (`string`, optional): Date the lead expects to decide (YYYY-MM-DD). Example: 2026-12-15.
- `lead_max_budget` (`integer`, optional): Lead's maximum budget. Integer amount in the studio's currency, in minor units (for example 15000 for 150.00); compare with an existing record from tave_payments_list if unsure. Example: 500000.
- `lead_notes` (`string`, optional): Notes about the lead. Example: Found us on Instagram.
- `lead_rating` (`integer`, optional): Lead rating from 1 to 5. Example: 4.
- `lead_source_id` (`string`, optional): ULID of the lead source (from tave_lead_sources_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `lead_status_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, optional): Job name; overrides the generated title. Example: Rivera Wedding.
- `pinned` (`boolean`, optional): true to pin the job. Example: false.
- `stage` (`string`, optional): Job stage. Example: lead. One of: `lead`, `booked`, `fulfillment`, `completed`.
- `web_lead` (`boolean`, optional): true if the lead came from a contact form. Example: false.
- `workflow_id` (`string`, optional): ULID of the workflow to run on the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{}`

### `tave_lead_source_create`

Create Lead Source · Write

Create a lead source, the referral channel a lead came from.
Returns the new lead source with id, name and parent ID.
Use tave_lead_source_create to add a channel. Use tave_lead_sources_list to find an existing one and tave_lead_source_update to rename one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Lead source name, 3 to 128 characters. Example: Instagram.
- `parent_id` (`string`, optional): ULID of the parent lead source, to nest this source under another one (from tave_lead_sources_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"name":"<name>"}`

### `tave_lead_source_update`

Update Lead Source · Write

Update a lead source (PUT replaces the source: read it with tave_lead_source_get first and resend parent_id to keep it).
Returns the updated lead source.
Use tave_lead_source_update to rename or re-nest a source. Use tave_lead_source_create for a new one.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the lead source. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, required): Lead source name, 3 to 128 characters. Example: Instagram.
- `parent_id` (`string`, optional): ULID of the parent lead source, to nest this source under another one (from tave_lead_sources_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>","name":"<name>"}`

### `tave_lead_status_create`

Create Lead Status · Write

Create a lead status, a pipeline stage for leads, with optional automatic transitions.
Returns the new lead status.
Use tave_lead_status_create to add a stage. Use tave_lead_statuses_list to find existing ones and tave_job_update to set a lead's status.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Lead status name, 1 to 64 characters. Example: Consultation booked.
- `after_document_sent_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after a document is sent. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_email_sent_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after an email is sent. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_event_scheduled_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after an event is scheduled. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_form_sent_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after a form is sent. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_quote_sent_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after a quote is sent. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `color` (`string`, optional): Display color as 6 lowercase hex digits, without #. Example: 3b82f6.
- `external_mappings` (`array`, optional): Links from this status to records in an external system; each item has id (1 to 64 characters) and url (12 to 255 characters). Mappings cannot be changed after creation. Example: [{"id": "crm-4821", "url": "https://crm.example.com/statuses/4821"}].
- `kind` (`string`, optional): Status kind: general, new (given to new leads) or stale (given to leads that go quiet). Example: general. One of: `general`, `new`, `stale`.
- `sort_position` (`integer`, optional): Position in the status list, 0 to 65535; lower comes first. Defaults to 100. Example: 100.
- `transition_closed_reason_id` (`string`, optional): ULID of the job closed reason (from tave_job_closed_reasons_list) to close the lead with when the automatic transition runs. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `transition_interval` (`integer`, optional): Number of transition_interval_unit units a lead stays in this status before it moves to transition_to_id. Example: 14.
- `transition_interval_unit` (`string`, optional): Unit of transition_interval: day, week, month or year. Example: day. One of: `day`, `week`, `month`, `year`.
- `transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to automatically after the transition interval. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"name":"<name>"}`

### `tave_lead_status_partial_update`

Partially Update Lead Status · Write

Change some fields of a lead status (PATCH: only the fields you send change; send at least one).
Returns the updated lead status.
Use tave_lead_status_partial_update to rename, recolor or reorder a status. Use tave_lead_status_update to replace the whole status.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the lead status. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_document_sent_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after a document is sent. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_email_sent_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after an email is sent. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_event_scheduled_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after an event is scheduled. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_form_sent_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after a form is sent. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_quote_sent_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after a quote is sent. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `color` (`string`, optional): Display color as 6 lowercase hex digits, without #. Example: 3b82f6.
- `kind` (`string`, optional): Status kind: general, new (given to new leads) or stale (given to leads that go quiet). Example: general. One of: `general`, `new`, `stale`.
- `name` (`string`, optional): Lead status name, 1 to 64 characters. Example: Consultation booked.
- `sort_position` (`integer`, optional): Position in the status list, 0 to 65535; lower comes first. Defaults to 100. Example: 100.
- `transition_closed_reason_id` (`string`, optional): ULID of the job closed reason (from tave_job_closed_reasons_list) to close the lead with when the automatic transition runs. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `transition_interval` (`integer`, optional): Number of transition_interval_unit units a lead stays in this status before it moves to transition_to_id. Example: 14.
- `transition_interval_unit` (`string`, optional): Unit of transition_interval: day, week, month or year. Example: day. One of: `day`, `week`, `month`, `year`.
- `transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to automatically after the transition interval. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_lead_status_update`

Update Lead Status · Write

Update a lead status (PUT replaces the status: read it with tave_lead_status_get first and resend fields you want to keep).
Returns the updated lead status.
Use tave_lead_status_update to rewrite the whole status. Use tave_lead_status_partial_update to change only the fields you send.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the lead status. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, required): Lead status name, 1 to 64 characters. Example: Consultation booked.
- `after_document_sent_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after a document is sent. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_email_sent_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after an email is sent. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_event_scheduled_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after an event is scheduled. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_form_sent_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after a form is sent. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `after_quote_sent_transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to after a quote is sent. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `color` (`string`, optional): Display color as 6 lowercase hex digits, without #. Example: 3b82f6.
- `kind` (`string`, optional): Status kind: general, new (given to new leads) or stale (given to leads that go quiet). Example: general. One of: `general`, `new`, `stale`.
- `sort_position` (`integer`, optional): Position in the status list, 0 to 65535; lower comes first. Defaults to 100. Example: 100.
- `transition_closed_reason_id` (`string`, optional): ULID of the job closed reason (from tave_job_closed_reasons_list) to close the lead with when the automatic transition runs. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `transition_interval` (`integer`, optional): Number of transition_interval_unit units a lead stays in this status before it moves to transition_to_id. Example: 14.
- `transition_interval_unit` (`string`, optional): Unit of transition_interval: day, week, month or year. Example: day. One of: `day`, `week`, `month`, `year`.
- `transition_to_id` (`string`, optional): ULID of the lead status (from tave_lead_statuses_list) to move the lead to automatically after the transition interval. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>","name":"<name>"}`

### `tave_note_create`

Create Note · Write

Add a note to a job or contact.
Returns the new note.
Use tave_note_create to log a call or decision.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `content_html` (`string`, required): Note text (HTML). Example: Called the client; they want a second shooter.
.
- `contact_id` (`string`, optional): ULID of the contact. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `date` (`string`, optional): Note date (YYYY-MM-DD). Defaults to today. Example: 2026-11-16.
- `job_id` (`string`, optional): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.

Example input: `{"content_html":"<content_html>"}`

### `tave_note_update`

Update Note · Write

Update a note's text or date.
Returns the updated note.
Use tave_note_update to correct a note.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `content_html` (`string`, required): Note text (HTML); replaces the existing text. Example: Updated: two shooters confirmed.
.
- `id` (`string`, required): ULID of the note. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `date` (`string`, optional): Note date (YYYY-MM-DD). Example: 2026-11-16.

Example input: `{"content_html":"<content_html>","id":"<id>"}`

### `tave_order_update`

Update Order · Write

Update an order's line items, recipient, tax group, payment terms or name (PUT replaces the order: read it with tave_order_get first and resend fields you want to keep).
Returns the updated order with recomputed totals, taxes and balance.
Use tave_order_update to change what a client is buying. Use tave_order_void to cancel an order and tave_job_order_create for a new one.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the order. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `due_date` (`string`, optional): Due date (YYYY-MM-DD); creates a single invoice for the order with this due date. Example: 2027-01-15.
- `line_items` (`array`, optional): The complete set of line items; it replaces the order's existing items, so resend every item you want to keep (read them with tave_order_get). Each item needs name and can have productId, descriptionHtml, units, pricePerUnit, costPerUnit, taxable, discount, discountKind, selectability and selected. pricePerUnit and costPerUnit: Integer amount in the studio's currency, in minor units (for example 15000 for 150.00); compare with an existing record from tave_payments_list if unsure. Example: [{"productId": "01j8z3k4m5n6p7q8r9s0t1v2y5", "name": "Full day coverage", "units": 1, "pricePerUnit": 350000, "taxable": true}].
- `name` (`string`, optional): Order name; overrides the generated title. Example: Wedding collection.
- `payment_terms_id` (`string`, optional): ULID of the payment terms. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `recipient_id` (`string`, optional): ULID of the bill-to contact. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `tax_group_id` (`string`, optional): ULID of the tax group (from tave_tax_groups_list); taxes are recomputed from it. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_payment_apply`

Apply Payment to Order · Write

Allocate part or all of a payment to an order.
Returns the payment with its allocations.
Use tave_payment_apply after tave_payment_create.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`integer`, required): Amount to apply. Integer amount in the studio's currency, in minor units (for example 15000 for 150.00); compare with an existing record from tave_payments_list if unsure. Example: 15000.
- `id` (`string`, required): ULID of the payment. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `order_id` (`string`, required): ULID of the order to apply the payment to. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"amount":15000,"id":"<id>","order_id":"<order_id>"}`

### `tave_payment_create`

Record Payment · Write

Record a payment received (or scheduled) on a job.
Returns the new payment.
Use tave_payment_create for checks, cash or transfers received outside VSCO Workspace, then tave_payment_apply to allocate it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`integer`, required): Payment amount. Integer amount in the studio's currency, in minor units (for example 15000 for 150.00); compare with an existing record from tave_payments_list if unsure. Example: 15000.
- `job_id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `check_number` (`string`, optional): Check number. Example: 1042.
- `memo` (`string`, optional): Memo. Example: Deposit.
- `payer_id` (`string`, optional): ULID of the contact who paid. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `payment_method_id` (`string`, optional): ULID of the payment method (from tave_payment_methods_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `received` (`string`, optional): Date received (YYYY-MM-DD). Example: 2026-11-16.
- `status` (`string`, optional): Payment status. Defaults to posted. Example: posted. One of: `future`, `confirmed-future`, `posted`, `failed`, `pending`.

Example input: `{"amount":15000,"job_id":"<job_id>"}`

### `tave_payment_update`

Update Payment · Write

Update a payment's status, date, payer, method, memo or check number; the amount cannot be changed (PUT replaces the payment: read it with tave_payment_get first and resend fields you want to keep).
Returns the updated payment.
Use tave_payment_update to correct payment details. To change the amount, delete it with tave_payment_delete and record it again with tave_payment_create; use tave_payment_apply to allocate it to an order.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the payment. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `job_id` (`string`, required): ULID of the job the payment belongs to; resend the current value from tave_payment_get to keep it. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `auth_code` (`string`, optional): Processor authorization code, up to 100 characters; resend it to keep it. Example: A1B2C3.
- `check_number` (`string`, optional): Check number, up to 18 characters. Example: 1042.
- `invoice_item_id` (`string`, optional): ULID of the invoice installment this payment is for. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `memo` (`string`, optional): Memo, up to 128 characters. Example: Deposit.
- `payer_id` (`string`, optional): ULID of the contact who paid. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `payment_method_id` (`string`, optional): ULID of the payment method (from tave_payment_methods_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `received` (`string`, optional): Date received (YYYY-MM-DD). Example: 2026-11-16.
- `status` (`string`, optional): Payment status. Example: posted. One of: `future`, `confirmed-future`, `posted`, `failed`, `pending`.
- `transaction_id` (`string`, optional): Processor transaction ID, up to 255 characters; resend it to keep it. Example: ch_3Q1x2y3z4a5b6c7d.

Example input: `{"id":"<id>","job_id":"<job_id>"}`

### `tave_product_create`

Create Product · Write

Create a product or service.
Returns the new product.
Use tave_product_create to add something you sell.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Product name. Example: Second shooter (per hour)
- `deliverable` (`boolean`, optional): true if the product is a deliverable. Example: false.
- `description_html` (`string`, optional): Description (HTML). Example: Additional photographer.
.
- `price` (`integer`, optional): Price. Integer amount in the studio's currency, in minor units (for example 15000 for 150.00); compare with an existing record from tave_payments_list if unsure. Example: 15000.
- `sku` (`string`, optional): Stock keeping unit. Example: SS-HR.
- `taxable` (`boolean`, optional): true if tax applies. Example: true.
- `type` (`string`, optional): ULID of the product type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"name":"<name>"}`

### `tave_product_partial_update`

Partially Update Product · Write

Change some fields of a product, such as its price or name (PATCH: only the fields you send change; send at least one).
Returns the updated product.
Use tave_product_partial_update for a quick change like a new price. Use tave_product_update to replace the whole product (PUT) and tave_product_get to read it first.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the product. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `deliverable` (`boolean`, optional): true if the product is a deliverable. Example: false.
- `description_html` (`string`, optional): Description (HTML). Example: Additional photographer.
.
- `expense_category_id` (`string`, optional): ULID of the expense category for the product's costs. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `expense_due_from` (`string`, optional): When the product's expenses fall due from: JobDate, Booking or Never. Example: Booking. One of: `JobDate`, `Booking`, `Never`.
- `expense_due_period` (`number`, optional): Number of expense_due_period_type units after expense_due_from that expenses fall due. Example: 30.
- `expense_due_period_type` (`string`, optional): Unit of expense_due_period: Days, Weeks or Months. Example: Days. One of: `Days`, `Weeks`, `Months`.
- `expenses` (`array`, optional): Product expenses (costs), each with memo and amount. amount: Integer amount in the studio's currency, in minor units (for example 15000 for 150.00); compare with an existing record from tave_payments_list if unsure. Example: [{"memo": "Album printing", "amount": 12000}].
- `manual_entry` (`boolean`, optional): true if the product is entered manually rather than from the catalog. Example: false.
- `name` (`string`, optional): Product name, up to 128 characters. Example: Second shooter (per hour).
- `price` (`integer`, optional): Price. Integer amount in the studio's currency, in minor units (for example 15000 for 150.00); compare with an existing record from tave_payments_list if unsure. Example: 15000.
- `sku` (`string`, optional): Stock keeping unit, up to 48 characters. Example: SS-HR.
- `taxable` (`boolean`, optional): true if tax applies. Example: true.
- `type` (`string`, optional): ULID of the product type (from tave_product_types_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `vendor_id` (`string`, optional): ULID of the vendor contact who supplies the product. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.

Example input: `{"id":"<id>"}`

### `tave_product_type_create`

Create Product Type · Write

Create a product type, a category for products.
Returns the new product type.
Use tave_product_type_create to add a category. Use tave_product_types_list to find an existing one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Product type name, up to 255 characters. Example: Fine art prints.
- `kind` (`string`, optional): Product type kind. Defaults to Other. Example: Print. One of: `Session`, `Album`, `Print`, `Other`, `Service`.
- `parent_id` (`string`, optional): ULID of the parent product type, to nest this type under another one. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"name":"<name>"}`

### `tave_product_update`

Update Product · Write

Update a product (PUT replaces the product: read it with tave_product_get first and resend fields you want to keep).
Returns the updated product.
Use tave_product_update to rewrite a product. Use tave_product_partial_update to change only some fields, such as a price.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the product. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `deliverable` (`boolean`, optional): true if the product is a deliverable. Example: false.
- `description_html` (`string`, optional): Description (HTML). Example: Additional photographer.
.
- `name` (`string`, optional): Product name. Example: Second shooter (per hour)
- `price` (`integer`, optional): Price. Integer amount in the studio's currency, in minor units (for example 15000 for 150.00); compare with an existing record from tave_payments_list if unsure. Example: 15000.
- `sku` (`string`, optional): Stock keeping unit. Example: SS-HR.
- `taxable` (`boolean`, optional): true if tax applies. Example: true.
- `type` (`string`, optional): ULID of the product type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_profit_center_create`

Create Profit Center · Write

Create a profit center, a revenue category for reporting product sales.
Returns the new profit center with its id.
Use tave_profit_center_create to add a category. Use tave_profit_centers_list first to avoid duplicates.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Profit center name, up to 24 characters. Example: Prints.

Example input: `{"name":"<name>"}`

### `tave_profit_center_partial_update`

Partially Update Profit Center · Write

Change only the fields you send on a profit center (PATCH); omitted fields keep their values.
Returns the updated profit center.
Use tave_profit_center_partial_update for a targeted change. Use tave_profit_center_update (PUT) to replace the whole record.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the profit center. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, optional): Profit center name, up to 24 characters. Example: Prints.

Example input: `{"id":"<id>"}`

### `tave_profit_center_update`

Update Profit Center · Write

Replace a profit center (PUT: name is required and the whole record is resent).
Returns the updated profit center.
Use tave_profit_center_update to rename a profit center. Use tave_profit_center_partial_update (PATCH) to send only changed fields.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the profit center. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, required): Profit center name, up to 24 characters. Example: Prints.

Example input: `{"id":"<id>","name":"<name>"}`

### `tave_quote_book`

Book Quote · Write

Book a quote, turning the chosen option into an order.
Returns the new order.
Use tave_quote_book when the client accepts.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): ULID of the quote. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `due_date` (`string`, optional): First payment due date (YYYY-MM-DD). Example: 2026-12-01.
- `option_id` (`string`, optional): ULID of the chosen option (required for advanced quotes). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `recipient_id` (`string`, optional): ULID of the contact who booked. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.
- `sold_at` (`string`, optional): Booking date (YYYY-MM-DD). Defaults to today. Example: 2026-11-16.

Example input: `{"id":"<id>"}`

### `tave_quote_create`

Create Quote · Write

Create a quote on a job with one or more priced options.
Returns the new quote.
Use tave_quote_create to price a lead; send it with tave_quote_send.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `job_id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `name` (`string`, required): Quote name. Example: Wedding collections.
- `introduction` (`string`, optional): Introduction text shown to the client. Example: Thank you for considering us!.
- `kind` (`string`, optional): simple (exactly one option) or advanced (several options to choose from). Example: simple. One of: `simple`, `advanced`.
- `options` (`array`, optional): Priced options; a simple quote has exactly one. Each option has lineItems, each with a name and optionally productId, units and pricePerUnit (minor units). Example: [{"lineItems": [{"productId": "01j8z3k4m5n6p7q8r9s0t1v2y5", "name": "Full day coverage", "units": 1, "pricePerUnit": 350000}]}].
- `recipients` (`array`, optional): Recipients, required when the job has no client contacts. Example: [{"contactId": "01j8z3k4m5n6p7q8r9s0t1v2x4"}].

Example input: `{"job_id":"<job_id>","name":"<name>"}`

### `tave_quote_send`

Send Quote · Write

Email a quote invitation to its recipients, or create the email as a draft.
Returns the queued mail message.
Use tave_quote_send after tave_quote_create. Set resend true to send again.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): ULID of the quote. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `resend` (`boolean`, required): Must be true to send again to recipients already emailed; false for a first send. Example: false.
- `draft` (`boolean`, optional): true to create a draft email without sending. Example: false.
- `mail_message_template_id` (`string`, optional): ULID of a mail template to use. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `recipient_contact_ids` (`array`, optional): Subset of quote recipient contact IDs to email; all recipients when empty. Example: ["01j8z3k4m5n6p7q8r9s0t1v2x4"].

Example input: `{"id":"<id>","resend":true}`

### `tave_rest_hook_create`

Create REST Hook · Write

Subscribe a target URL to a VSCO Workspace event (REST Hooks webhook): contact.created, job.created, order.booked or payment.created.
Returns the new subscription with its id. Each postback to the URL contains only the targetId of the new entity.
Use tave_rest_hook_create to get notified of new records; fetch the record with tave_contact_get, tave_job_get, tave_order_get or tave_payment_get. Use tave_rest_hooks_list to check for an existing subscription first.
Optional filters narrow the subscription by contact kind, job type (tave_job_types_list), brand (tave_brands_list) or web lead.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `event` (`string`, required): Event that triggers the webhook: contact.created, job.created, order.booked or payment.created. Example: job.created. One of: `contact.created`, `job.created`, `order.booked`, `payment.created`.
- `url` (`string`, required): Target URL that VSCO Workspace POSTs to when the event happens. The postback carries only the targetId of the new entity; fetch the entity with the matching get tool. Example: https://hooks.example.com/tave/job-created.
- `brand_ids` (`array`, optional): Only fire for records in these brand ULIDs (from tave_brands_list). Example: ["01j8z3k4m5n6p7q8r9s0t1v2y5"].
- `contact_kinds` (`array`, optional): Only fire for these address book kinds (person, company, location). Valid only for contact.created. Example: ["person"].
- `job_type_ids` (`array`, optional): Only fire for jobs of these job type ULIDs (from tave_job_types_list). Not valid for contact.created. Example: ["01j8z3k4m5n6p7q8r9s0t1v2y5"].
- `web_lead` (`boolean`, optional): true to fire only for jobs created from a web lead (contact form). Valid only for job.created. Example: true.

Example input: `{"event":"contact.created","url":"<url>"}`

### `tave_rest_hook_partial_update`

Partially Update REST Hook · Write

Change only the fields you send on a REST Hook webhook subscription (PATCH); omitted fields keep their values.
Returns the updated subscription.
Use tave_rest_hook_partial_update to change the target URL, event or one filter. Use tave_rest_hook_update (PUT) to replace the whole subscription.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the REST Hook subscription. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `brand_ids` (`array`, optional): Only fire for records in these brand ULIDs (from tave_brands_list). Example: ["01j8z3k4m5n6p7q8r9s0t1v2y5"].
- `contact_kinds` (`array`, optional): Only fire for these address book kinds (person, company, location). Valid only for contact.created. Example: ["person"].
- `event` (`string`, optional): Event that triggers the webhook: contact.created, job.created, order.booked or payment.created. Example: job.created. One of: `contact.created`, `job.created`, `order.booked`, `payment.created`.
- `job_type_ids` (`array`, optional): Only fire for jobs of these job type ULIDs (from tave_job_types_list). Not valid for contact.created. Example: ["01j8z3k4m5n6p7q8r9s0t1v2y5"].
- `url` (`string`, optional): Target URL that VSCO Workspace POSTs to when the event happens. The postback carries only the targetId of the new entity; fetch the entity with the matching get tool. Example: https://hooks.example.com/tave/job-created.
- `web_lead` (`boolean`, optional): true to fire only for jobs created from a web lead (contact form). Valid only for job.created. Example: true.

Example input: `{"id":"<id>"}`

### `tave_rest_hook_update`

Update REST Hook · Write

Replace a REST Hook webhook subscription (PUT: event and url are required, and filters you omit are cleared).
Returns the updated subscription.
Use tave_rest_hook_update to rewrite a subscription; read it with tave_rest_hook_get first. Use tave_rest_hook_partial_update (PATCH) to change only some fields.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `event` (`string`, required): Event that triggers the webhook: contact.created, job.created, order.booked or payment.created. Example: job.created. One of: `contact.created`, `job.created`, `order.booked`, `payment.created`.
- `id` (`string`, required): ULID of the REST Hook subscription. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `url` (`string`, required): Target URL that VSCO Workspace POSTs to when the event happens. The postback carries only the targetId of the new entity; fetch the entity with the matching get tool. Example: https://hooks.example.com/tave/job-created.
- `brand_ids` (`array`, optional): Only fire for records in these brand ULIDs (from tave_brands_list). Example: ["01j8z3k4m5n6p7q8r9s0t1v2y5"].
- `contact_kinds` (`array`, optional): Only fire for these address book kinds (person, company, location). Valid only for contact.created. Example: ["person"].
- `job_type_ids` (`array`, optional): Only fire for jobs of these job type ULIDs (from tave_job_types_list). Not valid for contact.created. Example: ["01j8z3k4m5n6p7q8r9s0t1v2y5"].
- `web_lead` (`boolean`, optional): true to fire only for jobs created from a web lead (contact form). Valid only for job.created. Example: true.

Example input: `{"event":"contact.created","id":"<id>","url":"<url>"}`

### `tave_studio_update`

Update My Studio · Write

Update the settings of the studio the API key belongs to: name, contact email, owner name, currency, timezone, default brand and display formats (PUT: name is required).
Returns the updated studio.
Use tave_studio_update to change studio settings; read current values with tave_studio_get first and resend the name. Use tave_studio_readonly_mode_set to lock or unlock the studio.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `name` (`string`, required): Studio name, up to 255 characters. Required by PUT. Example: Rivera Photography.
- `currency_code` (`string`, optional): Three-letter ISO 4217 currency code for the studio. Example: USD.
- `date_format` (`string`, optional): Date display format: n/j/Y (US), j/n/Y (day first) or Y-m-d (ISO). Example: n/j/Y. One of: `n/j/Y`, `j/n/Y`, `Y-m-d`.
- `decimal_separator` (`string`, optional): Decimal separator for numbers: period or comma. Example: .. One of: `,`, `.`.
- `default_brand_id` (`string`, optional): ULID of the default brand (from tave_brands_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `email` (`string`, optional): Studio email address. Example: hello@riveraphoto.com.
- `first_name` (`string`, optional): Studio owner's first name, up to 48 characters. Example: Ana.
- `last_name` (`string`, optional): Studio owner's last name, up to 48 characters. Example: Rivera.
- `temperature` (`string`, optional): Temperature unit for weather: Celsius or Fahrenheit. Example: Fahrenheit. One of: `Celsius`, `Fahrenheit`.
- `thousands_separator` (`string`, optional): Thousands separator for numbers: comma or period. Example: ,. One of: `,`, `.`.
- `time_format` (`string`, optional): Time display format: g:ia (12-hour) or H:i (24-hour). Example: g:ia. One of: `g:ia`, `H:i`.
- `timezone_id` (`string`, optional): ULID of the studio timezone (from tave_timezones_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `week_starts_on` (`string`, optional): First day of the week in calendars. Example: Monday. One of: `Sunday`, `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`.

Example input: `{"name":"<name>"}`

### `tave_task_create`

Create Task · Write

Create a task in a task list, optionally on a job and assigned to a user.
Returns the new task.
Use tave_task_create for a follow-up. Get task list IDs from tave_task_lists_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Task name. Example: Send timeline questionnaire.
- `task_list_id` (`string`, required): ULID of the task list (from tave_task_lists_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `completed` (`boolean`, optional): true when the task is done. Example: false.
- `due_date` (`string`, optional): Due date (YYYY-MM-DD). Example: 2026-12-05.
- `job_id` (`string`, optional): ULID of the job the task belongs to. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `user_id` (`string`, optional): ULID of the user the task is assigned to. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"name":"<name>","task_list_id":"<task_list_id>"}`

### `tave_task_update`

Update Task · Write

Update a task, for example to complete it or change its due date (PUT replaces the task: resend name, task list and the other fields to keep).
Returns the updated task.
Use tave_task_update with completed true to finish a task.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the task. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `name` (`string`, required): Task name. Example: Send timeline questionnaire.
- `task_list_id` (`string`, required): ULID of the task list (from tave_task_lists_list). Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `completed` (`boolean`, optional): true when the task is done. Example: false.
- `due_date` (`string`, optional): Due date (YYYY-MM-DD). Example: 2026-12-05.
- `job_id` (`string`, optional): ULID of the job the task belongs to. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.
- `user_id` (`string`, optional): ULID of the user the task is assigned to. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>","name":"<name>","task_list_id":"<task_list_id>"}`

### `tave_tax_group_create`

Create Tax Group · Write

Create a tax group of up to 3 tax rates, optionally compounding or set as the studio default.
Returns the new tax group with its id.
Use tave_tax_group_create to combine rates (for example state plus city). Use tave_tax_rate_create for a single standalone rate.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Tax group name, up to 64 characters. Example: New York City.
- `compounding` (`boolean`, optional): true to apply each rate on top of the previous ones (tax on tax). Defaults to false. Example: false.
- `default` (`boolean`, optional): true to make this the studio's default tax group. Defaults to false. Example: false.
- `tax_rates` (`array`, optional): Up to 3 tax rates in the group, each an object with name, rate (percentage) and inclusive (true if prices include the tax). Example: [{"name": "NY State", "rate": 4, "inclusive": false}].

Example input: `{"name":"<name>"}`

### `tave_tax_group_update`

Update Tax Group · Write

Update a tax group (PUT replaces the group: read it with tave_tax_group_get first and resend the rates and flags you want to keep).
Returns the updated tax group.
Use tave_tax_group_update to change a group's name, rates or default flag. Use tave_tax_rate_update for a standalone rate.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the tax group. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `compounding` (`boolean`, optional): true to apply each rate on top of the previous ones (tax on tax). Defaults to false. Example: false.
- `default` (`boolean`, optional): true to make this the studio's default tax group. Defaults to false. Example: false.
- `name` (`string`, optional): Tax group name, up to 64 characters. Example: New York City.
- `tax_rates` (`array`, optional): Up to 3 tax rates in the group, each an object with name, rate (percentage) and inclusive (true if prices include the tax). Example: [{"name": "NY State", "rate": 4, "inclusive": false}].

Example input: `{"id":"<id>"}`

### `tave_tax_rate_create`

Create Tax Rate · Write

Create a tax rate as a percentage, either added on top of prices or included in them.
Returns the new tax rate with its id.
Use tave_tax_rate_create for a single rate. Use tave_tax_group_create to combine up to 3 rates.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `rate` (`number`, required): Tax rate as a percentage, up to 4 decimal places (8.875 means 8.875%). Example: 8.875.
- `inclusive` (`boolean`, optional): true if prices already include this tax; false adds it on top. Defaults to false. Example: false.
- `name` (`string`, optional): Tax rate name, up to 32 characters. Example: NY Sales Tax.

Example input: `{"rate":8.875}`

### `tave_tax_rate_update`

Update Tax Rate · Write

Update a tax rate (PUT replaces the rate: read it with tave_tax_rate_get first and resend fields you want to keep).
Returns the updated tax rate.
Use tave_tax_rate_update to change a rate's name, percentage or inclusive flag. Use tave_tax_group_update for a group.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the tax rate. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `inclusive` (`boolean`, optional): true if prices already include this tax; false adds it on top. Defaults to false. Example: false.
- `name` (`string`, optional): Tax rate name, up to 32 characters. Example: NY Sales Tax.
- `rate` (`number`, optional): Tax rate as a percentage, up to 4 decimal places (8.875 means 8.875%). Example: 8.875.

Example input: `{"id":"<id>"}`

### `tave_user_create`

Create User · Write

Add a team member (user) to the studio with a sign-in email and admin or billing-contact flags.
Returns the new user with id, username and contactId (the address book contact holding the user's name and phone).
Use tave_user_create to add staff. Use tave_users_list to check the user does not already exist; edit the user's name or phone on the linked contact with tave_contact_update.
Each user is tied to an address book contact; the API sets contactId, and tave_contact_create creates standalone address book entries.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `username` (`string`, required): Email address the user signs in with, 5 to 64 characters. Example: jordan@riveraphoto.com.
- `is_admin` (`boolean`, optional): true to give the user admin rights in the studio. Defaults to false. Example: false.
- `is_billing_contact` (`boolean`, optional): true to make the user the studio's billing contact. Defaults to false. Example: false.

Example input: `{"username":"<username>"}`

### `tave_user_update`

Update User · Write

Update a studio user's sign-in email and admin or billing-contact flags (PUT replaces the user: read it with tave_user_get first and resend fields you want to keep).
Returns the updated user.
Use tave_user_update to change a user's email or permissions. Use tave_contact_update on the user's contactId to change name or phone.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the user. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.
- `is_admin` (`boolean`, optional): true to give the user admin rights in the studio. Defaults to false. Example: false.
- `is_billing_contact` (`boolean`, optional): true to make the user the studio's billing contact. Defaults to false. Example: false.
- `username` (`string`, optional): Email address the user signs in with, 5 to 64 characters. Example: jordan@riveraphoto.com.

Example input: `{"id":"<id>"}`

### `tave_brand_delete`

Delete Brand · Destructive

Delete a brand.
Returns no content on success.
Use tave_brand_delete to remove an unused brand; use tave_brand_update to change one instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the brand. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_contact_delete`

Delete Address Book Entry · Destructive

Delete an address book entry.
Returns no content on success.
Use tave_contact_delete to remove a duplicate contact.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the address book entry. Example: 01j8z3k4m5n6p7q8r9s0t1v2x4.

Example input: `{"id":"<id>"}`

### `tave_custom_field_delete`

Delete Custom Field · Destructive

Delete a custom field definition.
Returns no content on success.
Use tave_custom_field_delete to remove a field no longer used; use tave_custom_field_update to rename or change it instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the custom field. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_discount_delete`

Delete Discount · Destructive

Delete a discount.
Returns no content on success.
Use tave_discount_delete to remove a discount; use tave_discount_type_delete to remove a discount type.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the discount. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_discount_type_delete`

Delete Discount Type · Destructive

Delete a discount type.
Returns no content on success.
Use tave_discount_type_delete to remove a category; use tave_discount_delete to remove a single discount.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the discount type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_event_delete`

Delete Event · Destructive

Delete an event.
Returns no content on success.
Use tave_event_delete to cancel an event.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the event. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_event_type_delete`

Delete Event Type · Destructive

Delete an event type.
Returns no content on success.
Use tave_event_type_delete to remove an unused type; use tave_event_delete to cancel a single event.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the event type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_file_delete`

Delete File · Destructive

Delete a file.
Returns no content on success.
Use tave_file_delete to remove a file permanently. Use tave_file_update to detach it from a record instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the file. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_gallery_delete`

Delete Gallery · Destructive

Delete a client gallery record from the studio.
Returns no content on success.
Use tave_gallery_delete to remove a gallery. Use tave_gallery_update with status archived to keep it.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the gallery. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_job_closed_reason_delete`

Delete Job Closed Reason · Destructive

Delete a job closed reason.
Returns no content on success.
Use tave_job_closed_reason_delete to remove a reason. Use tave_job_closed_reason_partial_update to rename it instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job closed reason. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_job_contact_delete`

Remove Contact from Job · Destructive

Remove a contact from a job (the contact itself is kept).
Returns no content on success.
Use tave_job_contact_delete to unlink a contact.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job contact. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_job_delete`

Delete Job · Destructive

Delete a job.
Returns no content on success.
Use tave_job_delete only for test or duplicate jobs; close real ones with tave_job_update.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job. Example: 01j8z3k4m5n6p7q8r9s0t1v2w3.

Example input: `{"id":"<id>"}`

### `tave_job_role_delete`

Delete Job Role · Destructive

Delete a job role.
Returns no content on success.
Use tave_job_role_delete to remove a role. Use tave_job_role_update to rename it instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job role. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_job_type_delete`

Delete Job Type · Destructive

Delete a job type.
Returns no content on success.
Use tave_job_type_delete to remove a type. Use tave_job_type_update to rename it instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the job type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_lead_source_delete`

Delete Lead Source · Destructive

Delete a lead source.
Returns no content on success.
Use tave_lead_source_delete to remove a channel you no longer track. Use tave_lead_source_update to rename it instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the lead source. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_lead_status_delete`

Delete Lead Status · Destructive

Delete a lead status.
Returns no content on success.
Use tave_lead_status_delete to remove a stage you no longer use. Use tave_lead_status_partial_update to rename it instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the lead status. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_note_delete`

Delete Note · Destructive

Delete a note.
Returns no content on success.
Use tave_note_delete to remove a note.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the note. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_order_void`

Void Order · Destructive

Void an order so it no longer bills the client.
Returns the voided order.
Use tave_order_void to cancel a booked order.

Read only: no. Destructive: yes. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): ULID of the order. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_payment_delete`

Delete Payment · Destructive

Delete a recorded payment.
Returns no content on success.
Use tave_payment_delete to remove a payment recorded in error. Use tave_payment_update to correct its details instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the payment. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_product_delete`

Delete Product · Destructive

Delete a product or service.
Returns no content on success.
Use tave_product_delete to remove a product you no longer sell. Use tave_product_partial_update or tave_product_update to change it instead.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the product. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_product_type_delete`

Delete Product Type · Destructive

Delete a product type.
Returns no content on success.
Use tave_product_type_delete to remove a category you no longer use.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the product type. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_profit_center_delete`

Delete Profit Center · Destructive

Delete a profit center.
Returns no content on success.
Use tave_profit_center_delete to remove an unused category. Move products to another profit center first with tave_product_update.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the profit center. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_rest_hook_delete`

Delete REST Hook · Destructive

Unsubscribe and delete a REST Hook webhook subscription; the target URL stops receiving postbacks.
Returns no content on success.
Use tave_rest_hook_delete to stop a webhook. Use tave_rest_hooks_list to find the subscription ID.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the REST Hook subscription. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_studio_readonly_mode_set`

Set Studio Read-Only Mode · Destructive

Turn read-only mode on or off for the whole studio. While on, the studio is locked: no one can create or change jobs, contacts, orders, payments or other records until it is turned off.
Returns the studio, including readonlyEnabledAt when read-only mode is on.
Use tave_studio_readonly_mode_set only when the studio owner explicitly asks to lock or unlock the studio. Use tave_studio_update for ordinary settings and tave_studio_get to check the current state.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `enabled` (`boolean`, required): true locks the whole studio in read-only mode; false unlocks it. Example: false.

Example input: `{"enabled":true}`

### `tave_task_delete`

Delete Task · Destructive

Delete a task.
Returns no content on success.
Use tave_task_delete to remove a task.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the task. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_tax_group_delete`

Delete Tax Group · Destructive

Delete a tax group.
Returns no content on success.
Use tave_tax_group_delete to remove a group. Use tave_tax_rate_delete for a standalone rate.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the tax group. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

### `tave_tax_rate_delete`

Delete Tax Rate · Destructive

Delete a tax rate.
Returns no content on success.
Use tave_tax_rate_delete to remove a rate. Use tave_tax_group_delete for a tax group.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): ULID of the tax rate. Example: 01j8z3k4m5n6p7q8r9s0t1v2y5.

Example input: `{"id":"<id>"}`

## Related

Other Project Management connectors ([all 67](/agentkit/connectors/?category=project-management)):

- [Notion](/agentkit/connectors/notion/): Scalekit connector, OAuth, 51 tools
- [Linear](/agentkit/connectors/linear/): Scalekit connector, OAuth, 64 tools
- [Airtable](/agentkit/connectors/airtable/): Scalekit connector, OAuth, 26 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
