# SuiteDash API

> Every SuiteDash endpoint on Cotlet: inputs, JSON Schema, cURL, Python and Node.js examples and an example response for each call.

Source: https://cotlet.dev/docs/api/suitedash

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

14 endpoints for SuiteDash. Each one is a POST with a JSON body, called with your API key.

- Base URL: `https://cotlet.dev/api/v1/suitedash`
- Connects with: Your own SuiteDash account (admin for invoices, payments and the CRM)
- Integration page: https://cotlet.dev/integrations/suitedash-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `find_contact` | read | Contacts and companies by name or email, with role, company and custom fields. |
| `list_projects` | read | Projects with client, status, Project Leader, start and estimated completion dates. |
| `list_tasks` | read | Tasks with assignee, due date, priority, status and project. |
| `list_invoices` | read | Invoices with number, client, title, total, amount paid, due date and status. |
| `get_invoice` | read | Full invoice: line items, discounts, taxes, payments, notes and payment link. |
| `list_message_threads` | read | Secure Messaging threads with subject, participants, last message and unread flag. |
| `create_contact` | write | New Lead, Prospect or Client in your CRM. No portal invitation is sent. |
| `create_project` | write | New project for a client, optionally from a Task Template. |
| `add_task` | write | New task in a project or standalone, assigned to a teammate. |
| `complete_task` | write | Mark a task as Completed. |
| `create_invoice` | write | Invoice for a client from your Office items. Saved as Draft unless you open and send it. |
| `record_payment` | write | Record a payment made outside SuiteDash against an open invoice. |
| `send_message` | write | New Secure Messaging thread, or a reply in an existing one. |
| `share_file` | write | Upload a file to the Sharing Folder of a client. |

## Find contact

`POST https://cotlet.dev/api/v1/suitedash/find_contact`

Access: read.

Searches your CRM by name, company name or email and returns the matches with their UID, role and company. Use the UID as client_id or contact_id in the other tools. Role is Lead, Prospect or Client as in your CRM.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Name, company name or email. |
| `role` | enum | no | lead, prospect or client. Default: any. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/find_contact \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"query"}'
```

**Python**

```python
result = client.call("suitedash", "find_contact", {"query":"query"})
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'find_contact', {"query":"query"});
```

**CLI**

```bash
cotlet call suitedash find_contact --data '{"query":"query"}'
```

### Example response

```json
{
  "contacts": [
    {
      "contact_id": "c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71",
      "name": "Ana Lopez",
      "email": "ana@acmestudio.example",
      "role": "client",
      "company": "Acme Studio"
    }
  ]
}
```

## List projects

`POST https://cotlet.dev/api/v1/suitedash/list_projects`

Access: read.

Lists projects, optionally for one client. Archived projects are left out unless you ask. Use project_id in add_task and list_tasks.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | no | Only projects of this contact or company. |
| `include_archived` | boolean | no | Include archived projects. Default: false. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/list_projects \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("suitedash", "list_projects")
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'list_projects');
```

**CLI**

```bash
cotlet call suitedash list_projects
```

### Example response

```json
{
  "projects": [
    {
      "project_id": "p_2201",
      "name": "Website Redesign",
      "client": "Acme Studio",
      "status": "In progress",
      "leader": "you@yourcompany.example",
      "start_date": "2026-10-12",
      "completion_date": "2026-12-01"
    }
  ]
}
```

## List tasks

`POST https://cotlet.dev/api/v1/suitedash/list_tasks`

Access: read.

Lists tasks across your account, or in one project. Set mine_only to see your My Tasks list. Completed tasks are left out unless you ask.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `project_id` | string | no | Only tasks in this project. |
| `mine_only` | boolean | no | Only tasks assigned to you (My Tasks). Default: false. |
| `include_completed` | boolean | no | Include completed tasks. Default: false. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/list_tasks \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("suitedash", "list_tasks")
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'list_tasks');
```

**CLI**

```bash
cotlet call suitedash list_tasks
```

### Example response

```json
{
  "tasks": [
    {
      "task_id": "t_8841",
      "title": "Kickoff call",
      "project": "Website Redesign",
      "assigned_to": "you@yourcompany.example",
      "due_date": "2026-10-14",
      "priority": "Normal",
      "status": "Open"
    }
  ]
}
```

## List invoices

`POST https://cotlet.dev/api/v1/suitedash/list_invoices`

Access: read.

Lists invoices from Office, newest first. Filter by status, client or due date to find what is overdue. Total and amount paid are in the invoice currency, so a partial payment shows what is still owed.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `status` | enum | no | draft, open, partially_paid or paid. Default: open. |
| `client_id` | string | no | Only invoices of this client. |
| `due_before` | date | no | Only invoices due before this date. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/list_invoices \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("suitedash", "list_invoices")
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'list_invoices');
```

**CLI**

```bash
cotlet call suitedash list_invoices
```

### Example response

```json
{
  "invoices": [
    {
      "invoice_id": "58213",
      "invoice_number": "1042",
      "client": "Acme Studio",
      "title": "Website design, October",
      "total": "900.00",
      "paid": "0.00",
      "currency": "USD",
      "due_date": "2026-10-10",
      "status": "open"
    }
  ]
}
```

## Get invoice

`POST https://cotlet.dev/api/v1/suitedash/get_invoice`

Access: read.

Returns one invoice with its line items, payments recorded so far and the payment link your client uses. Read it before record_payment to check what is still owed.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `invoice_id` | string | yes | Invoice ID from list_invoices. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/get_invoice \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"invoice_8c41d2"}'
```

**Python**

```python
result = client.call("suitedash", "get_invoice", {"invoice_id":"invoice_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'get_invoice', {"invoice_id":"invoice_8c41d2"});
```

**CLI**

```bash
cotlet call suitedash get_invoice --data '{"invoice_id":"invoice_8c41d2"}'
```

### Example response

```json
{
  "invoice_id": "58213",
  "invoice_number": "1042",
  "status": "open",
  "title": "Website design, October",
  "items": [
    {
      "item": "Design hour",
      "quantity": 10,
      "rate": "90.00",
      "amount": "900.00"
    }
  ],
  "total": "900.00",
  "paid": "0.00",
  "payments": [],
  "currency": "USD",
  "due_date": "2026-10-24",
  "payment_link": "https://yourname.suitedash.com/pay/invoice/58213"
}
```

## List message threads

`POST https://cotlet.dev/api/v1/suitedash/list_message_threads`

Access: read.

Lists Secure Messaging threads in a folder, most recent first, with the last message and an unread flag. The folder is Inbox unless you name another. Use thread_id to reply with send_message.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `folder` | string | no | Folder name. Default: Inbox. |
| `unread_only` | boolean | no | Only threads with unread messages. |
| `limit` | integer | no | 1 to 50. Default: 20. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/list_message_threads \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("suitedash", "list_message_threads")
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'list_message_threads');
```

**CLI**

```bash
cotlet call suitedash list_message_threads
```

### Example response

```json
{
  "threads": [
    {
      "thread_id": "th_3a91",
      "subject": "Deadline for the logo files",
      "participants": [
        "Ana Lopez"
      ],
      "last_message": "Can we move the deadline to Friday?",
      "unread": true,
      "updated_at": "2026-10-09T15:40:00Z"
    }
  ]
}
```

## Create contact

`POST https://cotlet.dev/api/v1/suitedash/create_contact`

Access: write.

Adds one contact to your CRM and links it to a company, creating the company if it does not exist. No portal invitation or email goes out, and one edit in SuiteDash undoes it, so this tool runs without asking.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `first_name` | string | yes | First name. |
| `last_name` | string | yes | Last name. |
| `email` | string | yes | Email address. |
| `role` | enum | yes | lead, prospect or client. |
| `company_name` | string | no | Company to link, created if it does not exist. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/create_contact \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"first name","last_name":"last name","email":"jane@example.com","role":"lead"}'
```

**Python**

```python
result = client.call("suitedash", "create_contact", {"first_name":"first name","last_name":"last name","email":"jane@example.com","role":"lead"})
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'create_contact', {"first_name":"first name","last_name":"last name","email":"jane@example.com","role":"lead"});
```

**CLI**

```bash
cotlet call suitedash create_contact --data '{"first_name":"first name","last_name":"last name","email":"jane@example.com","role":"lead"}'
```

### Example response

```json
{
  "contact_id": "c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71",
  "name": "Jane Doe",
  "role": "client",
  "company": "Doe Studio",
  "status": "created"
}
```

## Create project

`POST https://cotlet.dev/api/v1/suitedash/create_project`

Access: write.

Creates a project for one client. With task_template, the project gets that template's tasks and phases. Nothing is sent to the client, and the project can be archived afterwards, so this tool runs without asking.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Project Name. |
| `client_id` | string | yes | Client UID from find_contact. |
| `task_template` | string | no | Task Template name; adds its tasks and phases. |
| `start_date` | date | no | Project Start Date. |
| `completion_date` | date | no | Estimated Completion Date. |
| `estimated_value` | string | no | Estimated value, e.g. "2500 USD". |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/create_project \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","client_id":"client_8c41d2"}'
```

**Python**

```python
result = client.call("suitedash", "create_project", {"name":"Jane Doe","client_id":"client_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'create_project', {"name":"Jane Doe","client_id":"client_8c41d2"});
```

**CLI**

```bash
cotlet call suitedash create_project --data '{"name":"Jane Doe","client_id":"client_8c41d2"}'
```

### Example response

```json
{
  "project_id": "p_2201",
  "name": "Website Redesign",
  "client_id": "c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71",
  "status": "created",
  "start_date": "2026-10-12",
  "completion_date": "2026-12-01"
}
```

## Add task

`POST https://cotlet.dev/api/v1/suitedash/add_task`

Access: write.

Adds a task to a project, or a standalone task when project_id is empty. It is assigned to you unless you give a staff email. Priority uses the names in your account. Runs without asking: the task reaches only your team and complete_task closes it.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `title` | string | yes | Task title. |
| `project_id` | string | no | Project from list_projects. Empty: standalone task. |
| `assigned_to` | string | no | Staff email. Default: you. |
| `due_date` | date | no | Due Date. |
| `priority` | string | no | Priority as named in your account. Default: Normal. |
| `description` | string | no | Task description. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/add_task \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"title"}'
```

**Python**

```python
result = client.call("suitedash", "add_task", {"title":"title"})
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'add_task', {"title":"title"});
```

**CLI**

```bash
cotlet call suitedash add_task --data '{"title":"title"}'
```

### Example response

```json
{
  "task_id": "t_8841",
  "title": "Kickoff call",
  "project_id": "p_2201",
  "assigned_to": "you@yourcompany.example",
  "due_date": "2026-10-14",
  "status": "created"
}
```

## Complete task

`POST https://cotlet.dev/api/v1/suitedash/complete_task`

Access: write.

Marks one task as Completed. It runs without asking, because it reaches no client and one edit in SuiteDash reopens the task.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `task_id` | string | yes | Task ID from list_tasks. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/complete_task \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"task_8c41d2"}'
```

**Python**

```python
result = client.call("suitedash", "complete_task", {"task_id":"task_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'complete_task', {"task_id":"task_8c41d2"});
```

**CLI**

```bash
cotlet call suitedash complete_task --data '{"task_id":"task_8c41d2"}'
```

### Example response

```json
{
  "task_id": "t_8841",
  "status": "completed"
}
```

## Create invoice

`POST https://cotlet.dev/api/v1/suitedash/create_invoice`

Access: write. Confirm: waits for the user's OK before it runs.

Creates an invoice for one client from items set up in Office, with a due date. The total is the sum of quantity times rate. With status draft nothing is sent. With status open the client can pay it, and notify_client sends the New Invoice notification. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `client_id` | string | yes | Client UID from find_contact. |
| `title` | string | yes | Title visible to the client. |
| `items` | object | yes | List of { item, quantity, rate }. item is an Item from Office settings. |
| `due_date` | date | yes | Due Date. |
| `status` | enum | no | draft or open. Default: draft. |
| `notify_client` | boolean | no | Send the New Invoice notification when open. Default: true. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/create_invoice \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71","title":"Website design, October","items":[{"item":"Design hour","quantity":10,"rate":90}],"due_date":"2026-10-24","status":"open","notify_client":true}'
```

**Python**

```python
result = client.call("suitedash", "create_invoice", {"client_id":"c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71","title":"Website design, October","items":[{"item":"Design hour","quantity":10,"rate":90}],"due_date":"2026-10-24","status":"open","notify_client":True})
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'create_invoice', {"client_id":"c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71","title":"Website design, October","items":[{"item":"Design hour","quantity":10,"rate":90}],"due_date":"2026-10-24","status":"open","notify_client":true});
```

**CLI**

```bash
cotlet call suitedash create_invoice --data '{"client_id":"c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71","title":"Website design, October","items":[{"item":"Design hour","quantity":10,"rate":90}],"due_date":"2026-10-24","status":"open","notify_client":true}'
```

### Example response

```json
{
  "invoice_id": "58213",
  "invoice_number": "1042",
  "status": "open",
  "total": "900.00",
  "currency": "USD",
  "due_date": "2026-10-24",
  "payment_link": "https://yourname.suitedash.com/pay/invoice/58213"
}
```

## Record payment

`POST https://cotlet.dev/api/v1/suitedash/record_payment`

Access: write. Confirm: waits for the user's OK before it runs.

Records a manual payment on one invoice, with a Payment Type from your account and an optional note. A partial amount leaves the invoice partially paid. send_confirmation emails the standard payment confirmation to the client. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `invoice_id` | string | yes | Invoice ID from list_invoices. |
| `amount` | string | yes | Amount paid, e.g. "900.00". |
| `payment_type` | string | yes | Payment Type as named in your account, e.g. Bank Transfer. |
| `note` | string | no | Payment note. |
| `send_confirmation` | boolean | no | Email the payment confirmation. Default: false. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/record_payment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id":"58213","amount":"900.00","payment_type":"Bank Transfer","note":"Wire ref INV1042, received 12 Oct","send_confirmation":true}'
```

**Python**

```python
result = client.call("suitedash", "record_payment", {"invoice_id":"58213","amount":"900.00","payment_type":"Bank Transfer","note":"Wire ref INV1042, received 12 Oct","send_confirmation":True})
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'record_payment', {"invoice_id":"58213","amount":"900.00","payment_type":"Bank Transfer","note":"Wire ref INV1042, received 12 Oct","send_confirmation":true});
```

**CLI**

```bash
cotlet call suitedash record_payment --data '{"invoice_id":"58213","amount":"900.00","payment_type":"Bank Transfer","note":"Wire ref INV1042, received 12 Oct","send_confirmation":true}'
```

### Example response

```json
{
  "invoice_id": "58213",
  "payment_id": "pay_7710",
  "amount": "900.00",
  "payment_type": "Bank Transfer",
  "invoice_status": "paid",
  "confirmation_sent": true
}
```

## Send message

`POST https://cotlet.dev/api/v1/suitedash/send_message`

Access: write. Confirm: waits for the user's OK before it runs.

Sends a Secure Messaging message: a reply when thread_id is set, otherwise a new thread to the contacts or staff in to, with a subject. Messages go out under your name. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `to` | string[] | no | Contact UIDs or staff emails. Required for a new thread. |
| `thread_id` | string | no | Reply in this thread from list_message_threads. |
| `subject` | string | no | Subject of a new thread. |
| `body` | string | yes | Message text. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/send_message \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"thread_id":"th_3a91","body":"Hi Ana, the final logo files are scheduled for Friday 16 Oct. You will find them in your portal."}'
```

**Python**

```python
result = client.call("suitedash", "send_message", {"thread_id":"th_3a91","body":"Hi Ana, the final logo files are scheduled for Friday 16 Oct. You will find them in your portal."})
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'send_message', {"thread_id":"th_3a91","body":"Hi Ana, the final logo files are scheduled for Friday 16 Oct. You will find them in your portal."});
```

**CLI**

```bash
cotlet call suitedash send_message --data '{"thread_id":"th_3a91","body":"Hi Ana, the final logo files are scheduled for Friday 16 Oct. You will find them in your portal."}'
```

### Example response

```json
{
  "thread_id": "th_3a91",
  "message_id": "msg_5502",
  "status": "sent",
  "sent_at": "2026-10-11T09:05:00+02:00"
}
```

## Share file

`POST https://cotlet.dev/api/v1/suitedash/share_file`

Access: write. Confirm: waits for the user's OK before it runs.

Uploads one file from a URL to the dedicated Sharing Folder of one client. With notify, the client is told about the new file. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact UID from find_contact. |
| `file_url` | string | yes | Public or signed URL of the file to upload. |
| `notify` | boolean | no | Notify the contact about the new file. Default: true. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/suitedash/share_file \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_id":"contact_8c41d2","file_url":"https://example.com"}'
```

**Python**

```python
result = client.call("suitedash", "share_file", {"contact_id":"contact_8c41d2","file_url":"https://example.com"})
```

**Node.js**

```js
const result = await cotlet.call('suitedash', 'share_file', {"contact_id":"contact_8c41d2","file_url":"https://example.com"});
```

**CLI**

```bash
cotlet call suitedash share_file --data '{"contact_id":"contact_8c41d2","file_url":"https://example.com"}'
```

### Example response

```json
{
  "contact_id": "c7f2a9e1-4b3d-4e8a-9f10-2d6b5a8c3e71",
  "file_name": "acme-logo-final.zip",
  "status": "shared",
  "notified": true
}
```