GET/v1/contacts
Your contacts, newest first. Any key. page (default 1) and limit (default 20) paginate.
curl "https://beecastly.com/api/v1/contacts?page=1&limit=20" \
-H "x-api-key: YOUR_API_KEY"
{
"success": true,
"data": [
{
"id": "cmg1k9…",
"name": "John Doe",
"phone": "+12025551234",
"email": "[email protected]",
"tags": ["vip"],
"source": "api",
"createdAt": "2026-10-01T10:30:00.000Z",
…
}
],
"pagination": { "page": 1, "limit": 20, "total": 1250, "totalPages": 63 }
}POST/v1/contacts
Create one contact. Needs a Read & write key. Common fields: name, firstName,lastName, email, phone (international format), tags (array of strings) andmetadata (any JSON object, for your own fields). source is always set to api.
curl -X POST https://beecastly.com/api/v1/contacts \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith",
"phone": "+14155551234",
"email": "[email protected]",
"tags": ["lead", "webinar"],
"metadata": { "company": "TechCorp" }
}'
// 201 Created
{ "success": true, "data": { "id": "cmg1ka…", "name": "Jane Smith", … } }409 — already exists.Email and phone are unique within your workspace. A repeat returns 409 with the existing contact indata and "existed": true, so you can treat it as an upsert.
403 API_KEY_PERMISSION — the key is read-only.