---
title: "Make your first API request"
description: "Authenticate a read-only contact search and understand the result."
---

> Documentation Index
> Fetch the complete documentation index at: https://developer.channelautomations.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Make your first API request

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`.

```bash
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.

```bash
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:

```json
{
  "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](/api/get-api-contacts-search/) to inspect every query parameter and response schema. From there, browse Contacts, Messages, Webhooks, or Calendar for your integration.

The existing [Swagger documentation](https://api.customerconnects.app/docs/) remains available for interactive testing. This reference does not certify every operation in the original specification as a supported external integration API.

Source: https://developer.channelautomations.com/first-request/index.mdx