# MarketSharp API

> Every MarketSharp 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/marketsharp

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 MarketSharp. Each one is a POST with a JSON body, called with your API key.

- Base URL: `https://cotlet.dev/api/v1/marketsharp`
- Connects with: Your own MarketSharp user account (a role that can see and edit the contacts, appointments and jobs you use)
- Integration page: https://cotlet.dev/integrations/marketsharp-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `search_contacts` | read | Find prospects, leads and customers by name, phone, email or address, like Quick Find. |
| `get_contact` | read | Full contact record: phones, addresses, inquiries, appointments, jobs, notes and open activities. |
| `list_appointments` | read | Sales appointments in a date range with contact, salesperson, set by and Appt Result. |
| `list_jobs` | read | Jobs with job number, customer, job status, contract status, sale date and start date. |
| `get_job` | read | One job: products, contract amount and status, payments, production tasks and dates. |
| `list_activities` | read | The Activity List: to-dos for a user and date, with type, contact and due date. |
| `create_lead` | write | New lead with contact details and an inquiry, optionally with a sales appointment. |
| `schedule_appointment` | write | Add a sales appointment to a contact's inquiry; it appears on the Sales Calendar. |
| `result_appointment` | write | Set the Appt Result after the visit. A result marked Sold converts the lead to a customer. |
| `add_note` | write | Add a note to the Notes tab of a contact. |
| `add_activity` | write | Add a follow-up activity to a contact and assign it to a user. |
| `complete_activity` | write | Mark an activity as completed, with an activity result. |
| `update_job_status` | write | Change a job's Job Status or Contract Status, for example to Canceled. |
| `issue_appointments` | write | Email and issue appointments to the assigned salespeople, using one of your Issue Appointment templates. |

## Search contacts

`POST https://cotlet.dev/api/v1/marketsharp/search_contacts`

Access: read.

Searches your MarketSharp contacts the way Quick Find does and returns the best matches first. Use contact_id from each item in get_contact and the write tools. Pages hold up to 100 contacts.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Name, phone, email or address. |
| `contact_type` | enum | no | prospect, lead, customer or all. Default: all. |
| `limit` | integer | no | 1 to 100. Default: 25. |

### Request

**cURL**

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

**Python**

```python
result = client.call("marketsharp", "search_contacts", {"query":"query"})
```

**Node.js**

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

**CLI**

```bash
cotlet call marketsharp search_contacts --data '{"query":"query"}'
```

### Example response

```json
{
  "contacts": [
    {
      "contact_id": "3e9b1d44-0c27-4f5a-8e13-6a2b9c0d7f58",
      "name": "Dana Miller",
      "contact_type": "lead",
      "phone": "555-0142",
      "address": "12 Oak Lane, Springfield, IL 62704"
    }
  ]
}
```

## Get contact

`POST https://cotlet.dev/api/v1/marketsharp/get_contact`

Access: read.

Returns one contact with its phones, addresses, inquiries, appointments, jobs, notes and open activities. Use it before writing, so your agent sees what is already there. IDs in the result feed the other tools.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact ID from search_contacts. |

### Request

**cURL**

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

**Python**

```python
result = client.call("marketsharp", "get_contact", {"contact_id":"contact_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'get_contact', {"contact_id":"contact_8c41d2"});
```

**CLI**

```bash
cotlet call marketsharp get_contact --data '{"contact_id":"contact_8c41d2"}'
```

### Example response

```json
{
  "contact_id": "3e9b1d44-0c27-4f5a-8e13-6a2b9c0d7f58",
  "name": "Dana Miller",
  "contact_type": "lead",
  "inquiries": [
    {
      "inquiry_id": "i_204",
      "product": "Kitchen"
    }
  ],
  "appointments": [
    {
      "appointment_id": "a7f3c2e1-5b8d-4e0a-9c61-2d4f8b7e1a90",
      "starts_at": "2026-10-15T10:00:00-05:00",
      "result": null
    }
  ],
  "jobs": [],
  "notes": [],
  "open_activities": []
}
```

## List appointments

`POST https://cotlet.dev/api/v1/marketsharp/list_appointments`

Access: read.

Lists sales appointments between two dates, earliest first. Set unresulted_only to see the visits that still need an Appt Result. Result is empty until someone sets it.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | date | yes | First appointment date. |
| `to` | date | yes | Last appointment date. |
| `salesperson` | string | no | MarketSharp username of the salesperson. |
| `unresulted_only` | boolean | no | Only appointments with no Appt Result yet. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/marketsharp/list_appointments \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"2026-10-01","to":"2026-10-01"}'
```

**Python**

```python
result = client.call("marketsharp", "list_appointments", {"from":"2026-10-01","to":"2026-10-01"})
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'list_appointments', {"from":"2026-10-01","to":"2026-10-01"});
```

**CLI**

```bash
cotlet call marketsharp list_appointments --data '{"from":"2026-10-01","to":"2026-10-01"}'
```

### Example response

```json
{
  "appointments": [
    {
      "appointment_id": "a7f3c2e1-5b8d-4e0a-9c61-2d4f8b7e1a90",
      "contact": "Dana Miller",
      "salesperson": "jsmith",
      "set_by": "frontdesk",
      "starts_at": "2026-10-08T10:00:00-05:00",
      "result": null
    }
  ]
}
```

## List jobs

`POST https://cotlet.dev/api/v1/marketsharp/list_jobs`

Access: read.

Lists jobs, newest sale first, with job number, customer, Job Status, Contract Status, sale date and start date. Filter by sale date or by one of your own Job Status values. Pages hold up to 200 jobs.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `sold_from` | date | no | Only jobs sold on or after this date. |
| `sold_to` | date | no | Only jobs sold on or before this date. |
| `job_status` | string | no | One of your company's Job Status values. |
| `limit` | integer | no | 1 to 200. Default: 50. |

### Request

**cURL**

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

**Python**

```python
result = client.call("marketsharp", "list_jobs")
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'list_jobs');
```

**CLI**

```bash
cotlet call marketsharp list_jobs
```

### Example response

```json
{
  "jobs": [
    {
      "job_id": "j_5531",
      "job_number": "1042",
      "customer": "Dana Miller",
      "job_status": "Sold",
      "contract_status": "Signed",
      "sold_on": "2026-10-08",
      "start_date": "2026-11-02"
    }
  ]
}
```

## Get job

`POST https://cotlet.dev/api/v1/marketsharp/get_job`

Access: read.

Returns one job with its products, contract amount and status, payments, production tasks and dates. Use it when the list is not enough.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `job_id` | string | yes | Job ID from list_jobs or get_contact. |

### Request

**cURL**

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

**Python**

```python
result = client.call("marketsharp", "get_job", {"job_id":"job_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'get_job', {"job_id":"job_8c41d2"});
```

**CLI**

```bash
cotlet call marketsharp get_job --data '{"job_id":"job_8c41d2"}'
```

### Example response

```json
{
  "job_id": "j_5531",
  "job_number": "1042",
  "customer": "Dana Miller",
  "products": [
    "Kitchen"
  ],
  "contract": {
    "amount": 18500,
    "currency": "USD",
    "status": "Signed"
  },
  "payments": [
    {
      "amount": 5000,
      "received_on": "2026-10-08"
    }
  ],
  "start_date": "2026-11-02"
}
```

## List activities

`POST https://cotlet.dev/api/v1/marketsharp/list_activities`

Access: read.

Returns the Activity List for one user and day: type, contact, reference and due date. Open activities only, unless include_completed is set. Use activity_id with complete_activity.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `assigned_to` | string | no | MarketSharp username. Default: you. |
| `date` | date | no | Day to list. Default: today. |
| `activity_type` | string | no | One of your Activity Types, e.g. a call. |
| `include_completed` | boolean | no | Also return completed activities. Default: false. |

### Request

**cURL**

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

**Python**

```python
result = client.call("marketsharp", "list_activities")
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'list_activities');
```

**CLI**

```bash
cotlet call marketsharp list_activities
```

### Example response

```json
{
  "activities": [
    {
      "activity_id": "act_881",
      "activity_type": "Call",
      "contact": "Dana Miller",
      "reference": "Follow up on kitchen quote",
      "due_at": "2026-10-14T09:00:00-05:00",
      "completed": false
    }
  ]
}
```

## Create lead

`POST https://cotlet.dev/api/v1/marketsharp/create_lead`

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

Creates a lead with an inquiry in your MarketSharp account. A first name, a last name, and an email or a phone number are required. With appointment_at set, a sales appointment is added to the Sales Calendar. Source and product values must exist in your lists. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `first_name` | string | yes | Up to 50 characters. |
| `last_name` | string | yes | Up to 50 characters. |
| `email` | string | no | Email or a phone number is required. |
| `phone` | string | no | Home or cell phone. |
| `address` | object | no | address1, city, state, zip. |
| `primary_source` | string | no | One of your existing primary lead sources. |
| `product_interests` | string[] | no | Product types from your MarketSharp list. |
| `inquiry_notes` | string | no | Added to the inquiry notes. |
| `appointment_at` | datetime | no | Book a sales appointment at this time. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/marketsharp/create_lead \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Dana","last_name":"Miller","phone":"555-0142","primary_source":"Website","product_interests":["Kitchen"],"inquiry_notes":"Wants a quote for a kitchen remodel, prefers mornings."}'
```

**Python**

```python
result = client.call("marketsharp", "create_lead", {"first_name":"Dana","last_name":"Miller","phone":"555-0142","primary_source":"Website","product_interests":["Kitchen"],"inquiry_notes":"Wants a quote for a kitchen remodel, prefers mornings."})
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'create_lead', {"first_name":"Dana","last_name":"Miller","phone":"555-0142","primary_source":"Website","product_interests":["Kitchen"],"inquiry_notes":"Wants a quote for a kitchen remodel, prefers mornings."});
```

**CLI**

```bash
cotlet call marketsharp create_lead --data '{"first_name":"Dana","last_name":"Miller","phone":"555-0142","primary_source":"Website","product_interests":["Kitchen"],"inquiry_notes":"Wants a quote for a kitchen remodel, prefers mornings."}'
```

### Example response

```json
{
  "contact_id": "3e9b1d44-0c27-4f5a-8e13-6a2b9c0d7f58",
  "inquiry_id": "i_204",
  "appointment_id": "a7f3c2e1-5b8d-4e0a-9c61-2d4f8b7e1a90",
  "contact_type": "lead",
  "status": "created"
}
```

## Schedule appointment

`POST https://cotlet.dev/api/v1/marketsharp/schedule_appointment`

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

Adds a sales appointment to an inquiry, the latest one unless inquiry_id is set. It appears on the Sales Calendar for the chosen salesperson. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact ID from search_contacts. |
| `inquiry_id` | string | no | Inquiry to attach it to. Default: the latest one. |
| `starts_at` | datetime | yes | ISO 8601 with time zone. |
| `salesperson` | string | no | MarketSharp username of the salesperson. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/marketsharp/schedule_appointment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_id":"contact_8c41d2","starts_at":"2026-10-01T09:00:00Z"}'
```

**Python**

```python
result = client.call("marketsharp", "schedule_appointment", {"contact_id":"contact_8c41d2","starts_at":"2026-10-01T09:00:00Z"})
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'schedule_appointment', {"contact_id":"contact_8c41d2","starts_at":"2026-10-01T09:00:00Z"});
```

**CLI**

```bash
cotlet call marketsharp schedule_appointment --data '{"contact_id":"contact_8c41d2","starts_at":"2026-10-01T09:00:00Z"}'
```

### Example response

```json
{
  "appointment_id": "a7f3c2e1-5b8d-4e0a-9c61-2d4f8b7e1a90",
  "contact_id": "3e9b1d44-0c27-4f5a-8e13-6a2b9c0d7f58",
  "starts_at": "2026-10-15T10:00:00-05:00",
  "salesperson": "jsmith",
  "status": "scheduled"
}
```

## Result appointment

`POST https://cotlet.dev/api/v1/marketsharp/result_appointment`

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

Sets the Appt Result of one appointment to one of your company's own options. A result marked Sold converts the lead to a customer, and the response says what to do next. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `appointment_id` | string | yes | Appointment ID from get_contact or list_appointments. |
| `result` | string | yes | One of your company's Appt Result options. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/marketsharp/result_appointment \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"appointment_id":"a7f3c2e1-5b8d-4e0a-9c61-2d4f8b7e1a90","result":"Sold"}'
```

**Python**

```python
result = client.call("marketsharp", "result_appointment", {"appointment_id":"a7f3c2e1-5b8d-4e0a-9c61-2d4f8b7e1a90","result":"Sold"})
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'result_appointment', {"appointment_id":"a7f3c2e1-5b8d-4e0a-9c61-2d4f8b7e1a90","result":"Sold"});
```

**CLI**

```bash
cotlet call marketsharp result_appointment --data '{"appointment_id":"a7f3c2e1-5b8d-4e0a-9c61-2d4f8b7e1a90","result":"Sold"}'
```

### Example response

```json
{
  "appointment_id": "a7f3c2e1-5b8d-4e0a-9c61-2d4f8b7e1a90",
  "contact_id": "3e9b1d44-0c27-4f5a-8e13-6a2b9c0d7f58",
  "result": "Sold",
  "sold": true,
  "contact_type": "customer",
  "next_step": "Create a job for this customer"
}
```

## Add note

`POST https://cotlet.dev/api/v1/marketsharp/add_note`

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

Adds a note to the Notes tab of one contact, under your name. There is no tool to delete a note, so each call asks first. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact ID from search_contacts. |
| `text` | string | yes | Note text. |

### Request

**cURL**

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

**Python**

```python
result = client.call("marketsharp", "add_note", {"contact_id":"contact_8c41d2","text":"text"})
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'add_note', {"contact_id":"contact_8c41d2","text":"text"});
```

**CLI**

```bash
cotlet call marketsharp add_note --data '{"contact_id":"contact_8c41d2","text":"text"}'
```

### Example response

```json
{
  "note_id": "n_3302",
  "contact_id": "3e9b1d44-0c27-4f5a-8e13-6a2b9c0d7f58",
  "status": "added"
}
```

## Add activity

`POST https://cotlet.dev/api/v1/marketsharp/add_activity`

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

Adds an activity of one of your Activity Types to a contact and assigns it to a user, who sees it in the Activity List. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | yes | Contact ID from search_contacts. |
| `activity_type` | string | yes | One of your Activity Types. |
| `assigned_to` | string | no | MarketSharp username. Default: you. |
| `due_at` | datetime | no | When the activity is due. |
| `reference` | string | no | Short description shown in the Activity List. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/marketsharp/add_activity \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_id":"contact_8c41d2","activity_type":"activity type"}'
```

**Python**

```python
result = client.call("marketsharp", "add_activity", {"contact_id":"contact_8c41d2","activity_type":"activity type"})
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'add_activity', {"contact_id":"contact_8c41d2","activity_type":"activity type"});
```

**CLI**

```bash
cotlet call marketsharp add_activity --data '{"contact_id":"contact_8c41d2","activity_type":"activity type"}'
```

### Example response

```json
{
  "activity_id": "act_881",
  "contact_id": "3e9b1d44-0c27-4f5a-8e13-6a2b9c0d7f58",
  "activity_type": "Call",
  "assigned_to": "jsmith",
  "due_at": "2026-10-14T09:00:00-05:00",
  "status": "added"
}
```

## Complete activity

`POST https://cotlet.dev/api/v1/marketsharp/complete_activity`

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

Marks one activity as completed and records one of your activity results. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `activity_id` | string | yes | Activity ID from list_activities or get_contact. |
| `result` | string | no | One of your activity results. |

### Request

**cURL**

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

**Python**

```python
result = client.call("marketsharp", "complete_activity", {"activity_id":"activity_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'complete_activity', {"activity_id":"activity_8c41d2"});
```

**CLI**

```bash
cotlet call marketsharp complete_activity --data '{"activity_id":"activity_8c41d2"}'
```

### Example response

```json
{
  "activity_id": "act_881",
  "completed": true,
  "result": "Left voicemail"
}
```

## Update job status

`POST https://cotlet.dev/api/v1/marketsharp/update_job_status`

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

Changes the Job Status, the Contract Status or both to values from your own lists. A change like Canceled affects a customer's contract, so the call asks first. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `job_id` | string | yes | Job ID from list_jobs or get_contact. |
| `job_status` | string | no | One of your Job Status values. |
| `contract_status` | string | no | One of your Contract Status values. |

### Request

**cURL**

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

**Python**

```python
result = client.call("marketsharp", "update_job_status", {"job_id":"job_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'update_job_status', {"job_id":"job_8c41d2"});
```

**CLI**

```bash
cotlet call marketsharp update_job_status --data '{"job_id":"job_8c41d2"}'
```

### Example response

```json
{
  "job_id": "j_5531",
  "job_status": "Canceled",
  "contract_status": "Canceled",
  "status": "updated"
}
```

## Issue appointments

`POST https://cotlet.dev/api/v1/marketsharp/issue_appointments`

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

Issues the appointments you pass and emails each assigned salesperson with one of your Issue Appointment templates, or your default one. The emails reach your team. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `appointment_ids` | string[] | yes | Appointments from list_appointments. |
| `template` | string | no | Issue Appointment email template name. Default: your default template. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/marketsharp/issue_appointments \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"appointment_ids":["appointment ids"]}'
```

**Python**

```python
result = client.call("marketsharp", "issue_appointments", {"appointment_ids":["appointment ids"]})
```

**Node.js**

```js
const result = await cotlet.call('marketsharp', 'issue_appointments', {"appointment_ids":["appointment ids"]});
```

**CLI**

```bash
cotlet call marketsharp issue_appointments --data '{"appointment_ids":["appointment ids"]}'
```

### Example response

```json
{
  "issued": 1,
  "emailed_to": [
    "jsmith"
  ],
  "template": "Default",
  "status": "issued"
}
```