API & webhooks

Authentication

Every request authenticates with an API key sent as a bearer token. Create a key in Channels & integrations → Developer API & webhooks → API keys. The full key is shown only once at creation — store it securely. Keys look like aa_<prefix>_<secret>.

Authorization: Bearer aa_live_xxxxxxxxxxxxxxxxxxxxxxxx

Requests without a valid key return 401. Keys on a plan below Growth return 403. Treat keys like passwords: never expose them in client-side code or a browser. POST leads from your server, not from a public web page.

Base URL & format

All endpoints live under:

https://automateadmits.com/api/v1

Requests and responses are JSON (Content-Type: application/json). List endpoints return { "data": [...], "next_cursor": ... }. Single-object endpoints return { "data": {...} }. Errors return { "error": "message" } with an appropriate HTTP status.

Probe a key

curl https://automateadmits.com/api/v1/me \
  -H "Authorization: Bearer $AA_KEY"

{ "org_id": "org_...", "org_name": "Acme Recovery", "plan": "growth",
  "version": "1", "events": ["message_received","lead_created", ...] }

Pagination

List endpoints are cursor-paginated, newest first. Pass limit (default 50, max 100). When more results exist, the response includes a next_cursor — pass it back as ?cursor= to fetch the next page. When next_cursor is null, you've reached the end.

GET /api/v1/contacts?limit=100
GET /api/v1/contacts?limit=100&cursor=1718900000000

Creating leads — the #1 use case

POST a lead from your own form or landing page and it lands in your inbox immediately, ready for a human (this endpoint never triggers an AI auto-reply). It creates a contact and a conversation, and optionally an initial inbound message. This fires the lead_created webhook.

curl -X POST https://automateadmits.com/api/v1/leads \
  -H "Authorization: Bearer $AA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jordan Lee",
    "phone": "+15551234567",
    "email": "jordan@example.com",
    "message": "Saw your ad — do you take Aetna?",
    "source": "Google Ads landing page"
  }'

HTTP/1.1 201 Created
{ "data": { "contact_id": "ct_...", "conversation_id": "cv_...",
            "status": "new", "created_at": 1718900000000 } }

Contacts

Conversations & messages

curl -X POST https://automateadmits.com/api/v1/conversations/cv_123/messages \
  -H "Authorization: Bearer $AA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hi Jordan — yes, we accept Aetna. When works for a quick call?" }'

Calls

Webhooks

Register a URL under Channels & integrations → Developer API & webhooks → Webhooks and subscribe to the events you care about (subscribe to none to receive all events, including ones we add later). When an event fires, we POST a JSON payload to your URL.

Each delivery carries these headers:

Respond with any 2xx status to acknowledge. Non-2xx responses are counted as failures and surfaced in the app. Use the Send test button to POST a signed ping payload and confirm your receiver works.

Event types

Verifying signatures

Always verify the X-AA-Signature before trusting a payload. Compute the HMAC-SHA256 of the raw request body (not a re-serialized copy) using your endpoint's signing secret, then compare it to the hex after sha256= using a constant-time comparison.

// Node.js (Express) example
const crypto = require("crypto");

function verify(req) {
  const secret = process.env.AA_WEBHOOK_SECRET;      // your endpoint's signing secret
  const sig = req.get("X-AA-Signature") || "";        // "sha256=<hex>"
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(req.rawBody)                               // the exact bytes we sent
    .digest("hex");
  return sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

If you rotate a secret in the app, older payloads signed with the previous secret will no longer verify — roll the secret when you're ready to update your receiver.