Docs

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:

  1. The key carries the scope, such as crm:write:leads, chosen when the key was made.
  2. 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, sortOrder and updatedSince (ISO date: only what changed since your last sync), and answer { success, data, pagination: { page, limit, total, pages, hasMore } }.
  • Send an Idempotency-Key header on a POST and 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

EndpointScopeOwner needsDoes
GET/crm/leadscrm:read:leadscrm.leads.viewList. Filters: status, source, priority, ownerId, tags
POST/crm/leadscrm:write:leadscrm.leads.createCreate, or return the lead already there
GET/crm/leads/:idcrm:read:leadscrm.leads.viewOne lead, with its notes
PATCH/crm/leads/:idcrm:write:leadscrm.leads.editChange details or status
DELETE/crm/leads/:idcrm:delete:leadscrm.leads.deleteDelete
POST/crm/leads/:id/notescrm:write:leadscrm.leads.editAdd a note
PUT/crm/leads/:id/ownercrm:write:leadscrm.leads.assignHand the lead to an employee
POST/crm/leads/:id/convertcrm:write:leadscrm.leads.convertTurn 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

  • PATCH takes the same fields as create. status may be new, contacted, qualified or lost.
  • PUT /owner takes { "ownerId": "..." }, an active employee of the branch.
  • POST /convert takes an optional customerType (individual, business, government, non-profit) and businessInfo, and answers { "lead": {...}, "customer": {...} }.

Customers

EndpointScopeOwner needsDoes
GET/crm/customerscrm:read:customerscrm.customers.viewList. Filters: type, status, ownerId, tags
POST/crm/customerscrm:write:customerscrm.customers.createCreate
GET/crm/customers/:idcrm:read:customerscrm.customers.viewOne customer
PATCH/crm/customers/:idcrm:write:customerscrm.customers.editChange details or owner
DELETE/crm/customers/:idcrm:delete:customerscrm.customers.deleteDelete
POST/crm/customers/:id/interactionscrm:write:customerscrm.customers.editLog 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

EndpointScopeOwner needsDoes
GET/crm/dealscrm:read:dealscrm.deals.viewList. Filters: stage, outcome, ownerId, customerId, tags
GET/crm/deals/pipelinecrm:read:dealscrm.pipeline.viewCount and value per stage
POST/crm/dealscrm:write:dealscrm.deals.createOpen a deal
GET/crm/deals/:idcrm:read:dealscrm.deals.viewOne deal, with its stage history
PATCH/crm/deals/:idcrm:write:dealscrm.deals.editChange details
PUT/crm/deals/:id/stagecrm:write:dealscrm.deals.editMove to another stage
POST/crm/deals/:id/wincrm:write:dealscrm.deals.editMark won (optional notes)
POST/crm/deals/:id/losecrm:write:dealscrm.deals.editMark lost (optional reason)
DELETE/crm/deals/:idcrm:delete:dealscrm.deals.deleteDelete

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.

No accounting through the API. Winning a deal here never books a receivable, and 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

EndpointScopeOwner needsDoes
GET/crm/activitiescrm:read:activitiescrm.activities.viewList. Filters: type, status, entityType, entityId
POST/crm/activitiescrm:write:activitiescrm.activities.createLog or schedule one
GET/crm/activities/:idcrm:read:activitiescrm.activities.viewOne activity
PATCH/crm/activities/:idcrm:write:activitiescrm.activities.editChange it
POST/crm/activities/:id/completecrm:write:activitiescrm.activities.completeMark it done
DELETE/crm/activities/:idcrm:delete:activitiescrm.activities.deleteDelete
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)

EndpointScopeOwner needsDoes
GET/crm/campaignscrm:read:campaignscrm.campaigns.viewList. Filters: status, search
GET/crm/campaigns/:idcrm:read:campaignscrm.campaigns.viewOne 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 API
crm.lead.updated A lead's details changed
crm.lead.status_changed An update set the lead's status
crm.lead.assigned A lead was given an owner
crm.lead.converted A lead became a customer (carries both)
crm.lead.deleted A lead was deleted
crm.customer.created A customer was added
crm.customer.updated A customer's details changed
crm.customer.status_changed Active, at risk, churned or reactivated
crm.customer.deleted A customer was deleted
crm.deal.created A deal was opened
crm.deal.updated A deal's details changed
crm.deal.stage_changed A deal moved stage
crm.deal.won A deal was won
crm.deal.lost A deal was lost
crm.deal.deleted A deal was deleted
crm.activity.created A call, email, meeting or note was logged
crm.activity.completed A scheduled activity was marked done

Not 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.