# API Access An API (Application Programming Interface) is a way for different software systems to talk to each other. The DM Champ API lets you (or your developer) automatically create contacts, send messages, manage lists, and receive incoming messages from custom channels - all without using the DM Champ dashboard. **Why use the API?** If you want to connect DM Champ 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 DM Champ, 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 DM Champ 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.dmchamp.com/v1/ ``` *** ## Authentication Every request must include your API key so DM Champ knows it is you. Add it to the end of the web address like this: ``` https://api.dmchamp.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 DM Champ account. **Request:** ```http POST https://api.dmchamp.com/v1/contacts?apiKey=YOUR_API_KEY Content-Type: application/json { "firstName": "Jane", "lastName": "Smith", "phone": "+15551234567", "email": "jane@example.com" } ``` **Required fields:** At minimum, provide a `phone` number (with country code) or an `email`. **Response:** ```json { "id": "abc123xyz", "firstName": "Jane", "lastName": "Smith", "phone": "+15551234567", "email": "jane@example.com", "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:** ```http POST https://api.dmchamp.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 DM Champ 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](https://help.dmchamp.com/messaging-channels/custom-channels) guide. **Request:** ```http POST https://api.dmchamp.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 DM Champ. This is how integrations like GoHighLevel send messages to DM Champ. See the [Custom Channels](https://help.dmchamp.com/messaging-channels/custom-channels) guide for full details and examples. **Request:** ```http POST https://api.dmchamp.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](https://help.dmchamp.com/webhooks#agency-sub-account-auto-recharge-webhook). **Request:** ```http POST https://api.dmchamp.com/v1/subaccounts/credits x-api-key: YOUR_API_KEY Content-Type: application/json { "email": "customer@example.com", "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:** ```json { "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 DM Champ 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 DM Champ's built-in import feature or fill in the form at [dmchamp.com/help](https://dmchamp.com/help) 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: ```json { "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 - fill in the form at [dmchamp.com/help](https://dmchamp.com/help) if this persists | *** ## Next Steps * [Webhooks](https://help.dmchamp.com/integrations/webhooks) - Receive real-time notifications from DM Champ. * [Facebook Lead Forms](https://help.dmchamp.com/integrations/facebook-lead-forms) - Use the API with automation platforms to capture leads. * [GoHighLevel Integration](https://help.dmchamp.com/integrations/ghl-integration) - See a full two-way API integration example.