Quickstart

A working end-to-end integration in four steps. Everything here uses real endpoints — see the reference for full parameters.

1. Create a key

In the dashboard, go to API keys and create one with only the permissions this integration needs. For the example below that’s contacts:create and calls:create. Copy it immediately — the full key is shown once.

export RECEPTA_API_KEY="rcp_your_key_here"

Keep this server-side. Never ship a key in frontend JavaScript or a mobile app — anything on a user’s device is readable by that user. Proxy through your own backend.

2. Confirm it works

curl "https://api.recepta.ai/api/v1/api/calls?limit=1" \
  -H "x-api-key: $RECEPTA_API_KEY"

A 200 with "success": true means you’re connected. A 401 means the key is wrong or truncated; a 403 means it’s valid but lacks the permission. See Errors. Every response uses the same envelope:

{
  "success": true,
  "message": "Calls retrieved successfully",
  "data": {}
}

Branch on the HTTP status and success — never on the text of message.

3. Create a contact and call them

The common pattern: a lead arrives in your system, you push it to Recepta.ai and have an agent call it immediately.

# Create the contact
curl -X POST https://api.recepta.ai/api/v1/api/contacts \
  -H "x-api-key: $RECEPTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Dana",
    "lastName": "Reyes",
    "phone": "+14155551234",
    "source": "API",
    "tags": ["website-lead"]
  }'

# Call them
curl -X POST https://api.recepta.ai/api/v1/api/calls/outbound \
  -H "x-api-key: $RECEPTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toNumber": "+14155551234",
    "fromNumber": "+14155559876",
    "metadata": { "source": "website-form" }
  }'

const API = 'https://api.recepta.ai/api/v1';
const headers = {
  'x-api-key': process.env.RECEPTA_API_KEY,
  'Content-Type': 'application/json',
};

async function callNewLead(lead) {
  await fetch(`${API}/api/contacts`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      firstName: lead.firstName,
      lastName: lead.lastName,
      phone: lead.phone,      // normalized to E.164 for you
      source: 'API',
      tags: ['website-lead'],
    }),
  });

  const res = await fetch(`${API}/api/calls/outbound`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      toNumber: lead.phone,
      fromNumber: process.env.RECEPTA_FROM_NUMBER,
      metadata: { source: 'website-form' },
    }),
  });

  if (res.status === 429) {
    // Rate limit, or your plan's call allowance is exhausted.
    // The message distinguishes them.
  }
  return res.json();
}

import os, requests

API = "https://api.recepta.ai/api/v1"
headers = {
    "x-api-key": os.environ["RECEPTA_API_KEY"],
    "Content-Type": "application/json",
}

def call_new_lead(lead):
    requests.post(f"{API}/api/contacts", headers=headers, json={
        "firstName": lead["first_name"],
        "lastName": lead["last_name"],
        "phone": lead["phone"],
        "source": "API",
        "tags": ["website-lead"],
    })

    r = requests.post(f"{API}/api/calls/outbound", headers=headers, json={
        "toNumber": lead["phone"],
        "fromNumber": os.environ["RECEPTA_FROM_NUMBER"],
        "metadata": {"source": "website-form"},
    })
    r.raise_for_status()
    return r.json()

fromNumber must be one of your own provisioned numbers, and outbound calling carries calling-hour, consent, and do-not-call obligations in the called party’s jurisdiction. See Recording & consent before you automate this.

4. Receive the result

Don’t poll for the outcome. Register a webhook endpoint and subscribe to call.ended, then read the result as it happens.

import crypto from 'crypto';

app.post('/webhooks/recepta', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('X-Webhook-Signature');
  const expected = crypto
    .createHmac('sha256', process.env.RECEPTA_WEBHOOK_SECRET)
    .update(req.body, 'utf8')          // raw body, not re-serialized JSON
    .digest('hex');

  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(signature, 'hex');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body);
  enqueue(event);        // do the work off the request path
  res.sendStatus(200);   // respond fast
});

Compute the HMAC over the raw request body. Parsing and re-serializing the JSON changes whitespace and key order, and the signature will never match — this is the most common webhook integration bug.

See Webhooks for the full event list and Python/PHP verification.

Before you go to production

Handle 429 properly

Read X-RateLimit-Remaining and back off before you hit the limit; honour Retry-After when you do. Add jitter so parallel workers don’t retry in lockstep. See Rate limits.

Make webhook handling idempotent

Key on the event id and ignore duplicates. Assume any event can arrive more than once and out of order.

Scope keys per integration

One key per system, with minimum permissions. Then you can revoke one without breaking the rest — and rate limits are tracked per key, so they don’t compete.

Don't log secrets or transcripts

Keys are credentials; transcripts contain customer personal data. See Security & privacy.

Let an assistant query your workspace instead

If you want analysis rather than automation, the MCP server exposes read-only tools to AI assistants with no integration code at all.

Overview

Endpoints

Automation

1. Create a key

2. Confirm it works

3. Create a contact and call them

4. Receive the result

Before you go to production

Let an assistant query your workspace instead

​1. Create a key

​2. Confirm it works

​3. Create a contact and call them

​4. Receive the result

​Before you go to production

Let an assistant query your workspace instead

1. Create a key

2. Confirm it works

3. Create a contact and call them

4. Receive the result

Before you go to production