HelloSend Public API v3 — Reference

Version: v3
Production base URL: https://api.hellosend.com

Table of Contents

1. Overview
2. Authentication
3. Request & Response Conventions
4. Errors
5. Idempotency
6. Endpoints - Auth - Messages - Numbers - Templates - Contacts - Webhooks (REST Hooks) - Webhook Samples
7. Webhook Events
8. Zapier Integration Mapping
9. Getting an API Key
10. Endpoint Index

Overview

Path Prefix

All routes use the prefix /api/v3/....

Example: GET https://api.hellosend.com/api/v3/auth/verify

Content Type

• Request bodies: Content-Type: application/json
• Responses: Content-Type: application/json
• Success property names: camelCase (e.g. serviceId, fromNumber)
• Error codes: snake_case (e.g. invalid_api_key)

Authentication

Every /api/v3 request requires a long-lived API key issued from the HelloSend web app.

API keys are user-scoped for hooks and sends, and account-scoped for shared resources such as contacts. Revoking a key or deactivating its owner invalidates the key and removes all hook subscriptions created with that key.

Request & Response Conventions

List Responses

List endpoints wrap results in a named array:

Dates & Times

Phone Numbers

Use E.164 format (e.g. +14155551234).

Errors

All error responses use this envelope:

{
  "error": "snake_case_code",
  "message": "Human-readable explanation."
}

HTTP Status Codes

Error Code Reference

Idempotency

POST /api/v3/messages supports optional idempotent sends via the Idempotency-Key request header. Using this header prevents duplicate sends on retries.

Behavior

Idempotency is scoped to account + user.

Endpoints

Auth

Verify Connection

GET /api/v3/auth/verify

Confirms a valid API key and returns metadata for connection labels.

Response 200

Example request

GET /api/v3/auth/verify HTTP/1.1
Host: api.hellosend.com
X-HelloSend-API-Key: hs_live_xxxxxxxxxxxxxxxx
Accept: application/json

Example response

{
  "userEmail": "alex@example.com",
  "userName": "Alex Morgan",
  "osyncUserId": "usr_abc123",
  "accountName": "Acme Corp",
  "apiKeyId": "key_xyz789",
  "apiKeyName": "Zapier production"
}

Messages

Send Message

POST /api/v3/messages

Send an outbound SMS, MMS, WhatsApp, or RCS message.

Request body

Template rules

• SMS/Application template — If body is omitted, the server renders from template content + variables. If body is provided, it is sent as-is and tagged with templateId.
• WhatsApp/RCS (structured) template — Rendered from variables only. Sending a non-empty body returns 422 body_not_allowed_for_structured_template.

Response 201

Example — plain SMS

POST /api/v3/messages HTTP/1.1
Host: api.hellosend.com
X-HelloSend-API-Key: hs_live_xxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "uniqueId": "SN_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "toNumber": "+14155551234",
  "body": "Your appointment is confirmed for tomorrow at 2pm."
}

Response

{
  "id": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "messageId": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "sent",
  "fromNumber": "+14155559876",
  "toNumber": "+14155551234",
  "serviceId": "integ_abc123"
}

Example — template with variables

{
  "uniqueId": "SN_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "toNumber": "+14155551234",
  "templateId": "tmpl_welcome_001",
  "variables": {
    "firstName": "Ada",
    "orderId": "ORD-42"
  }
}

Numbers

List Numbers

GET /api/v3/numbers

Returns phone numbers the authenticated user may send from. Used to populate From Number dropdowns.

Response 200 — numbers[] item

Example response

{
  "numbers": [
    {
      "id": "SN_01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "integId": "integ_abc123",
      "phoneNumber": "+14155559876",
      "friendlyName": "Main sales line",
      "provider": "Twilio",
      "crm": "HubSpot",
      "channels": ["sms", "mms"],
      "label": "+14155559876 — HubSpot via Twilio (SMS · MMS)"
    }
  ]
}

Templates

List Templates

GET /api/v3/templates

Query parameters

Response 200 — templates[] item

Get Template

GET /api/v3/templates/{id}

Returns full template detail including placeholders and, for structured templates, components.

Errors: 404 template_not_found when the id does not exist in the account.

Contacts

Find Contacts by Phone

GET /api/v3/contacts?phone={phone}

Account-scoped contact lookup. Returns an empty contacts array when no match — not an error.

Query parameters

Response 200 — contacts[] item

Webhooks (REST Hooks)

HelloSend delivers webhook payloads to HTTPS URLs registered via these endpoints. Use these routes to subscribe and unsubscribe triggers.

List Hooks

GET /api/v3/hooks

Response 200 — hooks[] item

Subscribe

POST /api/v3/hooks

Request body

Response 201 — Same shape as a single hook object above.

Multiple subscriptions for the same event are supported (each subscriber receives independent deliveries).

Example

{
  "event": "inbound_message",
  "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
}

Unsubscribe

DELETE /api/v3/hooks/{hookId}

Response 200

{
  "deleted": true,
  "hookId": "hook_uuid_here"
}

Errors: 404 hook_not_found when the id does not belong to the authenticated user.

Webhook Samples

Read-only endpoints that return recent webhook-shaped payloads for integration testing. The JSON structure matches live webhook POST bodies.

Inbound SMS Samples

GET /api/v3/zapier-hook-samples/inbound-message-sms

Outbound Delivery Status Samples

GET /api/v3/zapier-hook-samples/outbound-message-sms-status

Query parameters (both endpoints)

Response 200

{
  "events": [ /* webhook envelope objects, newest first */ ]
}

Returns { "events": [] } when the account has no recent matching history.

Webhook Events

When a subscribed event occurs, HelloSend POSTs a JSON envelope to the registered targetUrl with Content-Type: application/json.

Supported Events

Envelope Shape

inbound_message — data object

Example payload

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "inbound_message",
  "occurredAt": "2026-04-20T12:34:56.789Z",
  "data": {
    "messageId": "msg_inbound_123",
    "fromNumber": "+14155551234",
    "toNumber": "+14155559876",
    "body": "Hey — reply when you can.",
    "receivedAt": 1745148896789,
    "contact": {
      "phone": "+14155551234",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "ada@example.com",
      "remoteContactId": "crm_contact_456"
    }
  }
}

outbound_message_status — data object

Example payload

{
  "id": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx_delivered",
  "event": "outbound_message_status",
  "occurredAt": "2026-04-20T12:35:00.000Z",
  "data": {
    "messageId": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "fromNumber": "+14155559876",
    "toNumber": "+14155551234",
    "deliveryStatus": "delivered",
    "loggedAt": 1745152500000,
    "errorCode": "",
    "errorDetail": "",
    "contact": {
      "phone": "+14155551234",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "ada@example.com",
      "remoteContactId": "crm_contact_456"
    }
  }
}

Contact Object

Included in both event payloads when a matching contact is found.

Zapier Integration Mapping

Getting an API Key

API keys are created in the HelloSend web app — not via the API.

1. Sign in at https://www.hellosend.com
2. Go to Settings → API Keys
3. Click Generate key, name it, and copy the secret immediately (shown once)
4. Paste the key into your integration

Revoke unused keys from the same Settings page.

Endpoint Index