API Access #

An API (Application Programming Interface) is a way for different software systems to talk to each other. The Your AI Connector 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 doesn’t have a built-in integration, or you need to automate repetitive tasks at scale, the API is the way to do it.

Generating Your API Key #

1. In the left sidebar, click Settings (gear icon).
2. In the Settings sidebar, under the Integrations group, click API Key.

3. If you don’t have a key yet, click Generate API key.
4. If you already have one, it’s shown masked under Your key. If your key supports it, click Show to reveal it, then Copy to copy it — you’ll see a confirmation toast.
5. Store the key somewhere safe — you’ll need it for every API request.

Team members: the API key belongs to the account owner, so if you’re signed in as an invited team member (including an Admin) the section shows a note instead of the key. Sign in as the account owner to view, copy or regenerate it — that applies to scoped keys too.

Where to find it: API Key is its own section under Settings → Integrations, separate from Webhooks. If a guide or a colleague tells you to look under “Webhooks” for the key, look one section over instead.

Base URL #

All API requests use the following base web address:

https://api.youraiconnector.com/v1/

Authentication #

Every request must include your API key so the platform knows it’s you. The simplest way is to add it to the end of the web address:

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

You can also send the key as a request header instead of in the URL (recommended for production, so the key doesn’t end up in server logs):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

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

Looking for the full developer guides? This page is a quick intro covering the most common operations. For complete, step-by-step guides — every resource, with cURL, JavaScript, and Python examples — see Getting Started with the API and the API Reference.

Common API Operations #

Create a Contact #

Request:

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

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

Required fields: a phoneNumber (with country code) is always required to create a contact. An email address alone is not enough — a request without a valid phone number is rejected. The email is optional.

Response:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

Save data.contactId — you’ll need it for the “Add a Contact to a List” call.

Add a Contact to a List #

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

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

Find a list’s ID in the app under Contacts → Lists, from a list’s row menu (Copy list ID).

Update a Contact #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

Only the fields you include are changed. This is also the way to bulk-load custom field values after an import — see Custom Fields, Lead Profile & Notes. Full details in the Contacts API.

Send a Message (Custom Channel) #

POST https://api.youraiconnector.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"
  }
}

Receive Incoming Messages (Custom Channel) #

Accept messages from external systems as a custom channel. This is how integrations like GoHighLevel send messages into Your AI Connector. See Custom Channels for full details.

POST https://api.youraiconnector.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"
}

Available Operations Overview #

Rate Limiting #

The API enforces rate limits to ensure platform stability. Exceeding your limit returns 429 Too Many Requests — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in import feature or email hi@youraiconnector.com for guidance.

Best Practices #

• Store your API key securely — a password manager or server-side configuration, never client-side code a browser visitor could read.
• Always include the country code in phone numbers (+1 for US, +44 for UK, +31 for Netherlands).
• Handle errors gracefully — check status codes and read any error messages returned.
• Handle duplicates — a duplicate phone number returns { "success": false, "error_code": 409 } instead of a new contact. Look the contact up first if you need to work with it.
• Test with a small dataset before running bulk operations.

Error Responses #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

Next Steps #

• Webhooks — receive real-time notifications from the app (a separate section from your API key).
• Connect AI Assistants (MCP) — use the same API key to let Claude drive your account.
• Facebook Lead Forms — use the API with automation platforms to capture leads.
• GoHighLevel Integration — a full two-way API integration example.