# CRM API

Search, create and update Salesforce Contacts and Leads, log Tasks, 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 Salesforce org: the same requests work for HubSpot, so one integration covers both. Every call reads or writes Salesforce directly; Zernio stores nothing.

| Call | What it does in Salesforce |
|---|---|
| [Search contacts](/crm/search-crm-contacts) | Contacts and unconverted Leads, by text, email or phone |
| [Get](/crm/get-crm-contact), [create](/crm/create-crm-contact), [update](/crm/update-crm-contact) a contact | Contact or Lead records |
| [Log an activity](/crm/create-crm-activity) | A completed Task on the Contact or Lead |
| [List](/crm/list-crm-deals), [get](/crm/get-crm-deal), [update](/crm/update-crm-deal) deals | Opportunities, with their contact roles |
| [List owners](/crm/list-crm-owners) | Active standard users, for `ownerId` |

## Before you start

Connect Salesforce ([Connect](/platforms/salesforce/connect)) and use its account id as `accountId`. The connection's `api` scope covers every call.

The API can read and change what the connected Salesforce user can: field-level security and sharing apply.

## 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: 'LeadSource' },
});
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="LeadSource",
)
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=LeadSource" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"
```
</Tab>
</Tabs>

Results mix Contacts and Leads; `objectType` says which. `email` is an exact match. `q` and `phone` use Salesforce search, so a record saved in the last few minutes may not show yet.

## Create a Lead and log a Task

```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", "company": "Acme", "properties": { "LeadSource": "WhatsApp" } }'

curl -X POST "https://zernio.com/api/v1/crm/ACCOUNT_ID/contacts/00Q5g00000AbCdEFGH/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 new person becomes a Lead or a Contact by `createAs`, else by the connection's [`createAs` setting](/platforms/salesforce/settings). `lastName` is required on both.

A Lead without `company` gets `[not provided]`. A Contact takes its company from its Account, so set `properties.AccountId` instead.

The activity is a completed Task with `WhoId` set to the person, dated `occurredAt`, with the text in its comments. Its subject defaults to the channel and direction, for example `WhatsApp activity (inbound)`.

## Move an Opportunity

```bash
curl -X PATCH "https://zernio.com/api/v1/crm/ACCOUNT_ID/deals/0065g00000XyZaBCDE" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "Closed Won", "amount": 4800, "closeDate": "2026-11-30" }'
```

`stage` is the `StageName` picklist value. `contactIds` lists the Opportunity's contact roles, primary first.

## Platform fields

| Unified field | Salesforce field |
|---|---|
| `firstName`, `lastName`, `email`, `phone`, `ownerId` | `FirstName`, `LastName`, `Email`, `Phone` (else `MobilePhone` on reads), `OwnerId` |
| `company` | Lead `Company`; on a Contact, its Account name (read only) |
| Deal `name`, `stage`, `amount`, `currency`, `closeDate` | `Name`, `StageName`, `Amount`, `CurrencyIsoCode` (multi-currency orgs; else the org currency), `CloseDate` |

Any other field goes in `properties` by API name (`Industry__c`), up to 50 per request.

## If it fails

| Code | Status | What Salesforce said |
|---|---|---|
| `crm_validation_failed` | 422 | A validation rule, a required field, a bad picklist value or an unknown field. `details.errors` holds Salesforce's own `FIELD_CUSTOM_VALIDATION_EXCEPTION`, `REQUIRED_FIELD_MISSING` and similar, with the fields. |
| `crm_access_denied` | 403 | The connected user cannot see or edit the record or field. |
| `crm_duplicate_record` | 409 | A duplicate rule blocked the create; `details.existingId` is the match. |
| `crm_record_not_found` | 404 | No record with this id, or an id of another object. |
| `rate_limited` | 429 | The org's API budget, shared with the conversation sync, is spent for now. Wait for `Retry-After`. |

## Related

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