Custom CRM API

Overview

When a person is scheduled for an appointment in your system, send a POST request to the Rilla API. Rilla creates the appointment record and links it for analysis and coaching — either when the user submits a recording through the app, or automatically when you include a recording URL in the request. If a recording and a calendar event were created separately, you can link them after the fact with POST /custom/appointment/match.

https://api.apirilla.com

How it works

Authentication

All requests to the Custom CRM API must include a valid API key in the x-api-key request header.

POST /custom/appointment HTTP/1.1
Host: api.apirilla.com
x-api-key: YOUR_API_KEY
Content-Type: application/json

Request Headers

Obtaining an API Key

Admins and Team Managers can create API keys in Settings → Developer. Each key belongs to a single Rilla organization. See Get an API key for a quick overview.

If you don't have access to Developer settings, ask an admin on your account to create the key for you, or reach out to your Rilla account manager or customer success manager.

Your API key is enforced at the API gateway. If the x-api-key header is missing or not recognized, the request is rejected with 403 Forbidden before it reaches the application. A recognized key that isn't mapped to an active Rilla organization returns 422 Unprocessable Entity.

POST /custom/appointment

Creates a new appointment or updates an existing one. Rilla uses event_id to determine whether to insert or update.

Request Headers

Request Body

Example — Create

{
  "event_id": "appt-1234",
  "user_email": "rep@yourcompany.com",
  "start_time": "2024-06-15 14:00:00",
  "end_time": "2024-06-15 15:00:00",
  "title": "Home Estimate - Jane Smith",
  "customer": {
    "id": "cust-567",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "555-867-5309"
  },
  "result": "won",
  "price": 4500.00,
  "lead_source": "Facebook"
}

Updating an Appointment

To update an event, use the same POST endpoint. Only event_id and user_email are required. Send the full attendee_emails list on every update to keep additional attendees: omitting it or sending [] replaces the attendees with just user_email. Other omitted fields remain unchanged.

{
  "event_id": "appt-1234",
  "user_email": "rep@yourcompany.com",
  "result": "lost"
}

Multiple Attendees

When the appointment owner and the person conducting it may differ, keep the owner in user_email and include other reps in attendee_emails. Each resolved person becomes an attendee, making the appointment eligible for their recording matching and appointment selection. Send the appointment before the rep records; adding attendees does not rematch existing recordings.

{
  "event_id": "appt-1234",
  "user_email": "owner@yourcompany.com",
  "attendee_emails": ["consultant@yourcompany.com", "host@yourcompany.com"],
  "start_time": "2026-09-20 14:00:00",
  "end_time": "2026-09-20 15:00:00",
  "title": "Home Estimate - Jane Smith",
  "customer": {"id": "cust-567", "name": "Jane Smith"}
}

• Addresses are trimmed and matched case-insensitively within your API key's organization, using primary email, alternate email, then an unambiguous first.last email prefix. Duplicate addresses or aliases for the same person produce one attendee.
• With a non-empty attendee_emails list, removed and hidden users are skipped. Unresolved addresses, including the owner, are skipped with a warning in Rilla's logs. At least one person must resolve; otherwise the request returns 422 without changing the appointment. Omitting the field or sending [] retains the legacy single-rep lookup behavior.
• user_email remains required and must be a non-empty string. attendee_emails must be an array of non-empty strings; null, a single string, or invalid entries return 400.
• Every update replaces the complete attendee list. Re-send everyone who should remain, even on an outcome-only or time-only update. Send [] to return to the owner alone.
• A non-empty attendee_emails list cannot be combined with media_url (400); multi-attendee appointments are for reps recording through the app. Location-based call imports continue to use their system-managed UNASSIGNED account.

For example, this outcome-only update preserves the owner and both additional attendees from the request above:

{
  "event_id": "appt-1234",
  "user_email": "owner@yourcompany.com",
  "attendee_emails": ["consultant@yourcompany.com", "host@yourcompany.com"],
  "result": "won"
}

The API returns plain-text errors for these attendee-specific failures:

Responses

DELETE /custom/appointment/{id}

Deletes an appointment from Rilla. No request body is needed. Use this when an appointment is cancelled in your system to keep data in sync.

Path Parameters

Request Headers

Example Request

DELETE /custom/appointment/appt-1234 HTTP/1.1
Host: api.apirilla.com
x-api-key: YOUR_API_KEY

Responses

POST /custom/appointment/match

Links a calendar event Rilla already has on file for your organization to an existing Rilla conversation. Use this when a recording and a calendar event were created separately — for example, the rep recorded through the app before the appointment was pushed — and you want to associate them after the fact.

Both records must already exist. This endpoint creates and updates nothing else: it only sets the matched conversation's recording appointment_id to the calendar event. To create or update the appointment itself, use POST /custom/appointment.

Request Headers

Request Body

Example Request

POST /custom/appointment/match HTTP/1.1
Host: api.apirilla.com
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "event_id": "appt-1234",
  "conversation_id": "f1a3e9d8-2b46-4c1a-9c7e-7e4a18d2c93f"
}

Responses

On success the response body is the plain string Successfully matched conversation to event.

Data Models

Appointment Object

Customer Object

Recording Types

Code Examples

Create an Appointment

import requests

url = "https://api.apirilla.com/custom/appointment"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "event_id": "appt-1234",
    "user_email": "rep@yourcompany.com",
    "start_time": "2024-06-15 14:00:00",
    "end_time": "2024-06-15 15:00:00",
    "title": "Home Estimate - Jane Smith",
    "customer": {
        "id": "cust-567",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "phone": "555-867-5309"
    },
    "result": "won",
    "price": 4500.00,
    "lead_source": "Facebook"
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.text)

const response = await fetch('https://api.apirilla.com/custom/appointment', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event_id: 'appt-1234',
    user_email: 'rep@yourcompany.com',
    start_time: '2024-06-15 14:00:00',
    end_time: '2024-06-15 15:00:00',
    title: 'Home Estimate - Jane Smith',
    customer: { id: 'cust-567', name: 'Jane Smith' },
    result: 'won',
    price: 4500.00,
  }),
})

curl -X POST https://api.apirilla.com/custom/appointment \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "appt-1234",
    "user_email": "rep@yourcompany.com",
    "start_time": "2024-06-15 14:00:00",
    "end_time": "2024-06-15 15:00:00",
    "title": "Home Estimate - Jane Smith",
    "customer": {"id": "cust-567", "name": "Jane Smith"},
    "result": "won"
  }'

Update an Appointment

POST to the same endpoint with event_id, user_email, and the fields you want to change. For multi-attendee appointments, also re-send the full attendee_emails list on every update. Other omitted fields remain unchanged.

import requests

url = "https://api.apirilla.com/custom/appointment"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "event_id": "appt-1234",
    "user_email": "rep@yourcompany.com",
    "result": "lost"
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.text)

const response = await fetch('https://api.apirilla.com/custom/appointment', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event_id: 'appt-1234',
    user_email: 'rep@yourcompany.com',
    result: 'lost',
  }),
})

curl -X POST https://api.apirilla.com/custom/appointment \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "appt-1234", "user_email": "rep@yourcompany.com", "result": "lost"}'

Delete an Appointment

import requests

event_id = "appt-1234"
url = f"https://api.apirilla.com/custom/appointment/{event_id}"
headers = {"x-api-key": "YOUR_API_KEY"}
response = requests.delete(url, headers=headers)
print(response.status_code, response.text)

const eventId = 'appt-1234'
const response = await fetch(
  `https://api.apirilla.com/custom/appointment/${eventId}`,
  {
    method: 'DELETE',
    headers: { 'x-api-key': 'YOUR_API_KEY' },
  }
)

curl -X DELETE https://api.apirilla.com/custom/appointment/appt-1234 \
  -H "x-api-key: YOUR_API_KEY"

Match a Conversation to an Event

Link an existing conversation to a calendar event Rilla already has for your organization. Both must already exist.

import requests

url = "https://api.apirilla.com/custom/appointment/match"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "event_id": "appt-1234",
    "conversation_id": "f1a3e9d8-2b46-4c1a-9c7e-7e4a18d2c93f"
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.text)

const response = await fetch('https://api.apirilla.com/custom/appointment/match', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event_id: 'appt-1234',
    conversation_id: 'f1a3e9d8-2b46-4c1a-9c7e-7e4a18d2c93f',
  }),
})

curl -X POST https://api.apirilla.com/custom/appointment/match \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "appt-1234", "conversation_id": "f1a3e9d8-2b46-4c1a-9c7e-7e4a18d2c93f"}'

Custom API Debugger

Once your integration is sending events, you can verify them inside Rilla's web app. The Custom API Debugger lists every event we received against your API key and shows the full payload exactly as Rilla stored it. Use it to confirm field values, troubleshoot mappings, and check timestamps without needing access to logs.

Error Codes

The API returns standard HTTP status codes. On error, the response body is a plain string describing the issue.

Rate Limits

Effective Custom CRM limits depend on your API gateway usage-plan configuration. Confirm the applicable per-key quota and burst limit with Rilla before high-volume use. Requests exceeding an applicable limit can receive 429 Too Many Requests.

High-volume Usage

If your integration requires high-throughput or bulk operations, reach out to support@rilla.com before going live.

Best Practices

• Retry with exponential backoff on 429 or 5xx responses.
• Avoid polling at high frequency.
• Batch appointment creation on your side before calling the API.