REST API integration

The REST API is VGraple CRM's public interface for your own code: create and update contacts, create leads in a pipeline, send approved WhatsApp templates, list messages, subscribe to events and create broadcasts, all from a script, a backend or a low-code tool. It is native and first-party: the same API the Zapier app is built on, authenticated with an API key you create in Settings.

What syncs

Setup

1. Go to Settings, then API Keys, click Create key, name it and copy the secret once. Owners only.
2. Call GET https://crm.vgraple.co.in/api/v1/me with Authorization: Bearer <key> to confirm the key and see the organisation.
3. Create or update a contact with POST /api/v1/contacts (phone in international format, name, tags, custom fields).
4. List approved templates with GET /api/v1/templates, then send one with POST /api/v1/messages giving the template name, language and variables.
5. Subscribe to events with POST /api/v1/hooks (URL plus event names) and verify the X-Signature-256 header with your endpoint secret.
6. Read the full request and response examples in the REST API quickstart.

Who uses it

Businesses with a system of record that is not VGraple CRM: an ERP, a school management system, a hospital information system, a custom e-commerce backend, a billing tool. The typical first integration is one-way (send a template when something happens in your system) and the second is event-driven (react to WhatsApp replies through webhooks).

Authentication and keys

Keys are created under Settings, API Keys by the workspace owner, shown once, stored hashed, and can be named, rotated and revoked individually. Every request carries Authorization: Bearer <key>. A revoked key returns 401 immediately; a rate-limited key returns 429 with the reset time. Keys are scoped to the workspace, not to a user, so actions performed through the API are attributed to the key's name in the audit log.

Error handling

Errors return JSON with a machine-readable code and a plain-language message. Template sends that fail at Meta return Meta's error code (for example 131049 for the per-user marketing cap or 131047 for a closed window) together with an explanation and, where relevant, a retry hint. Validation failures name the field. The quickstart lists the common responses and the troubleshooting articles cover each Meta code in depth.

Idempotency and limits

Contact creation is an upsert by phone number, so repeating a request is safe. Lead creation is not idempotent; include your own external reference in a custom field and check with GET before creating if duplicates matter. The rolling limit of 600 requests per hour per key is generous for event-driven use; for bulk imports use the CSV importer in the app rather than one call per row.

Three recipes

• Your billing system marks an invoice overdue -> POST /messages sends the "payment reminder" utility template with the amount and link.
• Your website checkout completes -> POST /contacts upserts the buyer with tags -> POST /leads creates a lead in the upsell pipeline -> the pipeline's automation sends the welcome template.
• Subscribe message.received via POST /hooks -> your server classifies the text -> POST /leads for anything that looks like an enquiry.

Limits and gotchas

• API keys are secrets visible to owners only; rotate from the same screen.
• 600 requests per key per hour; batch where possible.
• Template sends obey consent, messaging limits, the US marketing pause and delivery protection; errors return Meta's code and a plain explanation.
• No free-form sends through the API by design.
• API-created webhook subscriptions have a per-workspace cap noted on the Webhooks page.

The API keys guide and the webhook payload reference complete the picture.