External API

The External API (the partner API) lets your own systems drive RateUp: create contacts, fill contact groups, launch campaigns, send WhatsApp templates, run a loyalty till and read survey responses. It is a REST API over HTTPS with JSON bodies, authenticated with an API key you create in Settings → Integrations → API Service.

Two VersionsCopy Anchor Link

A key works on its own version only. Calling v2 with a v1 key, or v1 with a v2 key, answers 401 with a message naming the right base URL — This is a v1 key; it works on /api/external/v1/{orgId} or This is a v2 key; it works on /api/external/v2.

Both versions get the same security: keys are checked against their own organisation, feature limits are enforced, and every write accepts an Idempotency-Key.

Keys and AccessCopy Anchor Link

Keys are created and managed in Settings → Integrations → API Service — see Integrations → API Service for the screen itself. In short:

An organisation can hold 20 keys. Use one per integration, so you can rotate or revoke one without touching the others. The full key is shown once, when it is created or rotated — RateUp stores only a hash of it.

Live and test keysCopy Anchor Link

A test key (rk_test_…) works like a live one against your real data, but is refused on every route that sends a paid WhatsApp message:

• POST /wa/templates/send, POST /wa/templates/send-with-file and POST /wa/templates/{templateId}/send/contacts
• POST /campaigns/{campaignId}/send
• POST /loyalty/members/card/send

There the answer is 403 test_key_not_allowed — "Test keys cannot send WhatsApp messages; use a live key". Everything else, including contact writes and loyalty points, really happens with a test key: test mode is about not spending money, not a sandbox.

Limiting a key to featuresCopy Anchor Link

A key with Full access can call every endpoint, including ones added later. A key limited to Only selected features can call only the endpoints in those features:

POST /wa/templates/{templateId}/send/contacts is open to a key with either WhatsApp messaging or Campaigns.

Webchat widget is for the key you put in the support widget. That key ships in your web page, so anyone can read it: a key with only Webchat widget opens no endpoint here, and the widget refuses a key limited to other features (403 — "This API key cannot run the webchat widget"). A Full access key still runs the widget.

A call outside the key's features answers 403 insufficient_scope, with the missing permission in details.permission:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key lacks the campaigns.send scope",
    "details": { "permission": "campaigns.send" },
    "requestId": "req-1x9k"
  }
}

A key created before features existed may have been limited to individual permissions; the keys table shows it as Custom permissions until you edit and save it.

Rotating and revokingCopy Anchor Link

A key that has already been rotated cannot be rotated again — rotate its replacement. An expired key cannot be rotated; create a new one.

AuthenticateCopy Anchor Link

Send the key as a bearer token on every request:

curl "https://api.rateup.app/api/external/v2/loyalty/ping" \
  -H "Authorization: Bearer $RATEUP_API_KEY"

There is no session and no refresh. A key is valid until it expires, is rotated out or is revoked.

How Every Request BehavesCopy Anchor Link

ErrorsCopy Anchor Link

Every v2 error has the same envelope:

{
  "error": {
    "code": "insufficient_points",
    "message": "Insufficient points. Required: 500, Available: 320",
    "details": { "required": 500, "available": 320 },
    "requestId": "req-3b"
  }
}

Branch on code, show message to a person, and quote requestId when you contact support. The HTTP status means what it says: a 4xx is something about your request or the organisation's state, a 5xx is RateUp's problem.

PaginationCopy Anchor Link

v2 lists are cursor-paged, newest first:

curl "https://api.rateup.app/api/external/v2/contacts?limit=100" \
  -H "Authorization: Bearer $RATEUP_API_KEY"

{ "data": [ … ], "nextCursor": "MjAyNi0xMC0xNlQwOToz…" }

Rows created while you page neither repeat nor go missing.

Retries and the Idempotency-Key headerCopy Anchor Link

Every write (POST, PUT, PATCH, DELETE) accepts an optional Idempotency-Key header. It is your choice per request:

• With a key, the first answer is stored for 24 hours. Sending the same key and the same body again returns that stored answer with the header Idempotent-Replay: true, and nothing is done twice.
• Without a key, the request simply runs. A retry runs again.

Keys are scoped per organisation and per endpoint. For loyalty awards the key is also written to the points ledger, so an award with a reused key comes back with replayed: true and the balance untouched — and you can look a lost write up with GET /loyalty/points/transactions?idempotencyKey=….

Phone numbersCopy Anchor Link

v2 phone numbers are digits with the country code and no + — "919876543210", the same shape v1 uses. Send them as a string or as a JSON number (919876543210). A leading + and spaces, brackets, dots or dashes are tolerated and stripped, so "+91 98765-43210" also works. A number without its country code is refused with 400 validation_failed.

Every response carries phones the same way: digits only, country code first, no +.

Loyalty endpoints are more forgiving: a member's phone may also be local to the programme's country (9876543210 on an Indian programme). Digits are read as including a country code first, and as a local number only when that is not a valid number.

Rate limitsCopy Anchor Link

Over a limit the answer is 429 rate_limited. The limits on sends and enrolments fail closed: if RateUp cannot check them, the request is refused with 503 rather than let through. Back off and retry — with the same Idempotency-Key.

Plan requirementsCopy Anchor Link

Campaign endpoints need a subscription that includes WhatsApp campaigns, and loyalty endpoints a subscription with loyalty; otherwise 403 subscription_required. An expired subscription blocks writes with 403 subscription_expired; reads keep working. Loyalty writes also need the programme to be active (422 program_not_active).

v2 EndpointsCopy Anchor Link

All paths below are relative to https://api.rateup.app/api/external/v2.

ContactsCopy Anchor Link

Feature: Contacts.

Create a contact

curl -X POST "https://api.rateup.app/api/external/v2/contacts" \
  -H "Authorization: Bearer $RATEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "919876543210",
    "name": "Priya Shah",
    "email": "[email protected]",
    "externalId": "crm-4821",
    "customFields": { "city": "Pune" },
    "labels": ["7a1c2e4b-0d3f-4b8e-9a51-2f6d8c3e1b07"]
  }'

{
  "id": "3f6c1d2a-8b4e-4f0a-9c7d-1e2b3a4c5d6e",
  "name": "Priya Shah",
  "phone": "919876543210",
  "email": "[email protected]",
  "externalId": "crm-4821",
  "source": "external",
  "consent": true,
  "labels": [{ "id": "7a1c2e4b-0d3f-4b8e-9a51-2f6d8c3e1b07", "name": "VIP" }],
  "customFields": { "city": "Pune" },
  "createdAt": "2026-10-16T09:30:00.000Z"
}

A phone or externalId already in use answers 409 contact_already_exists with details.contactId and details.field, so a retried create is harmless.

On PATCH, customFields merge into the contact's values (send null for a field to remove it), labels replace the contact's labels ([] removes them all), and email or externalId set to null clears them.

POST /contacts/bulk takes { "contacts": [ … ] } and always answers 200:

{
  "created": [ { "id": "…", "phone": "919876543210", … } ],
  "skipped": [ { "index": 3, "phone": "919812345678", "reason": "already_exists" } ]
}

reason is already_exists or duplicate_in_request; index is the row's position in your array.

Contact groupsCopy Anchor Link

Feature: Contacts.

Group names are unique within a team — a clash is 409 contact_group_already_exists.

Import contacts into a group

curl -X POST "https://api.rateup.app/api/external/v2/contact-groups/$GROUP_ID/contacts/import" \
  -H "Authorization: Bearer $RATEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-10-16-batch-1" \
  -d '{
    "contacts": [
      { "phone": "919876543210", "name": "Priya Shah" },
      { "phone": "14155552671", "customFields": { "city": "Austin" } }
    ]
  }'

{
  "created": 1,
  "existing": 1,
  "added": 2,
  "alreadyMembers": 0,
  "contacts": [
    { "phone": "919876543210", "contactId": "3f6c…", "status": "existing", "reason": null },
    { "phone": "14155552671", "contactId": "9b2e…", "status": "created", "reason": null }
  ]
}

A row that could not be resolved has status: "failed" and a reason such as external_id_conflict. Adding by id answers { "added", "alreadyMembers", "notFound": [ids] }; removing answers { "removed" }.

TeamsCopy Anchor Link

Feature: Teams.

A team id is what campaigns and contact groups belong to, and what a template send can be attributed to.

CampaignsCopy Anchor Link

Feature: Campaigns. Needs a plan with WhatsApp campaigns.

Create, then send

curl -X POST "https://api.rateup.app/api/external/v2/campaigns" \
  -H "Authorization: Bearer $RATEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Diwali offer",
    "type": "WHATSAPP",
    "teamId": "c1d2…",
    "templateId": "0e9f…",
    "dynamicTags": ["name"],
    "contactGroupIds": ["5a6b…"]
  }'

The status cannot be set; a campaign starts as a draft. Then:

curl -X POST "https://api.rateup.app/api/external/v2/campaigns/$CAMPAIGN_ID/send" \
  -H "Authorization: Bearer $RATEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: diwali-offer-launch" \
  -d '{ "scheduledAt": "2026-10-20T10:00:00+05:30", "dailySendLimit": 5000 }'

{
  "campaignId": "8c7d…",
  "campaignStatus": "SCHEDULED",
  "send": {
    "id": "f1e2…",
    "attemptNo": 1,
    "trigger": "MANUAL",
    "status": "SCHEDULED",
    "targetStatuses": ["PENDING"],
    "scheduledFor": "2026-10-20T04:30:00.000Z",
    "startedAt": null,
    "completedAt": null,
    "createdAt": "2026-10-16T09:31:00.000Z",
    "totals": { "targeted": 1200, "sent": 0, "delivered": 0, "read": 0, "failed": 0, "completed": 0 }
  }
}

The send answers 202. An empty body means send to every pending recipient, now.

A DRIP campaign is started instead, and send is null — its stages go out on their own delays.

Stopping or pausing a campaign, and re-sending to named participants, are dashboard-only — see Campaign Details.

WhatsApp templatesCopy Anchor Link

Feature: WhatsApp messaging. Sends are paid — live keys only.

Send a template

curl -X POST "https://api.rateup.app/api/external/v2/wa/templates/send" \
  -H "Authorization: Bearer $RATEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{
    "templateName": "order_shipped",
    "language": "en_US",
    "phone": "919876543210",
    "header": { "type": "image", "link": "https://cdn.example.com/banner.jpg" },
    "bodyVariables": ["Priya", "1042"]
  }'

{ "status": "accepted", "messageId": "wamid.HBgMOTE5ODc2NTQzMjEw…" }

Send with an uploaded file

curl -X POST "https://api.rateup.app/api/external/v2/wa/templates/send-with-file" \
  -H "Authorization: Bearer $RATEUP_API_KEY" \
  -H "Idempotency-Key: invoice-1042" \
  -F "templateName=invoice_ready" \
  -F "phone=919876543210" \
  -F "headerType=document" \
  -F "filename=Invoice-1042.pdf" \
  -F 'bodyVariables=["Priya","1042"]' \
  -F "file=@/path/to/invoice-1042.pdf"

headerType is required with a file. bodyVariables and quickReplyPayload may be a JSON array (["Ann","500"]) or the same field repeated; a single plain value is a one-item list.

Send to contacts

{
  "contactIds": ["3f6c…", "9b2e…"],
  "bodyVariables": ["Weekend sale"],
  "header": { "type": "image", "link": "https://cdn.example.com/sale.jpg" }
}

It answers once every send has been tried:

{
  "sent": [{ "contactId": "3f6c…", "messageId": "wamid.…" }],
  "failed": [{ "contactId": "9b2e…", "code": "contact_limit_reached", "metaCode": null }],
  "skipped": [{ "contactId": "77aa…", "reason": "no_phone" }]
}

Check delivery

{
  "messageId": "wamid.…",
  "status": "delivered",
  "createdAt": "2026-10-16T09:32:00.000Z",
  "sentAt": "2026-10-16T09:32:01.000Z",
  "deliveredAt": "2026-10-16T09:32:03.000Z",
  "readAt": null,
  "failedAt": null,
  "error": null
}

status is pending, sent, delivered, read or failed. Prefer the message.status webhook to polling.

SurveysCopy Anchor Link

Feature: Surveys.

{
  "data": [
    {
      "id": "d4c3…",
      "createdAt": "2026-10-16T08:12:00.000Z",
      "teamId": "c1d2…",
      "language": "en",
      "tag": null,
      "phone": "919876543210",
      "encrypted": false,
      "encryptedAnswers": null,
      "answers": [
        { "questionId": "q1", "type": "rating", "title": "How was your visit?", "value": 5 }
      ]
    }
  ],
  "nextCursor": null
}

When the organisation encrypts responses, encrypted is true, answers is empty and encryptedAnswers carries the ciphertext for you to decrypt with your own key.

LoyaltyCopy Anchor Link

Feature: Loyalty. Needs a plan with loyalty. Members are named by phone or card code, never by id: send exactly one of phone or cardCode (a query parameter on reads, a member object on writes). A card code may be bare, grouped (ABC-DEF-GHJ), lower case or the card URL.

Award points for a purchase

curl -X POST "https://api.rateup.app/api/external/v2/loyalty/points/award" \
  -H "Authorization: Bearer $RATEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-store7-order-1042" \
  -d '{
    "member": { "phone": "919876543210" },
    "purchaseAmount": 1250,
    "orderId": "1042"
  }'

{
  "replayed": false,
  "transactionId": "tx_5e6f…",
  "pointsAwarded": 125,
  "balance": { "current": 845, "lifetime": 2310 },
  "rule": { "name": "Standard", "multiplier": 1, "bonusPoints": 0 },
  "tier": {
    "current": { "name": "Silver", "color": "#C0C0C0" },
    "upgraded": false,
    "next": { "name": "Gold", "threshold": 25000 },
    "amountToNext": 4800
  }
}

Spend points, then hand the voucher over

curl -X POST "https://api.rateup.app/api/external/v2/loyalty/rewards/FREE-COFFEE/redeem" \
  -H "Authorization: Bearer $RATEUP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-store7-redeem-883" \
  -d '{ "member": { "cardCode": "ABC-DEF-GHJ" } }'

{
  "voucherCode": "RDM-7Q2K",
  "status": "approved",
  "pointsSpent": 500,
  "balance": { "current": 345, "lifetime": 2310 },
  "expiresAt": "2026-11-15T00:00:00.000Z"
}

GET /loyalty/vouchers/{code} returns valid and, when it is false, an invalidReason — read it before handing anything over. POST /loyalty/vouchers/{code}/redeem takes optional appliedBy and notes.

The card send only delivers inside the customer's 24-hour WhatsApp window; outside it the answer is { "sent": false, "skippedReason": "session_closed" } rather than an error.

WebhooksCopy Anchor Link

The API is for actions; webhooks tell you what happened. There is one webhook per organisation, receiving every event you tick. It is set up in the dashboard under Settings → Integrations → Webhook, not through the API and not per API key: every key — and every integration — shares the same endpoint and secret. Among others it can deliver:

These arrive in an envelope — { id, type, createdAt, orgId, data } — and are retried. Each delivery is signed with the organisation's signing secret (whsec_…, shown on the Signing secret card):

To verify: take the raw body, recompute the HMAC over <t>.<raw body>, compare it with v1 in constant time, and reject a t more than 5 minutes from your clock. Node and Python examples and a test vector are on the Integrations page.

v1 (Legacy)Copy Anchor Link

v1 stays for integrations already built on it. It is mounted at https://api.rateup.app/api/external/v1/{orgId} and accepts v1 keys only — create one with API version → v1 (legacy). New work belongs on v2.

What v1 shares with v2 now:

• Feature limits are enforced. A v1 key limited to features gets 403 insufficient_scope outside them, exactly as on v2.
• Everything is checked against your organisation. A key only works for the orgId in its own URL, and contact writes that name another organisation's labels, groups, lifecycle stages, custom fields or users are refused with 400 instead of being saved.
• Authentication, scope, rate-limit and idempotency failures use the v2 error envelope. A missing bearer token on v1 answers 400. Business failures from the original handlers keep their original shapes, such as { "error": "…" }.
• Idempotency-Key works on every v1 write.

v1 read shapes to expect:

v1 template sends take phone as a number (country code, no +), and body_variables on send-with-file as a JSON string — malformed JSON there is silently treated as an empty list, so the template sends with blanks.

Migrating from v1 to v2Copy Anchor Link

TroubleshootingCopy Anchor Link

Related PagesCopy Anchor Link

• Integrations — creating keys, usage, and the organisation webhook
• Members & Roles — who may manage API keys
• WhatsApp Templates — building and approving templates
• Custom Fields — the slugs customFields is keyed by
• Loyalty — the programme the loyalty endpoints run
• Web Forms → Settings — the per-form survey response webhook