Make your first API request | Channel Automation Developers

This walkthrough searches for a fictional email address. It uses a GET request: it does not create a contact, send a message, or start an automation.

Before you start

Ask your workspace owner or administrator for an existing workspace API key and its matching workspace ID. Use a key authorized for the contact-search endpoint. A restricted API key for another API, such as Sales Coach, is not interchangeable with a general workspace key.

The sample below uses placeholders. No credentials are included in this documentation, and this walkthrough has not been executed against a real workspace.

1. Set your connection details

The production base URL declared by the current OpenAPI document is https://api.channelautomation.com.

export CA_API_BASE="https://api.channelautomation.com"
export CA_API_KEY="YOUR_WORKSPACE_API_KEY"
export CA_WORKSPACE_ID="YOUR_WORKSPACE_ID"

Replace the two placeholders in your own environment. Keep your real key out of screenshots, shared code, and browser-side application code.

2. Send a read-only contact search

Use X-API-Key for the key and X-Workspace-Id for its workspace. The fictional email below is intended to produce a no-match response.

curl --include --get "$CA_API_BASE/api/contacts/search" \
  --header "X-API-Key: $CA_API_KEY" \
  --header "X-Workspace-Id: $CA_WORKSPACE_ID" \
  --header "Accept: application/json" \
  --data-urlencode "email=developer-preview@example.invalid" \
  --data-urlencode "limit=1"

--include shows the HTTP status along with the JSON body. This command runs only when you execute it in your own terminal; viewing or copying the example makes no API request.

3. Understand the response

For an email search with no match, the current repository handler returns HTTP 200 with an empty result:

{
  "success": true,
  "count": 0,
  "data": []
}

The email in this walkthrough is fictional, so an empty result is the expected outcome. When contacts match, data holds the records and count reports how many were returned.

Specification note: The existing OpenAPI document describes a different response shape (contacts and total) and lists a no-match 404. The guide above follows the current repository handler for email searches. This reference preserves the original specification; an authenticated live response has not been verified.

4. Resolve common errors

Status	What to check
`400`	Supply the required workspace information and valid query parameters.
`401`	Check that the API key is correct, active, and not expired.
`403`	Confirm the key has access to the requested workspace and API.
`404`	Check the request URL; the current email-search handler represents no matches with an empty `200` response.
`429`	Follow the rate-limit response before trying again.
`500`	A server error occurred; retain the status and error response for support.

Errors are endpoint-specific. Use the operation’s documented responses when building your integration.

Next steps

Open Search contacts in the API reference to inspect every query parameter and response schema. From there, browse Contacts, Messages, Webhooks, or Calendar for your integration.

The existing Swagger documentation remains available for interactive testing. This reference does not certify every operation in the original specification as a supported external integration API.