# CRM API

Search, create and update HighLevel contacts, log notes, move opportunities and list users through the Zernio API.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

The [CRM API](/crm/search-crm-contacts) acts on the connected HighLevel sub-account (location). The same requests work for HubSpot and Salesforce, so one integration covers all three. Every call reads or writes HighLevel directly; Zernio stores nothing.

| Call | What it does in HighLevel |
|---|---|
| [Search contacts](/crm/search-crm-contacts) | The location's contacts, by text, email or phone |
| [Get](/crm/get-crm-contact), [create](/crm/create-crm-contact), [update](/crm/update-crm-contact) a contact | Contact records |
| [Log an activity](/crm/create-crm-activity) | A note on the contact |
| [List](/crm/list-crm-deals), [get](/crm/get-crm-deal), [update](/crm/update-crm-deal) deals | Opportunities |
| [List owners](/crm/list-crm-owners) | The location's users, for `ownerId` |

## Before you start

Connect HighLevel ([Connect](/platforms/gohighlevel/connect)) and use the sub-account's account id as `accountId`. The calls use these scopes:

- Contacts and notes: `contacts.readonly` and `contacts.write`.
- Deals: `opportunities.readonly`. Updating a deal needs `opportunities.write`, which the Zernio app does not request yet, so it answers 403 `crm_scope_missing` for now.
- Custom fields named by key: `locations/customFields.readonly`.
- Owners: `users.readonly`. A sub-account that installed the app before Zernio asked for it gets 403 `crm_scope_missing` until it reconnects.

## Find a person

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data } = await zernio.crm.searchCrmContacts({
  path: { accountId: 'ACCOUNT_ID' },
  query: { email: 'maria@example.com', properties: 'source' },
});
const person = data.contacts[0];
```
</Tab>
<Tab value="Python">
```python
from zernio import Zernio

client = Zernio()

result = client.crm.search_crm_contacts(
    account_id="ACCOUNT_ID",
    email="maria@example.com",
    properties="source",
)
person = result["contacts"][0]
```
</Tab>
<Tab value="curl">
```bash
curl "https://zernio.com/api/v1/crm/ACCOUNT_ID/contacts/search?email=maria@example.com&properties=source" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

`email` and `phone` are exact lookups (HighLevel's duplicate check), so they return at most one contact.

`q` searches the location's contacts page by page, up to 10,000 results. The first page's `limit` holds for every next page.

## Create a contact and log a note

```bash
curl -X POST "https://zernio.com/api/v1/crm/ACCOUNT_ID/contacts" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Maria", "lastName": "Garcia", "email": "maria@example.com", "properties": { "source": "WhatsApp", "lead_score": 7 } }'

curl -X POST "https://zernio.com/api/v1/crm/ACCOUNT_ID/contacts/seD4PfOuKoVMLkEZqohJ/activities" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Asked for the annual plan price.", "channel": "whatsapp", "direction": "inbound" }'
```

A location that does not allow duplicate contacts answers 409 `crm_duplicate_record`, with the existing contact in `details.existingId`.

The activity is a plain-text note. HighLevel dates a note when it is logged, so its first line carries the subject (or channel), the direction and `occurredAt` when you send one, for example `WhatsApp (inbound)`.

## Move an opportunity

```bash
curl -X PATCH "https://zernio.com/api/v1/crm/ACCOUNT_ID/deals/yWQobCRIhRguQtD2llvk" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "e93ba61a-53b3-45e7-985a-c7732dbcdb69", "amount": 4800, "properties": { "status": "won" } }'
```

`stage` is the pipeline stage id. `properties.status` (`open`, `won`, `lost`, `abandoned`) marks the opportunity won or lost; read it back with `properties=status`. `contactIds` holds the opportunity's contact, and `url` opens that contact's record.

Opportunities have no close date or currency of their own, so `closeDate` and `currency` answer 400.

Listing deals filters by `stage` but not by update time: `updatedSince` answers 400, and deals come in HighLevel's own order.

## Platform fields

| Unified field | HighLevel field |
|---|---|
| `firstName`, `lastName`, `email`, `phone`, `company`, `ownerId` | `firstName`, `lastName`, `email`, `phone`, `companyName`, `assignedTo` |
| Deal `name`, `stage`, `amount`, `ownerId` | `name`, `pipelineStageId`, `monetaryValue`, `assignedTo` |
| Deal `currency`, `closeDate` | Always `null` |

Any other field goes in `properties`, up to 50 per request:

- A field of the record (`source`, `city`, `website`, an opportunity's `status` or `pipelineId`) is sent as is.
- Any other name is a custom field: its id (20 characters, such as `MgobCB14YMVKuE4Ka8p1`) or its key (`lead_score`).
- Reads return custom fields under the name you asked for, id or key.

## If it fails

| Code | Status | What HighLevel said |
|---|---|---|
| `crm_validation_failed` | 422 | HighLevel refused a value or an unknown field. `details.errors` holds its own messages. |
| `crm_scope_missing` | 403 | The install did not grant the scope in `details.scope`. Reconnect HighLevel and approve it. |
| `crm_access_denied` | 403 | HighLevel refused the location's token for this record. |
| `crm_duplicate_record` | 409 | The location does not allow duplicate contacts; `details.existingId` is the match. |
| `crm_record_not_found` | 404 | No record with this id in the location. |
| `rate_limited` | 429 | The location's HighLevel API budget is spent for now. Wait for `Retry-After`. |

## Related

- [Search CRM contacts](/crm/search-crm-contacts)
- [HighLevel settings](/platforms/gohighlevel/settings)
- [HubSpot CRM API](/platforms/hubspot/crm-api)
- [Salesforce CRM API](/platforms/salesforce/crm-api)