CRM contacts — list, create, update, delete, bulk-action, import, segments, and stats. api.misar.io/reach/api/contacts.

Contacts are the people in your CRM. MisarReach contacts sync to the central Misar contacts store, so a contact created here is visible across the workspace.

Base URL: https://api.misar.io/reach/api · Auth: Authorization: Bearer mrk_…

Response bodies on the developer contract are open-form — the examples below show representative fields.

List contacts

GET/api/contacts

Returns a paginated list of contacts. Required scope: contacts:read.

Query parameters

pagenumberquerydefault: 1

Page number.

limitnumberquerydefault: 50

Page size (1–200).

qstringquery

Text filter over name, email, and company.

Request

curl "https://api.misar.io/reach/api/contacts?page=1&limit=50" \
  -H "Authorization: Bearer mrk_your_key_here"

200 — OK

{
  "data": [
    { "id": "uuid", "email": "priya@example.com", "firstName": "Priya", "company": "Acme", "status": "subscribed" }
  ],
  "pagination": { "total": 240, "page": 1, "limit": 50, "totalPages": 5 }
}

Create a contact

POST/api/contacts

Creates (or upserts) a single contact. Required scope: contacts:write.

Request body

emailstringbodyrequired

Contact email (unique per account).

firstNamestringbody

Given name (≤100 chars).

lastNamestringbody

Family name (≤100 chars).

phonestringbody

Phone number (≤50 chars).

companystringbody

Company name (≤150 chars).

jobTitlestringbody

Job title (≤100 chars).

statusstringbody

One of subscribed | unsubscribed | bounced | complained.

sourcestringbody

Acquisition source label (≤100 chars).

socialProfilesobjectbody

Map of linkedin, twitter, instagram, telegram, whatsapp, … (each ≤500 chars).

Request

curl -X POST https://api.misar.io/reach/api/contacts \
  -H "Authorization: Bearer mrk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "priya@example.com",
    "firstName": "Priya",
    "company": "Acme",
    "status": "subscribed"
  }'

201 — Created

{ "ok": true, "contact": { "id": "uuid", "email": "priya@example.com" } }

Get, update, delete a contact

GET/api/contacts/:id

Fetch (GET, scope contacts:read), update (PATCH, scope contacts:write), or delete (DELETE, scope contacts:write) a single contact by id.

Path parameters

idstringpathrequired

Contact UUID.

PATCH body — any subset of the create fields.

Update

curl -X PATCH https://api.misar.io/reach/api/contacts/CONTACT_ID \
  -H "Authorization: Bearer mrk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+911234567890", "socialProfiles": { "telegram": "@priya" } }'

Delete

curl -X DELETE https://api.misar.io/reach/api/contacts/CONTACT_ID \
  -H "Authorization: Bearer mrk_your_key_here"

200 — OK

{ "ok": true }

Bulk action

POST/api/contacts/bulk

Delete, unsubscribe, or resubscribe up to 500 contacts in one call. Required scope: contacts:write.

Request body

actionstringbodyrequired

One of delete | unsubscribe | resubscribe.

idsArray<string>bodyrequired

Contact UUIDs (max 500).

Request

curl -X POST https://api.misar.io/reach/api/contacts/bulk \
  -H "Authorization: Bearer mrk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "action": "unsubscribe", "ids": ["uuid1", "uuid2"] }'

201 — Applied

{ "ok": true, "affected": 2 }

Import contacts

POST/api/contacts/import

Import up to 5,000 contacts. Setting status: "subscribed" requires consent evidence — supply consent per contact or a defaultConsent for the batch. Required scope: contacts:write.

Request body

contactsArray<ContactInput>bodyrequired

Up to 5,000 rows. Each row: email (required), plus firstName, lastName, phone, company, jobTitle, status, source, socialProfiles, consent.

defaultConsentConsentEvidencebody

Consent record applied to rows that omit their own consent. See Consent.

Request

curl -X POST https://api.misar.io/reach/api/contacts/import \
  -H "Authorization: Bearer mrk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "email": "a@acme.com", "firstName": "Al", "company": "Acme" }
    ],
    "defaultConsent": { "source": "signup_form", "consentedAt": "2026-07-01T00:00:00Z" }
  }'

201 — Imported

{ "ok": true, "imported": 1, "skipped": 0 }

Segments & stats

GET/api/contacts/segments

List saved contact segments (GET /api/contacts/segments, rate-limited api tier) or aggregate counts (GET /api/contacts/stats). Required scope: contacts:read.

Stats

curl https://api.misar.io/reach/api/contacts/stats \
  -H "Authorization: Bearer mrk_your_key_here"

200 — stats

{ "total": 240, "subscribed": 210, "unsubscribed": 25, "bounced": 5 }

Status codes

Code	Meaning
`200`	Contacts / stats returned, updated, or deleted
`201`	Contact created, bulk action applied, or import accepted
`403`	Missing `contacts:read` / `contacts:write` scope
`404`	Contact not found
`422`	Validation error (e.g. subscribed status without consent)
`429`	Rate limit exceeded on `segments` — retry after `Retry-After`

See Rate limits and Errors.

Contacts API

List contacts

Create a contact

Get, update, delete a contact

Bulk action

Import contacts

Segments & stats

Status codes

On this page