The REST API: quickstart

1. Make a key

In the console, open Settings, API & AI apps. Under API keys, give the key a name (where it will be used, like "Zapier" or "Office dashboard"), pick its access and, if you like, when it expires. Copy it right away: it's shown once.

• Read only (read): every list and detail, nothing changes.
• Day-to-day work (write): also bookings, to-dos, call-backs and notes.
• Full access (admin): also the receptionist's setup, team, numbers and connections.

2. Your first request

curl https://app.julius.dealsflow.ai/api/v1/account \
  -H "Authorization: Bearer jak_your_key"

{
  "workspace": {"id": "6cff3f21-44ee-4c93-9181-09ab7b096513", "business": "Joe Plumbing",
                "timezone": "America/Chicago", "phone_number": "+13125550100"},
  "you": {"email": "joe@joeplumbing.com", "role": "owner", "acting_as": "owner"},
  "access": {"scopes": ["read", "write", "admin"], "via": "key", "name": "Zapier"}
}

3. Common requests

# Missed calls, newest first
curl "https://app.julius.dealsflow.ai/api/v1/calls?show=missed" -H "Authorization: Bearer $KEY"

# One call: summary, transcript, the caller and what they asked for
curl https://app.julius.dealsflow.ai/api/v1/calls/CALL_ID \
  -H "Authorization: Bearer $KEY"

# What needs doing: to-dos, bookings to confirm, questions callers asked
curl https://app.julius.dealsflow.ai/api/v1/todo -H "Authorization: Bearer $KEY"

# Confirm a booking (the caller is emailed)
curl -X POST https://app.julius.dealsflow.ai/api/v1/bookings/BOOKING_ID/confirm \
  -H "Authorization: Bearer $KEY"

# Weekly opening hours (24-hour ranges, the business's time zone)
curl -X PUT https://app.julius.dealsflow.ai/api/v1/hours -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"mon": ["08:00-17:00"], "tue": ["08:00-17:00"], "fri": ["08:00-14:00"]}'

# Teach the receptionist an answer
curl -X PUT https://app.julius.dealsflow.ai/api/v1/answers -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Do you service tankless water heaters?", "answer": "No, we only work on tank water heaters."}'

Every operation, its inputs and the access it needs are on the reference page. The full machine-readable description is https://app.julius.dealsflow.ai/api/v1/openapi.json (OpenAPI 3.1, no key needed), which tools like Postman, Insomnia and OpenAPI code generators can import.

Python

import os
import requests

API = "https://app.julius.dealsflow.ai/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['JULIUS_KEY']}"

def call(method, path, **kwargs):
    reply = session.request(method, API + path, timeout=30, **kwargs)
    if reply.status_code >= 400:
        raise RuntimeError(reply.json()["error"]["message"])
    return reply.json()

# Every call, page by page
calls, before = [], None
while True:
    page = call("GET", "/calls", params={"before": before} if before else {})
    calls += page["calls"]
    before = page["next"]
    if not before:
        break
print(len(calls), "calls")

JavaScript

const API = "https://app.julius.dealsflow.ai/api/v1";

async function julius(method, path, body) {
  const reply = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${process.env.JULIUS_KEY}`, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await reply.json();
  if (!reply.ok) throw new Error(data.error.message);
  return data;
}

const todo = await julius("GET", "/todo");
for (const booking of todo.bookings_to_confirm) console.log(booking);

Keep keys on your server. The API answers browsers too (open CORS), but a key in a web page can be read by anyone who opens it.

Errors

Every error has the same shape, with a message you can show to a person:

{"error": {"status": 422, "message": "Opening ranges look like 09:00-17:00"}}

Paging, limits and good habits

• Calls come 30 at a time, newest first. Pass the next value as before for the next page; next is null on the last page.
• Events come oldest first. Keep the next value and pass it as after to get only what's new. See the events feed.
• Rate limits: 120 requests a minute per key, 4 at the same time per key and 8 per workspace. Questions to the CRM assistant (POST /ask): 30 an hour.
• Safe to repeat: PUT and most PATCH requests set a value, so sending one twice does no harm. POST requests that send something (confirming a booking emails the caller) should not be retried blindly.
• Changes are recorded: every change made with a key is listed in the console's activity log with the key's name.
• Download everything: GET /export (full access) returns every call, contact, booking and message as CSV files in a ZIP.