A REST API for your calls, contacts and text messages

Three steps to a first request

1. 01

   Create a key

   In the portal, Settings → API Keys. Name it, pick an expiry and copy it: the key is shown once and stored only as a hash.

2. 02

   Call an endpoint

   Send the key as a bearer token. GET /api/v1/me answers with your organization, the scopes the key holds and its rate limit, so it is the call to make first.

3. 03

   Subscribe to events

   Settings → Webhooks: add an https address on a host your organization has approved, tick the events you want, from call.completed to survey.responded, and keep the signing secret it shows once.

• { }

  OpenAPI 3.1

  openapi.json

  GET /api/v1/openapi.json

  Generated from the schemas the API validates against, and readable without a key.

  Open the spec →
• $_

  curl

  shell

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

  Checks the key: the organization, its scopes and the rate limit come back.

• JS

  JavaScript

  fetch

  const res = await fetch("https://api.inboundcx.com/api/v1/contacts?includeAutoCreated=false&limit=50", {
    headers: { Authorization: `Bearer ${process.env.API_KEY}` },
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  const { contacts, nextCursor } = await res.json();

  Lists the contacts a person entered, 50 at a time, with a cursor for the next page.

• PY

  Python

  requests

  import os
  import requests
  
  r = requests.post(
      "https://api.inboundcx.com/api/v1/messages",
      headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
      json={"to": "+15145550142", "body": "Your technician arrives between 9 and 11."},
      timeout=10,
  )
  r.raise_for_status()
  message = r.json()["message"]

  Sends a text as the organization, billed at its carrier rate.

• #

  Webhook signatures

  HMAC-SHA256

  import crypto from "node:crypto";
  
  // Deprecated names with the same values: x-ringfully-timestamp, x-ringfully-signature.
  const timestamp = req.get("x-inboundcx-timestamp") ?? "";
  const signature = req.get("x-inboundcx-signature") ?? "";
  const expected = crypto
    .createHmac("sha256", process.env.INBOUNDCX_WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const valid =
    expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)) &&
    Math.abs(Date.now() - Number(timestamp)) < 5 * 60 * 1000;

  Reads x-inboundcx-timestamp and x-inboundcx-signature; x-ringfully-timestamp and x-ringfully-signature Deprecated still arrive with the same values.

• rk

  API keys

  Pro and Business

  Authorization: Bearer rk_live_…

  Created in Settings → API Keys. Revoke one there and it stops working on its next request.

  Open API Keys in the portal →

• Every call logged in your own system

  Receive call.completed when a call ends, or page back through the history, and file each call against the right customer.

  GET /api/v1/calls

• One contact list, kept up to date

  Create, rename and remove contacts from the software you already use. A number your team has already called is named, not duplicated.

  POST /api/v1/contacts

• Texts sent from your own tools

  Send a reminder or a job update from your booking or dispatch software, and read the replies conversation by conversation.

  POST /api/v1/messages