CRM API
Leads, customers, deals, activities and campaigns, at https://api.zyhap.com/api/v1/public/crm. Push leads in from your website, keep another system in sync with your pipeline, or log calls from your phone system.
Two checks on every request
A CRM request passes only when both hold:
- The key carries the scope, such as
crm:write:leads, chosen when the key was made. - The person who made the key holds the matching CRM permission, such as
crm.leads.create, in the branch the request acts in, today. Take a permission away from that person and the key loses it at the same moment. Company owners pass this check.
CRM data belongs to a branch. A key acts in the branch it was created in; send X-Branch-ID to act in another branch its owner works in. Records from other branches are never visible, and their ids are refused wherever you reference one.
curl https://api.zyhap.com/api/v1/public/crm/leads?status=new \ -H "X-API-Key: YOUR_API_KEY"
Conventions
- Money is minor units with its currency:
{ "value": 150000, "currencyCode": "NGN" }is ₦1,500.00. A bare number is refused, because guessing kobo or naira is how an amount ends up a hundred times too big. - Ids are strings; dates are ISO 8601 in UTC; people are
{ "id", "name" }. - Lists take
page,limit(max 100),search,sortBy,sortOrderandupdatedSince(ISO date: only what changed since your last sync), and answer{ success, data, pagination: { page, limit, total, pages, hasMore } }. - Send an
Idempotency-Keyheader on aPOSTand a retry with the same key and body returns the first answer without doing anything twice. - Deletes are soft: the record leaves every list and the app keeps its history.
- Refusals are
{ "success": false, "error": "..." }and say what to send instead.
Leads
| Endpoint | Scope | Owner needs | Does |
|---|---|---|---|
GET/crm/leads | crm:read:leads | crm.leads.view | List. Filters: status, source, priority, ownerId, tags |
POST/crm/leads | crm:write:leads | crm.leads.create | Create, or return the lead already there |
GET/crm/leads/:id | crm:read:leads | crm.leads.view | One lead, with its notes |
PATCH/crm/leads/:id | crm:write:leads | crm.leads.edit | Change details or status |
DELETE/crm/leads/:id | crm:delete:leads | crm.leads.delete | Delete |
POST/crm/leads/:id/notes | crm:write:leads | crm.leads.edit | Add a note |
PUT/crm/leads/:id/owner | crm:write:leads | crm.leads.assign | Hand the lead to an employee |
POST/crm/leads/:id/convert | crm:write:leads | crm.leads.convert | Turn it into a customer |
Create a lead
name and an email or phone are required. source is one of website, social, referral, email-campaign, trade-show, partner, walk-in, cold-call, other (the default). New leads run the same automations as a lead typed into the app.
POST /api/v1/public/crm/leads
Idempotency-Key: form-submission-8841
{
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "0803 000 0000",
"companyName": "Obi Foods",
"source": "website",
"priority": "high",
"value": { "value": 50000000, "currencyCode": "NGN" },
"tags": ["premium-plan"],
"ownerId": "665f1c2e9b1e8a0012a4b7c1",
"notes": "Asked about the premium plan"
}Duplicates are returned, not created
If a lead in the branch already has that email, or that phone number however it was typed (+234 803 000 0000 and 08030000000 are the same person), you get it back with status 200 and "duplicate": true, and nothing is created. Send "allowDuplicate": true to create a second lead anyway. A new lead answers 201 with "duplicate": false.
{
"success": true,
"duplicate": false,
"data": {
"id": "6660a1f09b1e8a0012a4b8d2",
"name": "Ada Obi",
"email": "ada@example.com",
"phone": "0803 000 0000",
"companyName": "Obi Foods",
"source": "website",
"status": "new",
"priority": "high",
"value": { "value": 50000000, "currencyCode": "NGN" },
"tags": ["premium-plan"],
"owner": { "id": "665f1c2e9b1e8a0012a4b7c1", "name": "Bola Ade" },
"assignees": [{ "id": "665f1c2e9b1e8a0012a4b7c1", "name": "Bola Ade" }],
"notes": [{ "id": "...", "content": "Asked about the premium plan", "createdBy": { "id": "...", "name": "..." }, "createdAt": "2026-09-30T09:12:00.000Z" }],
"convertedToCustomer": null,
"createdAt": "2026-09-30T09:12:00.000Z",
"updatedAt": "2026-09-30T09:12:00.000Z"
}
}Update, assign, convert
PATCHtakes the same fields as create.statusmay benew,contacted,qualifiedorlost.PUT /ownertakes{ "ownerId": "..." }, an active employee of the branch.POST /converttakes an optionalcustomerType(individual,business,government,non-profit) andbusinessInfo, and answers{ "lead": {...}, "customer": {...} }.
Customers
| Endpoint | Scope | Owner needs | Does |
|---|---|---|---|
GET/crm/customers | crm:read:customers | crm.customers.view | List. Filters: type, status, ownerId, tags |
POST/crm/customers | crm:write:customers | crm.customers.create | Create |
GET/crm/customers/:id | crm:read:customers | crm.customers.view | One customer |
PATCH/crm/customers/:id | crm:write:customers | crm.customers.edit | Change details or owner |
DELETE/crm/customers/:id | crm:delete:customers | crm.customers.delete | Delete |
POST/crm/customers/:id/interactions | crm:write:customers | crm.customers.edit | Log a call, email, meeting, SMS or note |
Fields: name, email, phone (text, or { primary, secondary }), type, businessInfo, addresses, tags, ownerId, and photo as an https link you host. A customer's status and healthScore follow its activity and cannot be set. These are CRM's relationship records; salesCustomerId links one to its billing customer in Sales when there is one.
Deals
| Endpoint | Scope | Owner needs | Does |
|---|---|---|---|
GET/crm/deals | crm:read:deals | crm.deals.view | List. Filters: stage, outcome, ownerId, customerId, tags |
GET/crm/deals/pipeline | crm:read:deals | crm.pipeline.view | Count and value per stage |
POST/crm/deals | crm:write:deals | crm.deals.create | Open a deal |
GET/crm/deals/:id | crm:read:deals | crm.deals.view | One deal, with its stage history |
PATCH/crm/deals/:id | crm:write:deals | crm.deals.edit | Change details |
PUT/crm/deals/:id/stage | crm:write:deals | crm.deals.edit | Move to another stage |
POST/crm/deals/:id/win | crm:write:deals | crm.deals.edit | Mark won (optional notes) |
POST/crm/deals/:id/lose | crm:write:deals | crm.deals.edit | Mark lost (optional reason) |
DELETE/crm/deals/:id | crm:delete:deals | crm.deals.delete | Delete |
Stages: prospecting, qualification, proposal, negotiation, closed_won, closed_lost. A new deal starts in an open stage. Fields: title (required), value, probability (0 to 100), expectedCloseDate, customerId, sourceLeadId, campaignId, contactName, contactEmail, ownerId, tags.
cancelled_after_win is refused, because it exists to reverse a finance posting. Those are decisions made in the app, where the journal choice is shown.Activities
| Endpoint | Scope | Owner needs | Does |
|---|---|---|---|
GET/crm/activities | crm:read:activities | crm.activities.view | List. Filters: type, status, entityType, entityId |
POST/crm/activities | crm:write:activities | crm.activities.create | Log or schedule one |
GET/crm/activities/:id | crm:read:activities | crm.activities.view | One activity |
PATCH/crm/activities/:id | crm:write:activities | crm.activities.edit | Change it |
POST/crm/activities/:id/complete | crm:write:activities | crm.activities.complete | Mark it done |
DELETE/crm/activities/:id | crm:delete:activities | crm.activities.delete | Delete |
POST /api/v1/public/crm/activities
{
"type": "call",
"subject": "Discovery call",
"summary": "Wants pricing for 20 seats",
"relatedTo": { "entityType": "lead", "entityId": "6660a1f09b1e8a0012a4b8d2" },
"durationMinutes": 15,
"nextFollowUpDate": "2026-10-03T10:00:00Z"
}type is call, email, meeting, sms, task or note. relatedTo.entityType is lead, customer, deal or campaign, and the record must be in the same branch.
Campaigns (read only)
| Endpoint | Scope | Owner needs | Does |
|---|---|---|---|
GET/crm/campaigns | crm:read:campaigns | crm.campaigns.view | List. Filters: status, search |
GET/crm/campaigns/:id | crm:read:campaigns | crm.campaigns.view | One campaign, with budget and spend |
Use a campaign's id as campaignId on a lead or deal to attribute it.
Webhook events
Subscribe through Webhooks. Events fire whether the change came from the app, the phone, an AI teammate or the API, and carry the record in the same shape the API returns ({ "lead": {...} }, { "deal": {...} }, or { "id": "..." } for a delete).
crm.lead.created A lead was added, by hand, an import, an AI teammate or the APIcrm.lead.updated A lead's details changedcrm.lead.status_changed An update set the lead's statuscrm.lead.assigned A lead was given an ownercrm.lead.converted A lead became a customer (carries both)crm.lead.deleted A lead was deletedcrm.customer.created A customer was addedcrm.customer.updated A customer's details changedcrm.customer.status_changed Active, at risk, churned or reactivatedcrm.customer.deleted A customer was deletedcrm.deal.created A deal was openedcrm.deal.updated A deal's details changedcrm.deal.stage_changed A deal moved stagecrm.deal.won A deal was woncrm.deal.lost A deal was lostcrm.deal.deleted A deal was deletedcrm.activity.created A call, email, meeting or note was loggedcrm.activity.completed A scheduled activity was marked doneNot in the API
- Finance postings on deals (see above).
- Tasks: CRM follow-ups live in Project Management.
- Automations, SLA rules, lead scoring, integrations, WhatsApp, campaign spend, bulk edits, merges and file uploads. These are set up by a person in the app.