At a glance
Overview
- 1 Confirm your plan includes Developers API Access. Open Advance Tools → Developers API (or user menu → Developer API).
- 2 Under API Tokens, click Generate New Token, enter a name and optional expiry, then copy the token immediately — it is shown only once.
- 3 Use the Base URL shown on the page and send your token as a Bearer authorization header.
- 4 Download All (Postman) or use per-endpoint Postman buttons / the API Explorer to send a test request.
- 5 Revoke tokens you no longer need. Register webhooks when you want inbound events pushed to your server.
Step by step
Use the API
Create a token, import Postman, then call the API resources shown on the page.
API tokens
Tokens authenticate as your workspace. Team members need api / api.tokens permission (admins bypass).
- 1 Open API Management → API Tokens → Generate New Token.
- 2 Provide a Name and optional Expires At, then generate.
- 3 Copy and store the token securely. You will not be able to view it again.
- 4 The list shows name, created, last used, and expires. Use Revoke to invalidate a token immediately.
- 5 On 401 responses, check expiry, plan access, and whether the token was revoked — then generate a new one if needed.
Postman and API Explorer
Shipped collection: UpScaleUp-Complete-API-Collection (Contacts, Messages, Templates, Media, Webhooks).
- 1 Click Download All (Postman) or Getting Started, or use Postman on an individual endpoint example.
- 2 In Postman, set the collection Base URL and API token variables, and use Bearer authentication.
- 3 Or use API Explorer on the same page for live requests with cURL, PHP, JavaScript, Python, Node.js, or .NET C# snippets.
- 4 Jump chips on the page: Tools, Contacts, Messages, Templates, Webhooks.
- 5 Optional Remember in Explorer stores the token in your browser only if you check it — prefer secure app configuration for production.
Contacts, messages, templates, and media
All paths are under /api/v1 on your Base URL. Send the token as Authorization: Bearer <token> (or the X-API-Token header) with Accept: application/json.
- 1 Contacts: GET /contacts (search, group filter, per_page up to 100, page), POST /contacts, GET /contacts/{id}, PUT /contacts/{id}, DELETE /contacts/{id}.
- 2 Find a contact: GET /contacts/find?phone=…&email=… returns up to 5 matches (give a phone, an email, or both).
- 3 Groups: GET /groups lists your groups. POST /contacts/{id}/groups with group_id adds a contact to a group; DELETE /contacts/{id}/groups/{groupId} removes it.
- 4 Messages: POST /messages/send sends text or attachments; GET /messages/{message_id}/status checks delivery. Send to either a contact_id or a phone_number (not both); a phone number can auto-create the contact.
- 5 Templates: GET /templates lists approved templates with id (name::language), header_type, and the numbered body variables. POST /templates/send sends one; pass language when a template exists in several languages, variables as {"1": "value"}, and media_handle for image, video, or document headers.
- 6 Account: GET /me returns the connected account; GET /team-members lists the owner and active teammates (for assigning conversations).
- 7 WhatsApp must be connected and templates Approved for send/template calls to succeed.
- 8 Media: download with your API token, or use the short-lived signed links from webhooks (download promptly).
Bookings, orders, inbox, and campaigns
Automate the rest of your workspace. Creating bookings needs Booking automation on your plan; campaign sends follow the same rules as the Campaigns page.
- 1 Booking events: GET /booking-events lists active booking events with their type and, for stays, their room types.
- 2 Bookings: GET /bookings?type=appointment|reservation|booking|accommodation lists bookings (optional status=pending,approved…, page). POST /bookings creates one from a contact_id or phone_number and a booking_event_id, with scheduled_at for timed events or room_type_id, check_in, and check_out for stays. Send times in ISO 8601 with a timezone offset.
- 3 Approve or cancel: POST /bookings/{type}/{id}/approve and POST /bookings/{type}/{id}/cancel.
- 4 Orders: GET /orders lists catalog orders (optional status filter, page). POST /orders/{id}/status with status processing, fulfilled, or cancelled.
- 5 Conversations: GET /conversations (open_only=1 to hide resolved, page). POST /conversations/{id}/assign with user_id (from /team-members); POST /conversations/{id}/resolve marks it resolved.
- 6 Campaigns: POST /campaigns/send with group_id, template_name, optional language, campaign_name, variables, and media_handle. You must send opt_in_confirmed=true to confirm everyone in the group opted in to your WhatsApp messages; the campaign then queues like one started from the Campaigns page.
Webhooks
Register an HTTPS endpoint to receive events. Team permission api.webhooks (or admin).
- 1 Create a webhook via the API page or Postman with your HTTPS URL and the events you want.
- 2 Contact events: contact.created, contact.updated, contact.deleted, contact.added_to_group, contact.removed_from_group.
- 3 Message events: message.received, message.sent, message.delivered, message.read, message.failed.
- 4 Booking events: booking.created, booking.confirmed, booking.approved, booking.completed, booking.cancelled, booking.rejected, booking.no_show, booking.rescheduled.
- 5 Campaign events: campaign.started, campaign.completed, campaign.failed, campaign.cancelled. Order events: order.created, order.processing, order.fulfilled, order.cancelled, order.paid.
- 6 Other events: payment.received, payment.failed (in-chat payments), conversation.assigned, conversation.resolved, and reminder.due.
- 7 Each delivery is a JSON POST with event, event_id, data, and timestamp. Contact data includes name, phone, email, groups, and custom fields.
- 8 Return a 2xx response quickly. Server errors (5xx), 429, and timeouts are retried up to 3 attempts with the same event_id, so ignore duplicates by event_id. If you set a secret, verify the signature field (HMAC-SHA256).
- 9 Respond with 410 Gone to unsubscribe: the webhook is switched off and no further events are sent to it.
- 10 GET /trigger-samples?event=… returns recent real records shaped like that event, useful for testing a receiver before a live event happens.
- 11 List or delete webhooks from the API, and use the in-page tester (or the test endpoint in Postman) to verify delivery.
- 12 Download media referenced in payloads within about an hour using the signed URLs provided.
Tips
- Never put tokens in public repos or frontend JavaScript.
- Rotate tokens if a teammate leaves or a key may have leaked; revoke unused keys.
- Do not use Developer API tokens as session cookies or on ordinary web routes.
- WooCommerce and Shopify commerce API calls use the store token from Integrations — not your personal Developer API token.
- Owners should limit who can manage tokens via Team permissions and Billing plan access.