Your AI Connector Docs

API Access

An API (Application Programming Interface) is a way for different software systems to talk to each other. The API lets you (or your developer) automatically create contacts, send messages, manage lists, and receive incoming messages from custom channels - all without using the dashboard.

Why use the API? If you want to connect the app to a tool that does not have a built-in integration, or if you need to automate repetitive tasks at scale, the API is the way to do it.

Note: This page is more technical in nature. If you are a business owner and not a developer, you may want to share this page with your technical team or a freelance developer who can set things up for you.

Generating Your API Key

  1. In the app, go to Settings > Account.
  2. Scroll to the API Key section.
  3. Click Generate to create a new API key.
  4. Copy the key and store it securely. You will need it for every API request.

Important: Your API key is like a password - it grants full access to your account. Do not share it publicly or post it anywhere others can see it. If you believe your key has been compromised, generate a new one immediately - this will invalidate the old key.

Base URL

All API requests use the following base web address:

https://api.example.com/v1/

Authentication

Every request must include your API key so the platform knows it is you. Add it to the end of the web address like this:

https://api.example.com/v1/contacts?apiKey=YOUR_API_KEY

All requests must use a secure connection (HTTPS). Insecure (HTTP) requests will be rejected.

Common API Operations

Create a Contact

Add a new contact to your account.

Request:

POST https://api.example.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+15551234567",
  "email": "[email protected]"
}

Required fields: At minimum, provide a phone number (with country code) or an email.

Response:

{
  "id": "abc123xyz",
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+15551234567",
  "email": "[email protected]",
  "createdAt": "2026-01-15T10:30:00Z"
}

Note: If a contact with the same phone number already exists, the existing contact is returned instead of creating a duplicate.

Add a Contact to a List

Add an existing contact to a specific contact list.

Request:

POST https://api.example.com/v1/lists/LIST_ID/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz"
}

Replace LIST_ID with your actual list ID. You can find list IDs in the app under Contacts > Lists.

Send a Message (Custom Channel)

Send a message to a contact through a custom channel. This is the same endpoint described in the Custom Channels guide.

Request:

POST https://api.example.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}
Field Required Description
customData.fromId Yes The contact’s ID on your platform
customData.customChannel Yes The name of your custom channel
customData.body Yes The message text to send
customData.campaignId No Route the message to a specific campaign
customData.firstName No Contact’s first name (used when creating a new contact)
customData.lastName No Contact’s last name
customData.email No Contact’s email address

Note: This endpoint is for custom channel messaging. For WhatsApp, SMS, Instagram, and Messenger, messages are sent through campaigns and the AI bot.

Receive Incoming Messages (Custom Channel)

Accept messages from external systems as a custom channel in the app. This is how integrations like GoHighLevel send messages to the platform. See the Custom Channels guide for full details and examples.

Request:

POST https://api.example.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}
Field Required Description
customData.messageSid Yes A unique ID for this message (prevents duplicates). You can also use customData.id.
customData.fromId Yes The sender’s ID in your external system (for example, a customer ID from your CRM).
customData.toId Yes Your business identifier.
customData.body Yes The actual message text.
customData.channel No A label for the source (e.g., "email", "livechat", "custom").
customData.status No Message status. Defaults to "received".
messageType No The type of content. Set to "text" for text messages, "reaction" for emoji reactions.

Grant Credits to a Sub-Account

(Agency accounts only) Add credits to a sub-account. This is typically called after processing a payment triggered by the auto-recharge webhook.

Request:

POST https://api.example.com/v1/subaccounts/credits
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "email": "[email protected]",
  "amount": 500,
  "description": "Auto-recharge via webhook"
}
Field Required Description
email Yes The sub-account’s email address (must match an existing sub-account under your agency).
amount Yes The number of credits to grant.
description No A note describing why credits were added (shown in the credit transaction history).

Authentication: This endpoint uses header-based authentication. Include your API key in the x-api-key header (not as a query parameter).

Response:

{
  "success": true,
  "sub_account_id": "abc123xyz",
  "credits_added": 500,
  "new_balance": 542
}

Tip: When using this endpoint as part of the auto-recharge webhook flow, store the idempotency_key from the webhook payload and check it before calling this endpoint. This prevents accidentally granting credits twice if your server receives the same webhook more than once.

Available Operations Overview

Action Method Address Description
Create a contact POST /contacts Add a new contact to your account
Get contact details GET /contacts?phoneNumber=X or /contacts?email=X Look up a contact by phone number or email
Add contact to list POST /lists/:listId/contacts Add an existing contact to a specific list
Send a message POST /send_custom_channel_message Send a message through a custom channel
Receive a message POST /incoming_custom_channel_message Accept a message from an external system
Grant credits to sub-account POST /subaccounts/credits (Agency only) Add credits to a sub-account

Rate Limiting

The API enforces rate limits to ensure platform stability:

  • Requests are limited per API key per minute.
  • If you exceed the limit, you will receive a 429 Too Many Requests response.
  • Back off and retry after the time indicated in the response headers.

For high-volume use cases (such as bulk imports), use the platform’s built-in import feature or email [email protected] for guidance on batch operations.

Best Practices

  • Store your API key securely. Keep it in a safe place (like a password manager or server-side configuration) - never put it in code that runs in a web browser where others could find it.
  • Always include the country code in phone numbers (for example, +1 for US, +44 for UK, +31 for Netherlands).
  • Handle errors gracefully. Check the status codes in the response (see the Error Responses section below) and read any error messages returned.
  • Avoid duplicates. Creating a contact with a phone number that already exists returns the existing contact rather than creating a duplicate, so you do not need to worry about accidental double entries.
  • Test with a small dataset before running bulk operations.
  • Monitor your webhook receiving system if you are using webhooks alongside the API to ensure you are receiving events.

Error Responses

API errors follow a consistent format:

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}
Status Code Meaning
200 Success
201 Resource created
400 Bad request - check your parameters
401 Unauthorized - invalid or missing API key
404 Resource not found
429 Rate limit exceeded
500 Server error - email [email protected] if this persists

Next Steps