{ "openapi": "3.1.0", "info": { "title": "Oneanswer API", "version": "1.4.0", "description": "Read calls, appointments, contacts and leads, and book appointments, for one business. See https://beta.ittypingtest.io/developers." }, "servers": [ { "url": "https://beta.ittypingtest.io" } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A token from Dashboard → API tokens." } }, "responses": { "Unauthorised": { "description": "Unauthenticated.", "content": { "application/json": { "example": { "message": "Unauthenticated." } } } }, "Forbidden": { "description": "Invalid ability provided.", "content": { "application/json": { "example": { "message": "Invalid ability provided." } } } }, "Invalid": { "description": "The request was invalid.", "content": { "application/json": { "example": { "message": "The q field is required.", "errors": { "q": [ "The q field is required." ] } } } } }, "TooMany": { "description": "Too Many Attempts.", "content": { "application/json": { "example": { "message": "Too Many Attempts." } } } } } }, "paths": { "/api/v1/tenant": { "get": { "operationId": "tenant", "summary": "The business", "description": "The business this token belongs to: name, time zone, plan. Needs the `tenant:read` permission on the token.", "tags": [ "Business" ], "security": [ { "bearer": [] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "01JC8Z…", "type": "tenant", "attributes": { "name": "Northside Hair Studio", "status": "active", "timezone": "Europe/London", "industry": "salon", "phone": "+441614960000", "website": "https://example.com", "trial_ends_at": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } } } }, "/api/v1/team": { "get": { "operationId": "team", "summary": "Team members", "description": "Everyone on the business’s team, with their role. Needs the `team:read` permission on the token.", "tags": [ "Business" ], "security": [ { "bearer": [] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "type": "member", "attributes": { "name": "Priya Shah", "email": "priya@example.com", "role": "manager", "joined_at": "2026-09-02T08:15:00Z" } } ], "meta": { "count": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } } } }, "/api/v1/calls": { "get": { "operationId": "calls.index", "summary": "List calls", "description": "Newest first, with the summary. Needs the `calls:read` permission on the token.", "tags": [ "Calls" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "outcome", "in": "query", "description": "Only calls with this outcome.", "schema": { "type": "string", "enum": [ "resolved", "booked", "rescheduled", "booking_cancelled", "lead_captured", "transferred", "message_taken", "abandoned", "forwarded", "limit_reached", "error", "voicemail", "declined", "opted_out" ] } }, { "name": "since", "in": "query", "description": "Only calls that started at or after this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "description": "Results per page, 1–100 (default 25).", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "description": "From links.next of the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "01JD2K…", "type": "call", "attributes": { "caller": "+447700900123", "called": "+441614960000", "outcome": "booked", "status": "completed", "started_at": "2026-10-21T09:41:12Z", "ended_at": "2026-10-21T09:43:40Z", "duration_seconds": 148, "transferred_to": null, "summary": "Sam booked a men’s cut for Thursday at 2pm." } } ], "links": { "next": "https://app.oneanswer.io/api/v1/calls?cursor=eyJ…", "prev": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } } } }, "/api/v1/calls/{call}": { "get": { "operationId": "calls.show", "summary": "One call", "description": "Add include=transcript for everything that was said. Needs the `calls:read` permission on the token.", "tags": [ "Calls" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "call", "in": "path", "required": true, "description": "The call ID.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Extra data to include.", "schema": { "type": "string", "enum": [ "transcript" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "01JD2K…", "type": "call", "attributes": { "caller": "+447700900123", "called": "+441614960000", "outcome": "booked", "status": "completed", "started_at": "2026-10-21T09:41:12Z", "ended_at": "2026-10-21T09:43:40Z", "duration_seconds": 148, "transferred_to": null, "summary": "Sam booked a men’s cut for Thursday at 2pm.", "transcript": [ { "role": "assistant", "text": "Hello, Northside Hair Studio, Ava speaking.", "at": "2026-10-21T09:41:13Z" }, { "role": "caller", "text": "Hi, can I book a cut for Thursday?", "at": "2026-10-21T09:41:18Z" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } } } }, "/api/v1/search": { "get": { "operationId": "search", "summary": "Search what customers said", "description": "Searches call transcripts and summaries, website chats and texts. Every word must appear; use \"quotes\" for a phrase and -word to leave one out. Results follow the token owner’s permissions. Needs the `calls:read` permission on the token.", "tags": [ "Calls" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "What to search for.", "schema": { "type": "string" } }, { "name": "channels", "in": "query", "description": "Comma-separated: calls, chats, texts (default all).", "schema": { "type": "string" } }, { "name": "speaker", "in": "query", "description": "customer = only what the customer said.", "schema": { "type": "string", "enum": [ "customer", "anyone" ] } }, { "name": "from", "in": "query", "description": "From this day (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Up to this day.", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "1–100 (default 25).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "type": "call", "id": "01JD2K…", "at": "2026-10-21T10:42:00+01:00", "title": "Call from Sam Taylor", "snippets": [ "Caller: Do you take NHS patients?" ] } ], "query": { "words": [ "nhs" ], "excluded": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } } } }, "/api/v1/appointments": { "get": { "operationId": "appointments.index", "summary": "List appointments", "description": "In start time order. Needs the `appointments:read` permission on the token.", "tags": [ "Appointments" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "from", "in": "query", "description": "Starting at or after.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "Starting before.", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "description": "Only this status.", "schema": { "type": "string", "enum": [ "booked", "completed", "no_show", "cancelled" ] } }, { "name": "per_page", "in": "query", "description": "Results per page, 1–100 (default 25).", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "description": "From links.next of the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "01JD3M…", "type": "appointment", "attributes": { "reference": "K7P4M", "status": "booked", "service": "Men’s haircut", "calendar": "Sam", "starts_at": "2026-10-22T14:00:00+01:00", "ends_at": "2026-10-22T14:30:00+01:00", "source": "call", "customer": { "name": "Sam Taylor", "phone": "+447700900123", "email": null } } } ], "links": { "next": null, "prev": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } } }, "post": { "operationId": "appointments.store", "summary": "Book an appointment", "description": "Checked against opening hours, other bookings and time off, exactly like a phone booking. Send an Idempotency-Key header so a retry never books twice. Needs the `appointments:write` permission on the token.", "tags": [ "Appointments" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "8–80 letters, digits or - _ : . (recommended).", "schema": { "type": "string" } } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "01JD3M…", "type": "appointment", "attributes": { "reference": "K7P4M", "status": "booked", "service": "Men’s haircut", "calendar": "Sam", "starts_at": "2026-10-22T14:00:00+01:00", "ends_at": "2026-10-22T14:30:00+01:00", "source": "call", "customer": { "name": "Sam Taylor", "phone": "+447700900123", "email": null } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "service", "start", "customer" ], "properties": { "service": { "type": "string", "description": "Service ID." }, "start": { "type": "string", "format": "date-time", "description": "A free start time from /availability." }, "calendar": { "type": "string", "description": "Calendar ID (optional)." }, "customer": { "type": "object", "description": "{ \"name\": required, \"phone\", \"email\" }" }, "notes": { "type": "string", "description": "Up to 2,000 characters." } } } } } } } }, "/api/v1/availability": { "get": { "operationId": "availability", "summary": "Free times", "description": "Bookable start times for a service on one day, using the same rules as the receptionist. Needs the `appointments:read` permission on the token.", "tags": [ "Appointments" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "service", "in": "query", "required": true, "description": "Service ID.", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": true, "description": "YYYY-MM-DD in the business’s time zone.", "schema": { "type": "string", "format": "date" } }, { "name": "calendar", "in": "query", "description": "Only this calendar (ID).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "start": "2026-10-22T10:00:00+01:00", "end": "2026-10-22T10:30:00+01:00", "calendar": "01JB…" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } } } }, "/api/v1/appointments/{appointment}": { "get": { "operationId": "appointments.show", "summary": "One appointment", "description": "Needs the `appointments:read` permission on the token.", "tags": [ "Appointments" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "appointment", "in": "path", "required": true, "description": "The appointment ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "01JD3M…", "type": "appointment", "attributes": { "reference": "K7P4M", "status": "booked", "service": "Men’s haircut", "calendar": "Sam", "starts_at": "2026-10-22T14:00:00+01:00", "ends_at": "2026-10-22T14:30:00+01:00", "source": "call", "customer": { "name": "Sam Taylor", "phone": "+447700900123", "email": null } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } } } }, "/api/v1/appointments/{appointment}/cancel": { "post": { "operationId": "appointments.cancel", "summary": "Cancel an appointment", "description": "The customer is told, as with any cancellation. Needs the `appointments:write` permission on the token.", "tags": [ "Appointments" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "appointment", "in": "path", "required": true, "description": "The appointment ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "id": "01JD3M…", "type": "appointment", "attributes": { "reference": "K7P4M", "status": "cancelled", "service": "Men’s haircut", "calendar": "Sam", "starts_at": "2026-10-22T14:00:00+01:00", "ends_at": "2026-10-22T14:30:00+01:00", "source": "call", "customer": { "name": "Sam Taylor", "phone": "+447700900123", "email": null } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "reason": { "type": "string", "description": "Up to 200 characters." } } } } } } } }, "/api/v1/contacts": { "get": { "operationId": "contacts.index", "summary": "List contacts", "description": "Newest first. Filter by an exact phone number to look someone up. Needs the `crm:read` permission on the token.", "tags": [ "Contacts and leads" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "phone", "in": "query", "description": "E.164, e.g. +447700900123.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Results per page, 1–100 (default 25).", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "description": "From links.next of the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "01JC…", "type": "contact", "attributes": { "name": "Sam Taylor", "phone": "+447700900123", "email": "sam@example.com", "last_contacted_at": "2026-10-21T09:42:00Z" } } ], "links": { "next": null, "prev": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } } } }, "/api/v1/leads": { "get": { "operationId": "leads.index", "summary": "List leads", "description": "Enquiries the receptionist qualified, newest first. Needs the `crm:read` permission on the token.", "tags": [ "Contacts and leads" ], "security": [ { "bearer": [] } ], "parameters": [ { "name": "status", "in": "query", "description": "Only this status.", "schema": { "type": "string", "enum": [ "new", "qualified", "unqualified", "contacted", "won", "lost" ] } }, { "name": "per_page", "in": "query", "description": "Results per page, 1–100 (default 25).", "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "description": "From links.next of the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "id": "01JC…", "type": "lead", "attributes": { "status": "qualified", "score": 80, "interest": "Kitchen refit quote", "contact": { "name": "Sam Taylor", "phone": "+447700900123" } } } ], "links": { "next": null, "prev": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/TooMany" } } } } }, "webhooks": { "appointment.booked": { "post": { "summary": "Appointment booked", "requestBody": { "content": { "application/json": { "example": { "id": "01JE…", "type": "appointment.booked", "created_at": "2026-10-21T09:43:41+01:00", "data": { "reference": "K7P4M", "status": "booked", "service": "Men’s haircut", "calendar": "Sam", "starts_at": "2026-10-22T14:00:00+01:00", "ends_at": "2026-10-22T14:30:00+01:00", "source": "call", "customer": { "name": "Sam Taylor", "phone": "+447700900123", "email": null } } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds." } } } }, "appointment.rescheduled": { "post": { "summary": "Appointment moved", "requestBody": { "content": { "application/json": { "example": { "id": "01JE…", "type": "appointment.rescheduled", "created_at": "2026-10-21T09:43:41+01:00", "data": { "reference": "K7P4M", "status": "booked", "service": "Men’s haircut", "calendar": "Sam", "starts_at": "2026-10-22T14:00:00+01:00", "ends_at": "2026-10-22T14:30:00+01:00", "source": "call", "customer": { "name": "Sam Taylor", "phone": "+447700900123", "email": null } } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds." } } } }, "appointment.cancelled": { "post": { "summary": "Appointment cancelled", "requestBody": { "content": { "application/json": { "example": { "id": "01JE…", "type": "appointment.cancelled", "created_at": "2026-10-21T09:43:41+01:00", "data": { "reference": "K7P4M", "status": "booked", "service": "Men’s haircut", "calendar": "Sam", "starts_at": "2026-10-22T14:00:00+01:00", "ends_at": "2026-10-22T14:30:00+01:00", "source": "call", "customer": { "name": "Sam Taylor", "phone": "+447700900123", "email": null } } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds." } } } }, "appointment.completed": { "post": { "summary": "Appointment completed", "requestBody": { "content": { "application/json": { "example": { "id": "01JE…", "type": "appointment.completed", "created_at": "2026-10-21T09:43:41+01:00", "data": { "reference": "K7P4M", "status": "booked", "service": "Men’s haircut", "calendar": "Sam", "starts_at": "2026-10-22T14:00:00+01:00", "ends_at": "2026-10-22T14:30:00+01:00", "source": "call", "customer": { "name": "Sam Taylor", "phone": "+447700900123", "email": null } } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds." } } } }, "lead.created": { "post": { "summary": "New lead", "requestBody": { "content": { "application/json": { "example": { "id": "01JE…", "type": "lead.created", "created_at": "2026-10-21T09:43:41+01:00", "data": { "id": "01JC…", "status": "qualified", "score": 80, "interest": "Kitchen refit quote", "contact": { "name": "Sam Taylor", "phone": "+447700900123" } } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds." } } } }, "lead.updated": { "post": { "summary": "Lead status changed", "requestBody": { "content": { "application/json": { "example": { "id": "01JE…", "type": "lead.updated", "created_at": "2026-10-21T09:43:41+01:00", "data": { "id": "01JC…" } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds." } } } }, "call.completed": { "post": { "summary": "Call finished (with summary)", "requestBody": { "content": { "application/json": { "example": { "id": "01JE…", "type": "call.completed", "created_at": "2026-10-21T09:43:41+01:00", "data": { "caller": "+447700900123", "called": "+441614960000", "outcome": "booked", "status": "completed", "started_at": "2026-10-21T09:41:12Z", "ended_at": "2026-10-21T09:43:40Z", "duration_seconds": 148, "transferred_to": null, "summary": "Sam booked a men’s cut for Thursday at 2pm." } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds." } } } }, "message.taken": { "post": { "summary": "Message taken for the team", "requestBody": { "content": { "application/json": { "example": { "id": "01JE…", "type": "message.taken", "created_at": "2026-10-21T09:43:41+01:00", "data": { "id": "01JC…", "caller_name": "Sam Taylor", "caller_phone": "+447700900123", "message": "Please call me back about the quote.", "reason": "callback", "call_id": "01JD…" } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds." } } } }, "chat.completed": { "post": { "summary": "Website chat finished", "requestBody": { "content": { "application/json": { "example": { "id": "01JE…", "type": "chat.completed", "created_at": "2026-10-21T09:43:41+01:00", "data": { "id": "01JC…", "status": "closed", "outcome": "answered", "visitor_name": "Jo", "visitor_email": "jo@example.com", "visitor_phone": null, "page_url": "https://example.com/prices", "messages": 4, "summary": "Jo asked about parking.", "started_at": "2026-10-21T09:40:00+01:00" } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds." } } } }, "outbound.completed": { "post": { "summary": "Outbound call finished", "requestBody": { "content": { "application/json": { "example": { "id": "01JE…", "type": "outbound.completed", "created_at": "2026-10-21T09:43:41+01:00", "data": { "id": "01JC…", "purpose": "reminder", "to": "+447700900123", "status": "completed", "result": "resolved", "attempts": 1, "call_id": "01JD…", "contact": { "id": "01JC…", "name": "Sam Taylor", "phone": "+447700900123", "email": null } } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds." } } } }, "keyword.spotted": { "post": { "summary": "Keyword alert matched", "requestBody": { "content": { "application/json": { "example": { "id": "01JE…", "type": "keyword.spotted", "created_at": "2026-10-21T09:43:41+01:00", "data": { "id": "01JC…", "alert": "Complaints", "phrase": "not happy", "channel": "calls", "snippet": "I’m really not happy with my crown", "call_id": "01JD…", "conversation_id": null } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds." } } } } } }