# Smokeball

> Run your law firm's Smokeball from workflows: open and update matters, add contacts, tasks, memos, time entries, expenses and calendar events. Start a workflow when a matter is opened or changed, a contact is added or changed, or a task is added or completed.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/smokeball

## Actions

### Add calendar event

Add an appointment to Smokeball's calendar, such as a meeting or a hearing, on a matter or on its own. Smokeball saves it within a few seconds.

**Inputs**

- Subject (`subject`, text, required): What the event is.
- Starts (`start_time`, date and time, required): When it starts.
- Ends (`end_time`, date and time, required): When it ends.
- Time zone (`time_zone`, text): The time zone to show it in. Defaults to UTC.
- Matter (`matter_id`, text): The matter it belongs to, if any.
- Attendees (`attendee_ids`, list): The staff members attending.
- Location (`location`, text): Where it is.
- Description (`description`, text): More detail.
- All day (`all_day`, true/false): On makes it an all-day event.

**Outputs**

- `href` (text): Its address in Smokeball's API
- `id` (text): The record's ID, for the next step

**Example output**

```json
{
  "href": "https://api.smokeball.com/events/5d0e7a4c-2b9f-4c61-8e3a-7f1b6d2c9e05",
  "id": "5d0e7a4c-2b9f-4c61-8e3a-7f1b6d2c9e05"
}
```

### Add contact

Add a person or a company to your firm's contacts. Smokeball saves it within a few seconds.

**Inputs**

- Type (`contact_type`, text): A person or a company. Defaults to a person. One of: `person`, `company`. Default: `person`.
- First name (`first_name`, text): A person's first name.
- Last name (`last_name`, text): A person's last name.
- Company name (`company_name`, text): A company's name.
- Email (`email`, text): Their email address.
- Phone (`phone`, text): Their phone number.
- Mobile (`mobile`, text): A person's mobile number.
- Notes (`notes`, text): Notes on the contact.

**Outputs**

- `href` (text): Its address in Smokeball's API
- `id` (text): The record's ID, for the next step

**Example output**

```json
{
  "href": "https://api.smokeball.com/contacts/9a9ce552-6bee-45e4-8eb1-afe2c18c489f",
  "id": "9a9ce552-6bee-45e4-8eb1-afe2c18c489f"
}
```

### Add expense

Record a cost on a matter, such as a filing fee or travel. Smokeball saves it within a few seconds.

**Inputs**

- Matter (`matter_id`, text, required): The matter. Pick an open one, or give its ID from an earlier step.
- Subject (`subject`, text, required): What it was for.
- Price (`price`, number, required): The cost of one unit, such as 45.50.
- Quantity (`quantity`, number): How many units. Defaults to 1. Default: `1`.
- Date (`expense_date`, date): When it was spent. Defaults to today.
- Cost type (`cost_type`, text): Defaults to a hard cost. One of: `Hard` (Hard cost, such as travel or filing fees (default)), `Soft` (Soft cost, such as copying or admin). Default: `Hard`.
- Staff member (`staff_id`, text): Who spent it. Leave blank to file it under the firm's owner.
- Description (`description`, text): More detail.
- Billable (`billable`, true/false): Off records it without billing it. Defaults to on. Default: `true`.

**Outputs**

- `href` (text): Its address in Smokeball's API
- `id` (text): The record's ID, for the next step

**Example output**

```json
{
  "href": "https://api.smokeball.com/expenses/0b6d2c1e-8f4a-4e3b-a1d9-2c7f5e9b3a60",
  "id": "0b6d2c1e-8f4a-4e3b-a1d9-2c7f5e9b3a60"
}
```

### Add memo

Add a memo (file note) to a matter, such as a note of a call. Smokeball saves it within a few seconds.

**Inputs**

- Matter (`matter_id`, text, required): The matter. Pick an open one, or give its ID from an earlier step.
- Title (`title`, text, required): A short title.
- Text (`text`, text, required): What the memo says.

**Outputs**

- `href` (text): Its address in Smokeball's API
- `id` (text): The record's ID, for the next step

**Example output**

```json
{
  "href": "https://api.smokeball.com/matters/3f2c7a10-55a1-4f0e-9a43-0c7d8b9e6f21",
  "id": "3f2c7a10-55a1-4f0e-9a43-0c7d8b9e6f21"
}
```

### Add task

Add a task, on a matter or on its own, and assign it to staff. Smokeball saves it within a few seconds.

**Inputs**

- Subject (`subject`, text, required): What needs doing.
- Created by (`staff_id`, text, required): The staff member adding the task. It is assigned to them unless you pick others.
- Assign to (`assignee_ids`, list): The staff members to do it.
- Matter (`matter_id`, text): The matter it belongs to, if any.
- Due on (`due_date`, date): When it is due.
- Notes (`note`, text): More detail.

**Outputs**

- `href` (text): Its address in Smokeball's API
- `id` (text): The record's ID, for the next step

**Example output**

```json
{
  "href": "https://api.smokeball.com/tasks/1bf55840-cba3-4f8a-8c0f-66082692e493",
  "id": "1bf55840-cba3-4f8a-8c0f-66082692e493"
}
```

### Add time entry

Record time worked on a matter, billed at the staff member's rate unless you give one. Smokeball saves it within a few seconds.

**Inputs**

- Matter (`matter_id`, text, required): The matter. Pick an open one, or give its ID from an earlier step.
- Staff member (`staff_id`, text, required): Who did the work.
- Subject (`subject`, text, required): What the work was.
- Minutes (`minutes`, number, required): How long, in minutes, such as 30.
- Date (`fee_date`, date): When the work was done. Defaults to today.
- Hourly rate (`rate`, number): Leave blank to use the staff member's rate in Smokeball.
- Description (`description`, text): More detail.
- Billable (`billable`, true/false): Off records the time without billing it. Defaults to on. Default: `true`.

**Outputs**

- `href` (text): Its address in Smokeball's API
- `id` (text): The record's ID, for the next step

**Example output**

```json
{
  "href": "https://api.smokeball.com/fees/7e3f6b52-1a0c-4b8e-9f27-5d61c2a8e914",
  "id": "7e3f6b52-1a0c-4b8e-9f27-5d61c2a8e914"
}
```

### Create matter

Open a new matter for one or more client contacts. Smokeball saves it within a few seconds.

**Inputs**

- Matter type (`matter_type_id`, text, required): The area of law and state, such as Financing (Real Estate, IL).
- Clients (`client_ids`, list, required): The client contacts. Pick them, or give IDs from an earlier step such as 'Add contact'.
- Description (`description`, text): What the matter is about.
- Status (`status`, text): Defaults to Open. One of: `Open`, `Pending`, `Closed`, `Cancelled`, `Deleted`. Default: `Open`.
- Person responsible (`person_responsible_id`, text): The staff member responsible for the matter.
- Person assisting (`person_assisting_id`, text): The staff member assisting.
- Other side (`other_side_ids`, list): Contacts on the other side, if any.
- Matter number (`number`, text): Leave blank for Smokeball to number it.
- Opened on (`opened_date`, date): Defaults to today. Can be earlier.

**Outputs**

- `href` (text): Its address in Smokeball's API
- `id` (text): The record's ID, for the next step

**Example output**

```json
{
  "href": "https://api.smokeball.com/matters/51cefb72-6247-4ca2-8926-5d14d65f7cb9",
  "id": "51cefb72-6247-4ca2-8926-5d14d65f7cb9"
}
```

### Delete contact

Delete a contact. Smokeball keeps deleted contacts, and they can be restored there.

**Inputs**

- Contact (`contact_id`, text, required): The contact. Pick one, or give its ID from an earlier step.

**Outputs**

- `deleted` (true/false): Always true once done
- `id` (text): The record deleted

**Example output**

```json
{
  "deleted": true,
  "id": "9a9ce552-6bee-45e4-8eb1-afe2c18c489f"
}
```

### Delete task

Delete a task.

**Inputs**

- Task (`task_id`, text, required): The task's ID, from 'List tasks', 'Add task' or a task trigger.

**Outputs**

- `deleted` (true/false): Always true once done
- `id` (text): The record deleted

**Example output**

```json
{
  "deleted": true,
  "id": "1bf55840-cba3-4f8a-8c0f-66082692e493"
}
```

### Get contact

Get one contact with every detail Smokeball holds.

**Inputs**

- Contact (`contact_id`, text, required): The contact. Pick one, or give its ID from an earlier step.

**Outputs**

- `contact` (object): The contact
- `name` (text): Their name, ready to use

**Example output**

```json
{
  "contact": {
    "company": null,
    "id": "9a9ce552-6bee-45e4-8eb1-afe2c18c489f",
    "isDeleted": false,
    "lastUpdated": 638668800000000000,
    "person": {
      "cell": {
        "areaCode": "",
        "number": ""
      },
      "email": "jane.smith@example.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "notes": "",
      "phone": {
        "areaCode": "312",
        "number": "555 0100"
      }
    }
  },
  "name": "Jane Smith"
}
```

### Get matter

Get one matter with its type, clients, other sides, staff, status and dates.

**Inputs**

- Matter (`matter_id`, text, required): The matter. Pick an open one, or give its ID from an earlier step.

**Outputs**

- `matter` (object): The matter

**Example output**

```json
{
  "matter": {
    "clients": [
      {
        "href": "https://api.smokeball.com/contacts/9a9ce552-6bee-45e4-8eb1-afe2c18c489f",
        "id": "9a9ce552-6bee-45e4-8eb1-afe2c18c489f"
      }
    ],
    "closedDate": null,
    "description": "Sale of 12 Oak Street",
    "id": "51cefb72-6247-4ca2-8926-5d14d65f7cb9",
    "matterType": {
      "href": "https://api.smokeball.com/mattertypes/8aca3574-aecb-4a6f-991d-680861bece1d_IL",
      "id": "8aca3574-aecb-4a6f-991d-680861bece1d_IL"
    },
    "number": "Matter-001",
    "openedDate": "2026-11-03T04:18:22Z",
    "otherSides": [],
    "personAssisting": null,
    "personResponsible": {
      "href": "https://api.smokeball.com/staff/c85d28cb-a760-4627-aa59-0a853c2e65ed",
      "id": "c85d28cb-a760-4627-aa59-0a853c2e65ed"
    },
    "status": "Open",
    "title": "Matter-001 - Smith - Sale - Jones",
    "versionId": "638138489289266248"
  }
}
```

### Get task

Get one task with its matter, assignees, notes and dates.

**Inputs**

- Task (`task_id`, text, required): The task's ID, from 'List tasks', 'Add task' or a task trigger.

**Outputs**

- `task` (object): The task

**Example output**

```json
{
  "task": {
    "assignees": [
      {
        "href": "https://api.smokeball.com/staff/c85d28cb-a760-4627-aa59-0a853c2e65ed",
        "id": "c85d28cb-a760-4627-aa59-0a853c2e65ed"
      }
    ],
    "completedBy": null,
    "completedDateOnly": null,
    "createdBy": {
      "href": "https://api.smokeball.com/staff/c85d28cb-a760-4627-aa59-0a853c2e65ed",
      "id": "c85d28cb-a760-4627-aa59-0a853c2e65ed"
    },
    "createdDateOnly": "2026-11-18T00:00:00",
    "dueDateOnly": "2026-11-20T00:00:00",
    "id": "1bf55840-cba3-4f8a-8c0f-66082692e493",
    "isCompleted": false,
    "lastUpdated": 638675712000000000,
    "matter": {
      "href": "https://api.smokeball.com/matters/51cefb72-6247-4ca2-8926-5d14d65f7cb9",
      "id": "51cefb72-6247-4ca2-8926-5d14d65f7cb9"
    },
    "note": "Use the residential template.",
    "subject": "Send engagement letter"
  }
}
```

### List contacts

Find people and companies in your firm's contacts by name or email.

**Inputs**

- Name (`name`, text): Part of the contact's name.
- Email (`email`, text): The contact's exact email address.
- Type (`contact_type`, text): Only people, or only companies. Leave blank for both. One of: `person`, `company`.
- How many (`limit`, number): The most to return, up to 2,000. Defaults to 100. Default: `100`.

**Outputs**

- `contacts` (list): The contacts
- `count` (number): How many were returned
- `total` (number): How many Smokeball holds in all

**Example output**

```json
{
  "contacts": [
    {
      "company": null,
      "id": "9a9ce552-6bee-45e4-8eb1-afe2c18c489f",
      "isDeleted": false,
      "lastUpdated": 638668800000000000,
      "person": {
        "cell": {
          "areaCode": "",
          "number": ""
        },
        "email": "jane.smith@example.com",
        "firstName": "Jane",
        "lastName": "Smith",
        "notes": "",
        "phone": {
          "areaCode": "312",
          "number": "555 0100"
        }
      }
    }
  ],
  "count": 1,
  "total": 1
}
```

### List matters

List your firm's matters, with their number, title, status, type, clients and the staff responsible.

**Inputs**

- Search (`search`, text): Words to look for in clients, other sides, descriptions and matter numbers.
- Status (`status`, list): Only matters with these statuses. Leave blank for any. One or more of: `Open`, `Pending`, `Closed`, `Cancelled`, `Deleted`.
- Matter type (`matter_type_id`, text): Only matters of this type.
- Contact (`contact_id`, text): Only matters this contact is on.
- How many (`limit`, number): The most to return, up to 2,000. Defaults to 100. Default: `100`.

**Outputs**

- `count` (number): How many were returned
- `matters` (list): The matters
- `total` (number): How many Smokeball holds in all

**Example output**

```json
{
  "count": 1,
  "matters": [
    {
      "clients": [
        {
          "href": "https://api.smokeball.com/contacts/9a9ce552-6bee-45e4-8eb1-afe2c18c489f",
          "id": "9a9ce552-6bee-45e4-8eb1-afe2c18c489f"
        }
      ],
      "closedDate": null,
      "description": "Sale of 12 Oak Street",
      "id": "51cefb72-6247-4ca2-8926-5d14d65f7cb9",
      "matterType": {
        "href": "https://api.smokeball.com/mattertypes/8aca3574-aecb-4a6f-991d-680861bece1d_IL",
        "id": "8aca3574-aecb-4a6f-991d-680861bece1d_IL"
      },
      "number": "Matter-001",
      "openedDate": "2026-11-03T04:18:22Z",
      "otherSides": [],
      "personAssisting": null,
      "personResponsible": {
        "href": "https://api.smokeball.com/staff/c85d28cb-a760-4627-aa59-0a853c2e65ed",
        "id": "c85d28cb-a760-4627-aa59-0a853c2e65ed"
      },
      "status": "Open",
      "title": "Matter-001 - Smith - Sale - Jones",
      "versionId": "638138489289266248"
    }
  ],
  "total": 1
}
```

### List memos

List the memos (file notes) on a matter, with their text.

**Inputs**

- Matter (`matter_id`, text, required): The matter. Pick an open one, or give its ID from an earlier step.
- How many (`limit`, number): The most to return, up to 2,000. Defaults to 100. Default: `100`.

**Outputs**

- `count` (number): How many were returned
- `memos` (list): The memos
- `total` (number): How many Smokeball holds in all

**Example output**

```json
{
  "count": 1,
  "memos": [
    {
      "createdByUserId": "526670af-acd8-401e-bc64-6d4cafb4a12a",
      "createdDate": "2026-11-18T03:12:00Z",
      "id": "3f2c7a10-55a1-4f0e-9a43-0c7d8b9e6f21",
      "lastUpdated": "2026-11-18T03:12:00Z",
      "matterId": "51cefb72-6247-4ca2-8926-5d14d65f7cb9",
      "plainText": "Client confirmed the settlement date.",
      "title": "Call with client"
    }
  ],
  "total": 1
}
```

### List tasks

List tasks, on one matter or across the firm, with who they are assigned to and when they are due.

**Inputs**

- Matter (`matter_id`, text): Only tasks on this matter. Leave blank for every matter.
- Status (`status`, text): Tasks not yet completed, completed ones, or both. One of: `open` (Not completed (default)), `completed`, `all` (Both). Default: `open`.
- How many (`limit`, number): The most to return, up to 2,000. Defaults to 100. Default: `100`.

**Outputs**

- `count` (number): How many were returned
- `tasks` (list): The tasks
- `total` (number): How many Smokeball holds in all

**Example output**

```json
{
  "count": 1,
  "tasks": [
    {
      "assignees": [
        {
          "href": "https://api.smokeball.com/staff/c85d28cb-a760-4627-aa59-0a853c2e65ed",
          "id": "c85d28cb-a760-4627-aa59-0a853c2e65ed"
        }
      ],
      "completedBy": null,
      "completedDateOnly": null,
      "createdBy": {
        "href": "https://api.smokeball.com/staff/c85d28cb-a760-4627-aa59-0a853c2e65ed",
        "id": "c85d28cb-a760-4627-aa59-0a853c2e65ed"
      },
      "createdDateOnly": "2026-11-18T00:00:00",
      "dueDateOnly": "2026-11-20T00:00:00",
      "id": "1bf55840-cba3-4f8a-8c0f-66082692e493",
      "isCompleted": false,
      "lastUpdated": 638675712000000000,
      "matter": {
        "href": "https://api.smokeball.com/matters/51cefb72-6247-4ca2-8926-5d14d65f7cb9",
        "id": "51cefb72-6247-4ca2-8926-5d14d65f7cb9"
      },
      "note": "Use the residential template.",
      "subject": "Send engagement letter"
    }
  ],
  "total": 1
}
```

### List time and fees

List the time entries and fixed fees on a matter, with who did the work, minutes and amounts.

**Inputs**

- Matter (`matter_id`, text, required): The matter. Pick an open one, or give its ID from an earlier step.
- How many (`limit`, number): The most to return, up to 2,000. Defaults to 100. Default: `100`.

**Outputs**

- `count` (number): How many were returned
- `fees` (list): The time entries and fees
- `total` (number): How many Smokeball holds in all

**Example output**

```json
{
  "count": 1,
  "fees": [
    {
      "amount": 175,
      "createdDate": "2026-11-18T03:20:00Z",
      "description": "",
      "duration": 30,
      "feeDate": "2026-11-18T00:00:00Z",
      "feeType": 1,
      "id": "7e3f6b52-1a0c-4b8e-9f27-5d61c2a8e914",
      "isBillable": true,
      "matter": {
        "href": "https://api.smokeball.com/matters/51cefb72-6247-4ca2-8926-5d14d65f7cb9",
        "id": "51cefb72-6247-4ca2-8926-5d14d65f7cb9"
      },
      "rate": 350,
      "staff": {
        "href": "https://api.smokeball.com/staff/c85d28cb-a760-4627-aa59-0a853c2e65ed",
        "id": "c85d28cb-a760-4627-aa59-0a853c2e65ed"
      },
      "subject": "Review contract of sale"
    }
  ],
  "total": 1
}
```

### Update contact

Change a person's or company's name, email, phone or notes. Fields left blank stay as they are. Smokeball saves it within a few seconds.

**Inputs**

- Contact (`contact_id`, text, required): The contact. Pick one, or give its ID from an earlier step.
- First name (`first_name`, text): A person's first name. Leave blank to keep it.
- Last name (`last_name`, text): A person's last name. Leave blank to keep it.
- Company name (`company_name`, text): A company's name. Leave blank to keep it.
- Email (`email`, text): Their email address. Leave blank to keep it.
- Phone (`phone`, text): Their phone number. Leave blank to keep it.
- Mobile (`mobile`, text): A person's mobile number. Leave blank to keep it.
- Notes (`notes`, text): Notes on the contact. Leave blank to keep it. Replaces the notes there.

**Outputs**

- `href` (text): Its address in Smokeball's API
- `id` (text): The record's ID, for the next step

**Example output**

```json
{
  "href": "https://api.smokeball.com/contacts/9a9ce552-6bee-45e4-8eb1-afe2c18c489f",
  "id": "9a9ce552-6bee-45e4-8eb1-afe2c18c489f"
}
```

### Update matter

Change a matter's description, status, staff, number or dates. Fields left blank stay as they are. Smokeball saves it within a few seconds.

**Inputs**

- Matter (`matter_id`, text, required): The matter. Pick an open one, or give its ID from an earlier step.
- Description (`description`, text): A new description.
- Status (`status`, text): The matter's status. One of: `Open`, `Pending`, `Closed`, `Cancelled`, `Deleted`.
- Person responsible (`person_responsible_id`, text): The staff member now responsible.
- Person assisting (`person_assisting_id`, text): The staff member now assisting.
- Matter number (`number`, text): A new matter number.
- Opened on (`opened_date`, date): A new opened date.
- Closed on (`closed_date`, date): When the matter was closed.

**Outputs**

- `href` (text): Its address in Smokeball's API
- `id` (text): The record's ID, for the next step

**Example output**

```json
{
  "href": "https://api.smokeball.com/matters/51cefb72-6247-4ca2-8926-5d14d65f7cb9",
  "id": "51cefb72-6247-4ca2-8926-5d14d65f7cb9"
}
```

### Update task

Change a task's subject, notes, due date or assignees, or mark it completed. Fields left blank stay as they are. Smokeball saves it within a few seconds.

**Inputs**

- Task (`task_id`, text, required): The task's ID, from 'List tasks', 'Add task' or a task trigger.
- Subject (`subject`, text): A new subject.
- Notes (`note`, text): New notes. Replaces the notes there.
- Due on (`due_date`, date): A new due date.
- Assign to (`assignee_ids`, list): The staff members to do it. Replaces those assigned now.
- Completed (`completed`, true/false): On marks the task completed; off reopens it.
- Changed by (`staff_id`, text): The staff member making the change. Defaults to whoever last changed the task.

**Outputs**

- `href` (text): Its address in Smokeball's API
- `id` (text): The record's ID, for the next step

**Example output**

```json
{
  "href": "https://api.smokeball.com/tasks/1bf55840-cba3-4f8a-8c0f-66082692e493",
  "id": "1bf55840-cba3-4f8a-8c0f-66082692e493"
}
```
