API reference

REST API, version 1.

Endpoints are grouped by module. Each endpoint documents its scope and availability. All requests are JSON over HTTPS and require a scoped credential.

Available Planned

Conventions

Base URL

https://connectapi.clickmaker.in/api/v1

Authorization

Bearer cmc_live_...

Tenant resolved server-side requestId on every response Cursor pagination

Response envelope

200 OK

{
  "data": {
    "id": "pn_01J8XK4T",
    "displayName": "Lumina Clinics",
    "phoneNumber": "+919820044210",
    "qualityRating": "GREEN",
    "messagingLimit": "TIER_10K",
    "status": "CONNECTED"
  },
  "requestId": "req_01J8XK4T"
}

Pagination

list

{
  "data": [ /* items */ ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "eyJpZCI6IjAxSjhYIn0"
  },
  "requestId": "req_01J8XM2"
}

Error

400

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "path": "to", "message": "Phone number must be E.164" }
    ]
  },
  "requestId": "req_01J8XM2"
}

Authentication

Browser authentication uses HttpOnly cookies with rotating refresh tokens. Machine-to-machine calls use scoped API keys.

6 endpoints

POST/auth/registerCreate a user and organizationPublicavailable

Creates a user, an organization and an initial owner membership. Returns an access token and sets refresh cookies for browser clients.

Required scope: PublicAuthentication

POST/auth/loginSign inPublicavailable

Authenticates a user and issues an access token plus an HttpOnly refresh cookie.

Required scope: PublicAuthentication

POST/auth/refreshRotate the sessionRefresh cookieavailable

Rotates the refresh token and returns a fresh access token. Reuse of a rotated token revokes the session family.

Required scope: Refresh cookieAuthentication

POST/auth/logoutRevoke the current sessionSessionavailable

Revokes the refresh token, clears cookies and records a security event.

Required scope: SessionAuthentication

POST/auth/forgot-passwordRequest a password reset codePublicavailable

Sends a time-limited verification code to the account email. Responses are intentionally generic.

Required scope: PublicAuthentication

POST/auth/reset-passwordReset a passwordPublicavailable

Consumes a valid verification code and updates the password. All other sessions may be revoked.

Required scope: PublicAuthentication

Organizations

An organization is the tenant boundary. Every WhatsApp asset, contact, message and API key belongs to exactly one organization.

4 endpoints

GET/organizationsList your organizationsorganization:readavailable

Returns organizations the authenticated user is an active member of.

Required scope: organization:readAuthentication

POST/organizationsCreate an organizationorganization:writeavailable

Creates a new tenant and makes the caller its owner.

Required scope: organization:writeAuthentication

GET/organizations/:idGet an organizationorganization:readavailable

Returns organization profile, membership and plan context for a tenant the caller belongs to.

Required scope: organization:readAuthentication

PATCH/organizations/:idUpdate an organizationorganization:writeavailable

Updates name, billing email and workspace settings. Requires an admin or owner role.

Required scope: organization:writeAuthentication

WhatsApp connections

Customers connect their own WhatsApp Business Account through Meta Embedded Signup. ClickMaker stores tokens encrypted and never returns them.

5 endpoints

GET/whatsapp/connectionsList connectionswhatsapp:readavailable

Lists WhatsApp Business Accounts connected to the organization with status, quality and messaging limits.

Required scope: whatsapp:readAuthentication

POST/whatsapp/embedded-signup/exchangeExchange an Embedded Signup codewhatsapp:writeavailable

Exchanges the authorization code, validates returned WABA and phone assets, subscribes the app to webhooks and persists the connection idempotently.

Required scope: whatsapp:writeAuthentication

GET/whatsapp/connections/:idGet a connectionwhatsapp:readavailable

Returns connection details and the phone numbers discovered under the WABA.

Required scope: whatsapp:readAuthentication

DELETE/whatsapp/connections/:idDisconnect a WABAwhatsapp:writeavailable

Revokes local access, stops processing events for the connection and records an audit entry. It does not delete the customer's Meta assets.

Required scope: whatsapp:writeAuthentication

GET/whatsapp/phone-numbersList phone numberswhatsapp:readavailable

Lists numbers synced from connected WABAs, including display name, quality rating and messaging limit.

Required scope: whatsapp:readAuthentication

Templates

Templates are owned and approved by Meta. Local creation is not approval. Always render approval state and rejection reasons.

3 endpoints

GET/whatsapp/templatesList templatestemplates:readavailable

Returns synced templates with category, language, components and Meta approval state.

Required scope: templates:readAuthentication

POST/whatsapp/templatesCreate a templatetemplates:writeavailable

Submits a template to Meta for review. The local record starts as pending and updates from the Meta event stream.

Required scope: templates:writeAuthentication

POST/whatsapp/templates/:id/syncSync template statustemplates:writeavailable

Refreshes one template from the Graph API and records a sync attempt.

Required scope: templates:writeAuthentication

Messages

Outbound messages are validated, queued and dispatched asynchronously. Status reflects Meta events, never optimistic assumptions.

4 endpoints

POST/messagesSend a messagemessages:writeavailable

Sends text, image, video, document, audio or location within the customer service window. Accepts an Idempotency-Key header.

Required scope: messages:writeAuthentication

POST/messages/templateSend a templatemessages:writeavailable

Sends an approved template with header, body and button parameters. Validates template status and variable count.

Required scope: messages:writeAuthentication

GET/messagesList messagesmessages:readavailable

Cursor-paginated message history scoped to the organization and optional phone number or conversation.

Required scope: messages:readAuthentication

GET/messages/:idGet a messagemessages:readavailable

Returns one message with its current status and event timeline.

Required scope: messages:readAuthentication

Contacts

Contacts are tenant-owned. Consent and opt-out records are enforced before any marketing send.

4 endpoints

GET/contactsList contactscontacts:readavailable

Searchable, cursor-paginated contacts with tags, opt-in state and last activity.

Required scope: contacts:readAuthentication

POST/contactsCreate a contactcontacts:writeavailable

Creates or upserts a contact with phone normalisation and consent metadata.

Required scope: contacts:writeAuthentication

PATCH/contacts/:idUpdate a contactcontacts:writeavailable

Updates profile, tags and custom attributes. Opt-out changes require an explicit source.

Required scope: contacts:writeAuthentication

DELETE/contacts/:idDelete a contactcontacts:writeavailable

Soft-deletes a contact while retaining suppression evidence where required.

Required scope: contacts:writeAuthentication

Conversations

Conversations group inbound and outbound messages with one contact and one business phone number.

4 endpoints

GET/conversationsList conversationsconversations:readavailable

Filters by status, assignee, phone number, labels and unread state.

Required scope: conversations:readAuthentication

GET/conversations/:idGet a conversationconversations:readavailable

Returns conversation metadata and a paginated message timeline.

Required scope: conversations:readAuthentication

POST/conversations/:id/assignAssign a conversationconversations:writeavailable

Assigns to a team member, or unassigns when userId is null.

Required scope: conversations:writeAuthentication

POST/conversations/:id/replyReply in a conversationconversations:writeavailable

Queues a reply, enforces the 24-hour service window and attaches the message to the thread.

Required scope: conversations:writeAuthentication

Campaigns

Campaigns are asynchronous. The HTTP request creates and schedules work; BullMQ workers perform batching, throttling and retries.

5 endpoints

GET/campaignsList campaignscampaigns:readavailable

Returns campaign status, audience size and delivery counters.

Required scope: campaigns:readAuthentication

POST/campaignsCreate a campaigncampaigns:writeavailable

Creates a draft with an approved template and an audience definition.

Required scope: campaigns:writeAuthentication

GET/campaigns/:idGet a campaigncampaigns:readavailable

Returns campaign configuration, progress and per-status analytics.

Required scope: campaigns:readAuthentication

POST/campaigns/:id/scheduleSchedule or sendcampaigns:writeavailable

Validates consent, template status and limits, then enqueues dispatch.

Required scope: campaigns:writeAuthentication

POST/campaigns/:id/cancelCancel a campaigncampaigns:writeavailable

Stops pending jobs. Already-sent messages remain sent and are not retracted.

Required scope: campaigns:writeAuthentication

Developer platform

Applications receive scoped credentials. API keys are hashed at rest and shown once at creation.

6 endpoints

GET/applicationsList applicationsapplications:readavailable

Lists applications registered by the organization with their scopes and status.

Required scope: applications:readAuthentication

POST/applicationsRegister an applicationapplications:writeavailable

Creates an application with allowed redirect URLs, scopes and webhook defaults.

Required scope: applications:writeAuthentication

GET/developer/api-keysList API keysdeveloper:readavailable

Lists key prefixes, scopes and last-used timestamps. Full secrets are never returned.

Required scope: developer:readAuthentication

POST/developer/api-keysCreate an API keydeveloper:writeavailable

Creates a scoped key and returns the secret exactly once. Store it in a secret manager.

Required scope: developer:writeAuthentication

DELETE/developer/api-keys/:idRevoke an API keydeveloper:writeavailable

Immediately revokes a key. Revocation is recorded in the audit log.

Required scope: developer:writeAuthentication

GET/developer/usageRead API usagedeveloper:readavailable

Returns request counts and message usage for the current billing period.

Required scope: developer:readAuthentication

Webhook endpoints

4 endpoints

GET/webhooksList webhook endpointswebhooks:readavailable

Returns endpoint URL, subscribed events, status and last delivery result.

Required scope: webhooks:readAuthentication

POST/webhooksRegister a webhookwebhooks:writeavailable

Creates an endpoint and returns its signing secret once.

Required scope: webhooks:writeAuthentication

PATCH/webhooks/:idUpdate a webhookwebhooks:writeavailable

Updates URL, event subscriptions or enabled state.

Required scope: webhooks:writeAuthentication

DELETE/webhooks/:idDelete a webhookwebhooks:writeavailable

Stops new deliveries and soft-deletes the endpoint.

Required scope: webhooks:writeAuthentication

Billing

Platform subscription and Meta charges are separate. Usage is metered from real API and message events.

3 endpoints

GET/billing/subscriptionGet subscriptionbilling:readavailable

Returns the current plan, status, period and limits.

Required scope: billing:readAuthentication

GET/billing/usageGet usagebilling:readavailable

Returns metered API requests, messages and webhook deliveries for a period.

Required scope: billing:readAuthentication

GET/billing/invoicesList invoicesbilling:readavailable

Returns invoice history. Online payment collection is not yet enabled; invoices are issued manually.

Required scope: billing:readAuthentication

Keep your integration honest

Custom HTTP clients and SDK examples in this documentation target the real route shapes implemented by the backend. If an endpoint is not yet deployed in your environment, it is marked planned and should not be called in production.