{ "openapi": "3.1.0", "info": { "title": "LineHQ API", "version": "1.0", "summary": "Read and act on your LineHQ account from your own systems.", "description": "The LineHQ Public API lets your own systems read your account, numbers, routing, calls, transcripts, text messages, inbox, analytics and billing, keep the contact directory in step, and manage webhooks. Authenticate every request with an API key from the portal's API keys page, sent in the `Authorization: Bearer` header. Responses are JSON. Records are addressed by their opaque `public_id`.", "contact": { "name": "LineHQ support", "url": "https://linehq.co.uk/contact" } }, "servers": [ { "url": "https://app.linehq.co.uk/api/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Account", "description": "Who the key belongs to and the account's prepaid balance." }, { "name": "Numbers", "description": "The account's phone numbers and how each one answers calls." }, { "name": "Calls", "description": "Calls, their recordings, transcripts and AI summaries." }, { "name": "Text messages", "description": "Text-message conversations on the account's numbers." }, { "name": "Contacts", "description": "The contact directory LineHQ names callers from. Keep it in step with your own system." }, { "name": "To-dos", "description": "Follow-ups the AI summary finds in calls." }, { "name": "Notifications", "description": "The notifications behind each user's bell in the portal." }, { "name": "Message slips", "description": "Messages callers leave with the virtual receptionist." }, { "name": "Job requests", "description": "Jobs picked out of message slips and calls." }, { "name": "Blocked callers", "description": "Numbers whose calls the account rejects or sends straight to voicemail." }, { "name": "Analytics", "description": "Call totals over time." }, { "name": "Billing", "description": "Movements on the prepaid balance, and receipts." }, { "name": "Webhooks", "description": "Webhook endpoints LineHQ posts events to, and their deliveries. Owners only, with an API key holding the `webhooks:manage` permission. Adding an endpoint, sending a test and resending need the Integrations add-on; the rest keep working after it lapses, so an owner can tidy up." } ], "paths": { "/me": { "get": { "operationId": "getMe", "tags": [ "Account" ], "summary": "The key's account, user and permissions", "description": "Who this API key belongs to, the permissions it holds, and the private channel to subscribe to for live events. Call it first to check a key works.", "x-linehq-capability": null, "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "responses": { "200": { "description": "The key's identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" }, "example": { "tenant": { "name": "Acme Plumbing Ltd", "status": "active" }, "user": { "name": "Sam Patel", "email": "sam@acmeplumbing.co.uk", "role": "owner" }, "abilities": [ "read", "contacts:read" ], "can_transcribe": false, "realtime": { "enabled": true, "channel": "private-tenant.4821", "key": "linehq", "host": "app.linehq.co.uk", "port": 443, "scheme": "https" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/balance": { "get": { "operationId": "getBalance", "tags": [ "Account" ], "summary": "The prepaid balance", "description": "The account's prepaid wallet balance, in pence.", "x-linehq-capability": null, "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "responses": { "200": { "description": "The balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "example": { "balance_pence": 2500, "currency": "GBP" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/numbers": { "get": { "operationId": "listNumbers", "tags": [ "Numbers" ], "summary": "List numbers", "description": "Every number on the account that hasn't been released, ordered by number.", "x-linehq-capability": null, "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "responses": { "200": { "description": "The account's numbers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NumberSummary" } } } }, "example": { "data": [ { "public_id": "8kQ2mVn4Lr7Tz1Xc9Bw3Hd6Fs0Jy5Pa2", "e164": "+442035550123", "label": "Sales", "status": "assigned", "sms_capable": true, "sms_ready": true, "cli_eligible": true, "is_default_caller_id": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/numbers/{number}": { "get": { "operationId": "getNumber", "tags": [ "Numbers" ], "summary": "Get a number", "description": "One number, with its business, caller ID and text-message status.", "x-linehq-capability": null, "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "$ref": "#/components/parameters/Number" } ], "responses": { "200": { "description": "The number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Number" }, "example": { "public_id": "8kQ2mVn4Lr7Tz1Xc9Bw3Hd6Fs0Jy5Pa2", "e164": "+442035550123", "label": "Sales", "status": "assigned", "ownership": "platform", "business_profile": { "public_id": "Vb7Nq1Zr4Kx8Lm2Tc6Wd0Hs3Jf9Pg5Ya", "name": "Acme Plumbing" }, "release_at": null, "sms_capable": true, "sms_ready": true, "cli_eligible": true, "cli_verified": false, "is_default_caller_id": true, "forward_cli": { "mode": "auto", "shows": "own", "own_e164": "+442035550123", "platform_e164": null, "own_available": true } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/numbers/{number}/routing": { "get": { "operationId": "getNumberRouting", "tags": [ "Numbers" ], "summary": "Get a number's routing", "description": "How a number answers calls: the default route, any scheduled routes (the first matching window wins), and a temporary override while one is set. Read-only; routing is changed in the portal or the LineHQ app.", "x-linehq-capability": null, "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "$ref": "#/components/parameters/Number" } ], "responses": { "200": { "description": "The number's routing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberRouting" }, "example": { "number": { "public_id": "8kQ2mVn4Lr7Tz1Xc9Bw3Hd6Fs0Jy5Pa2", "e164": "+442035550123", "status": "assigned", "voicemail_transcription_enabled": true, "call_transcription_enabled": false, "privacy_mode_enabled": false }, "default": { "mode": "forward", "recording_enabled": true, "voicemail_fallback": true, "whisper": false, "ai_cover": "off", "forward_targets": [ { "kind": "pstn", "e164": "+447700900001", "staff_label": "Sam", "ring_seconds": 25 } ], "ivr": { "options": [] } }, "schedules": [ { "name": "Weekends", "windows": [ { "days": [ 6, 7 ], "start": "09:00", "end": "17:30" } ], "mode": "voicemail", "recording_enabled": false, "voicemail_fallback": false, "whisper": false, "ai_cover": "off", "forward_targets": [], "ivr": { "options": [] } } ], "override": null } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/calls": { "get": { "operationId": "listCalls", "tags": [ "Calls" ], "summary": "List calls", "description": "The account's calls, newest first, each with its AI summary once one exists. Calls our call protection filtered out are left out unless you ask for them with `activity`.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "name": "activity", "in": "query", "description": "`business` (the default) for real calls, `filtered` for calls call protection screened out, or `all`.", "schema": { "type": "string", "enum": [ "business", "filtered", "all" ] } }, { "name": "search", "in": "query", "description": "Part of the caller's or the dialled number, as international digits, or of the caller's name.", "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "`today`, `7d`, `30d`, `month` (this calendar month), or `custom` with `date_from` and `date_to`.", "schema": { "type": "string", "enum": [ "all", "today", "7d", "30d", "month", "custom" ] } }, { "name": "date_from", "in": "query", "description": "With `period=custom`, the first day to include (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "description": "With `period=custom`, the last day to include (YYYY-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "description": "Only calls with this outcome.", "schema": { "$ref": "#/components/schemas/CallOutcome" } }, { "name": "sentiment", "in": "query", "description": "Only calls whose summary has this sentiment.", "schema": { "type": "string", "enum": [ "positive", "neutral", "negative" ] } }, { "name": "urgency", "in": "query", "description": "Only calls whose summary has this urgency.", "schema": { "type": "string", "enum": [ "low", "normal", "high" ] } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "A page of calls.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Call" } } } } ] }, "example": { "data": [ { "public_id": "Qm4Tz8Kc1Lp6Wr3Nx9Bv2Hd7Fs5Jy0Ga", "from": "+447700900123", "caller_display_name": "Jo Smith", "to": "+442035550123", "to_name": "Sales", "direction": "inbound", "disposition": "answered", "started_at": "2026-10-14T09:30:12+01:00", "forward_seconds": 184, "total_rated_amount_pence": 0, "recording_public_id": "Rk3Lm8Nq2Tz6Vb1Xc5Wd9Hs4Jf0Pg7Ya", "transcript": { "status": "completed", "summary_status": "completed", "summary": "Jo from Harbour Cafe needs a boiler repair today.", "intent": "Book a boiler repair", "sentiment": "neutral", "urgency": "high", "action_items": [ "Call Jo back to book a visit today" ], "callback_number": "+447700900123" } } ], "current_page": 1, "last_page": 1, "per_page": 25, "total": 1, "next_page_url": null, "prev_page_url": null } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/calls/{call}": { "get": { "operationId": "getCall", "tags": [ "Calls" ], "summary": "Get a call", "description": "One call, in the same shape as a row of List calls.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "$ref": "#/components/parameters/Call" } ], "responses": { "200": { "description": "The call.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Call" }, "example": { "public_id": "Qm4Tz8Kc1Lp6Wr3Nx9Bv2Hd7Fs5Jy0Ga", "from": "+447700900123", "caller_display_name": "Jo Smith", "to": "+442035550123", "to_name": "Sales", "direction": "inbound", "disposition": "answered", "started_at": "2026-10-14T09:30:12+01:00", "forward_seconds": 184, "total_rated_amount_pence": 0, "recording_public_id": "Rk3Lm8Nq2Tz6Vb1Xc5Wd9Hs4Jf0Pg7Ya", "transcript": { "status": "completed", "summary_status": "completed", "summary": "Jo from Harbour Cafe needs a boiler repair today.", "intent": "Book a boiler repair", "sentiment": "neutral", "urgency": "high", "action_items": [ "Call Jo back to book a visit today" ], "callback_number": "+447700900123" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/calls/{call}/transcribe": { "post": { "operationId": "transcribeCall", "tags": [ "Calls" ], "summary": "Transcribe a call", "description": "Start a transcription and AI summary of a recorded call. It is paid: minutes come from the plan's allowance, then any prepaid transcription bundle, then the prepaid balance, and they count towards the account's daily spending limit. Needs a key with the `transcribe` permission, which only an owner, or a member the owner allows to start transcriptions, can create. It returns straight away; read the summary from Get a call once `summary_status` is `completed`. Asking again for a call already transcribed costs nothing.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "transcribe", "x-linehq-account-role": "any", "x-linehq-platform-switch": "transcription", "parameters": [ { "$ref": "#/components/parameters/Call" } ], "responses": { "202": { "description": "Queued, or already done.", "content": { "application/json": { "schema": { "type": "object", "required": [ "call_public_id", "status", "summary_status" ], "properties": { "call_public_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/TranscriptStatus" }, "summary_status": { "$ref": "#/components/schemas/SummaryStatus" } } }, "example": { "call_public_id": "Qm4Tz8Kc1Lp6Wr3Nx9Bv2Hd7Fs5Jy0Ga", "status": "pending", "summary_status": "pending" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "402": { "description": "The prepaid balance can't cover it, or it would pass the account's daily spending limit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "estimate" ], "properties": { "message": { "type": "string" }, "estimate": { "$ref": "#/components/schemas/TranscriptionEstimate" } } }, "example": { "message": "Not enough credit to transcribe this call. Please top up.", "estimate": { "available": true, "minutes": 4, "cost_pence": 16, "rate_pence_per_min": 4, "within_allowance": false, "bundle_minutes": 0, "balance_pence": 10, "affordable": false, "existing_status": null } } } } }, "403": { "description": "The key lacks the `transcribe` permission, its user may no longer start transcriptions, or the account's plan doesn't include transcription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Transcription is not available on your current package." } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The call has no recording.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "This call has no recording to transcribe." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/recordings/{recording}/stream-url": { "get": { "operationId": "getRecordingLink", "tags": [ "Calls" ], "summary": "Get a recording link", "description": "A signed link to a call's recording audio, valid for 10 minutes. Ask for a new one each time you play or download it.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "$ref": "#/components/parameters/Recording" } ], "responses": { "200": { "description": "The link.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } } }, "example": { "url": "https://app.linehq.co.uk/media/recordings/Rk3Lm8Nq2Tz6Vb1Xc5Wd9Hs4Jf0Pg7Ya?expires=1760450400&signature=0f3c9b", "expires_at": "2026-10-14T14:00:00+01:00" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/recordings/{recording}/transcript": { "get": { "operationId": "getTranscript", "tags": [ "Calls" ], "summary": "Get a transcript", "description": "The full transcript of a recording, with timed, speaker-labelled segments and the AI summary. An empty object means the recording hasn't been transcribed.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": "transcription", "parameters": [ { "$ref": "#/components/parameters/Recording" } ], "responses": { "200": { "description": "The transcript, or `{}`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Transcript" }, { "type": "object", "maxProperties": 0 } ] }, "example": { "status": "completed", "text": "Hi, it's Jo from Harbour Cafe. Our boiler's stopped working, could someone come out today?", "language": "en", "minutes": 1, "rated_amount_pence": 0, "summary_status": "completed", "summary": "Jo from Harbour Cafe needs a boiler repair today.", "segments": [ { "start": 0, "end": 6.4, "speaker": "customer", "text": "Hi, it's Jo from Harbour Cafe. Our boiler's stopped working, could someone come out today?" } ], "intent": "Book a boiler repair", "sentiment": "neutral", "urgency": "high", "action_items": [ "Call Jo back to book a visit today" ], "callback_number": "+447700900123" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/recordings/{recording}/transcript/estimate": { "get": { "operationId": "getTranscriptionEstimate", "tags": [ "Calls" ], "summary": "Price a transcription", "description": "What transcribing this recording would cost, and whether the account can afford it now.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": "transcription", "parameters": [ { "$ref": "#/components/parameters/Recording" } ], "responses": { "200": { "description": "The price.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionEstimate" }, "example": { "available": true, "minutes": 4, "cost_pence": 0, "rate_pence_per_min": 4, "within_allowance": true, "bundle_minutes": 0, "balance_pence": 2500, "affordable": true, "existing_status": null } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/sms/conversations": { "get": { "operationId": "listSmsConversations", "tags": [ "Text messages" ], "summary": "List text conversations", "description": "The account's text-message threads, most recent first. One thread per number and other party.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "A page of conversations.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SmsConversation" } } } } ] }, "example": { "data": [ { "public_id": "Tc5Wd9Hs4Jf0Pg7YaRk3Lm8Nq2Tz6Vb1X", "counterparty_e164": "+447700900123", "number_e164": "+442035550123", "number_label": "Sales", "last_message_at": "2026-10-14T09:12:00+01:00", "last_message_preview": "Running 10 minutes late, sorry!", "unread_count": 1 } ], "current_page": 1, "last_page": 1, "per_page": 25, "total": 1, "next_page_url": null, "prev_page_url": null } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/sms/conversations/{conversation}/messages": { "get": { "operationId": "listSmsMessages", "tags": [ "Text messages" ], "summary": "List a conversation's messages", "description": "The messages in one thread, oldest first, with the thread itself.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "$ref": "#/components/parameters/Conversation" }, { "$ref": "#/components/parameters/Page" }, { "name": "per_page", "in": "query", "description": "Messages per page, up to 200. Defaults to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "A page of messages.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "required": [ "data", "conversation" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SmsMessage" } }, "conversation": { "$ref": "#/components/schemas/SmsConversation" } } } ] }, "example": { "data": [ { "conversation_public_id": "Tc5Wd9Hs4Jf0Pg7YaRk3Lm8Nq2Tz6Vb1X", "direction": "inbound", "from_e164": "+447700900123", "to_e164": "+442035550123", "body": "Running 10 minutes late, sorry!", "status": "received", "segments": 1, "received_at": "2026-10-14T09:12:00+01:00" } ], "conversation": { "public_id": "Tc5Wd9Hs4Jf0Pg7YaRk3Lm8Nq2Tz6Vb1X", "counterparty_e164": "+447700900123", "number_e164": "+442035550123", "number_label": "Sales", "last_message_at": "2026-10-14T09:12:00+01:00", "last_message_preview": "Running 10 minutes late, sorry!", "unread_count": 1 }, "current_page": 1, "last_page": 1, "per_page": 100, "total": 1, "next_page_url": null, "prev_page_url": null } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/contacts": { "get": { "operationId": "listContacts", "tags": [ "Contacts" ], "summary": "List contacts", "description": "The account's contact directory, most recently changed first. LineHQ uses it to name callers. Needs a key with the `contacts:read` permission.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "contacts:read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "name": "search", "in": "query", "description": "Part of the display name, company or email address, or of a phone number as international digits (`+44…`, not `07…`).", "schema": { "type": "string", "maxLength": 100 } }, { "name": "source", "in": "query", "description": "Only contacts from this source, such as the one your system writes them with.", "schema": { "type": "string", "maxLength": 60 } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "A page of contacts.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } } ] }, "example": { "data": [ { "public_id": "Lm8Nq2Tz6Vb1Xc5Wd9Hs4Jf0Pg7YaRk3", "display_name": "Jo Smith", "first_name": "Jo", "last_name": "Smith", "company": "Harbour Cafe", "email": "jo@harbourcafe.co.uk", "notes": null, "source": "acme-crm", "external_id": "10442", "source_created_at": null, "source_updated_at": null, "phones": [ { "e164": "+447700900123", "raw_number": "07700 900123", "label": "mobile", "is_primary": true } ], "links": [], "created_at": "2026-10-01T10:00:00+01:00", "updated_at": "2026-10-14T08:45:00+01:00" } ], "current_page": 1, "last_page": 1, "per_page": 25, "total": 1, "next_page_url": null, "prev_page_url": null } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createContact", "tags": [ "Contacts" ], "summary": "Create or update a contact", "description": "Add a contact. Send `external_id` (your system's id for it) and the same record can be sent again safely: a contact with the same `source` and `external_id` is updated rather than added twice, and the answer is still `201`. Without `external_id` every request adds a new contact. Phone numbers that can't be read as a phone number are dropped. Needs a key with the `contacts:write` permission.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "contacts:write", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" }, "example": { "source": "acme-crm", "external_id": "10442", "display_name": "Jo Smith", "company": "Harbour Cafe", "email": "jo@harbourcafe.co.uk", "phones": [ { "number": "07700 900123", "label": "mobile", "is_primary": true } ] } } } }, "responses": { "201": { "description": "The contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" }, "example": { "public_id": "Lm8Nq2Tz6Vb1Xc5Wd9Hs4Jf0Pg7YaRk3", "display_name": "Jo Smith", "first_name": "Jo", "last_name": "Smith", "company": "Harbour Cafe", "email": "jo@harbourcafe.co.uk", "notes": null, "source": "acme-crm", "external_id": "10442", "source_created_at": null, "source_updated_at": null, "phones": [ { "e164": "+447700900123", "raw_number": "07700 900123", "label": "mobile", "is_primary": true } ], "links": [], "created_at": "2026-10-01T10:00:00+01:00", "updated_at": "2026-10-14T08:45:00+01:00" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/contacts/bulk-upsert": { "post": { "operationId": "bulkUpsertContacts", "tags": [ "Contacts" ], "summary": "Create or update many contacts", "description": "Up to 500 contacts at once, each matched on `source` and `external_id` like Create or update a contact. The batch is checked first, and one invalid contact rejects it all with `422`; a contact that then fails to save is counted in `failed_count` and the rest are kept. Needs a key with the `contacts:write` permission.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "contacts:write", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source", "contacts" ], "properties": { "source": { "type": "string", "maxLength": 60, "description": "Your system's name. Used for every contact that doesn't give its own." }, "contacts": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/ContactInput" } } } }, "example": { "source": "acme-crm", "contacts": [ { "external_id": "10442", "display_name": "Jo Smith", "phones": [ { "number": "+447700900123" } ] }, { "external_id": "10443", "display_name": "Priya Shah", "company": "Shah Dental", "phones": [ { "number": "020 7946 0991", "label": "office" } ] } ] } } } }, "responses": { "202": { "description": "How many were saved.", "content": { "application/json": { "schema": { "type": "object", "required": [ "imported_count", "failed_count" ], "properties": { "imported_count": { "type": "integer" }, "failed_count": { "type": "integer" } } }, "example": { "imported_count": 2, "failed_count": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/contacts/{contact}": { "put": { "operationId": "updateContact", "tags": [ "Contacts" ], "summary": "Replace a contact", "description": "Replace a contact's details and phone numbers with the ones sent. Its `source` and `external_id` stay as they were. Needs a key with the `contacts:write` permission.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "contacts:write", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "$ref": "#/components/parameters/Contact" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" }, "example": { "display_name": "Jo Smith", "company": "Harbour Cafe & Bakery", "phones": [ { "number": "+447700900123", "label": "mobile", "is_primary": true } ] } } } }, "responses": { "200": { "description": "The contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" }, "example": { "public_id": "Lm8Nq2Tz6Vb1Xc5Wd9Hs4Jf0Pg7YaRk3", "display_name": "Jo Smith", "first_name": "Jo", "last_name": "Smith", "company": "Harbour Cafe", "email": "jo@harbourcafe.co.uk", "notes": null, "source": "acme-crm", "external_id": "10442", "source_created_at": null, "source_updated_at": null, "phones": [ { "e164": "+447700900123", "raw_number": "07700 900123", "label": "mobile", "is_primary": true } ], "links": [], "created_at": "2026-10-01T10:00:00+01:00", "updated_at": "2026-10-14T08:45:00+01:00" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteContact", "tags": [ "Contacts" ], "summary": "Delete a contact", "description": "Remove a contact from the directory. Needs a key with the `contacts:write` permission.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "contacts:write", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "$ref": "#/components/parameters/Contact" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean", "enum": [ true ] } } }, "example": { "deleted": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tasks": { "get": { "operationId": "listTodos", "tags": [ "To-dos" ], "summary": "List to-dos", "description": "Follow-ups the AI summary found in the account's calls, newest first. Open ones by default.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "name": "status", "in": "query", "description": "`open` (the default), `done` or `all`.", "schema": { "type": "string", "enum": [ "open", "done", "all" ] } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "A page of to-dos.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Todo" } } } } ] }, "example": { "data": [ { "public_id": "Wd9Hs4Jf0Pg7YaRk3Lm8Nq2Tz6Vb1Xc5", "text": "Call Jo back to book a visit today", "status": "open", "callback_e164": "+447700900123", "sentiment": "neutral", "urgency": "high", "summary_snippet": "Jo from Harbour Cafe needs a boiler repair today.", "created_at": "2026-10-14T09:34:02+01:00", "updated_at": "2026-10-14T09:34:02+01:00", "completed_at": null, "done_by": null, "call": { "public_id": "Qm4Tz8Kc1Lp6Wr3Nx9Bv2Hd7Fs5Jy0Ga", "from_e164": "+447700900123", "to_e164": "+442035550123", "number_label": "Sales", "started_at": "2026-10-14T09:30:12+01:00" } } ], "current_page": 1, "last_page": 1, "per_page": 25, "total": 1, "next_page_url": null, "prev_page_url": null } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tasks/{task}": { "patch": { "operationId": "updateTodo", "tags": [ "To-dos" ], "summary": "Tick off or reopen a to-do", "description": "Mark a to-do done, recording the key's user as the one who did it, or open it again. Needs a key with the `inbox:write` permission.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "inbox:write", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "name": "task", "in": "path", "required": true, "description": "The to-do's `public_id`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "open", "done" ] } } }, "example": { "status": "done" } } } }, "responses": { "200": { "description": "The to-do.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Todo" }, "example": { "public_id": "Wd9Hs4Jf0Pg7YaRk3Lm8Nq2Tz6Vb1Xc5", "text": "Call Jo back to book a visit today", "status": "open", "callback_e164": "+447700900123", "sentiment": "neutral", "urgency": "high", "summary_snippet": "Jo from Harbour Cafe needs a boiler repair today.", "created_at": "2026-10-14T09:34:02+01:00", "updated_at": "2026-10-14T09:34:02+01:00", "completed_at": null, "done_by": null, "call": { "public_id": "Qm4Tz8Kc1Lp6Wr3Nx9Bv2Hd7Fs5Jy0Ga", "from_e164": "+447700900123", "to_e164": "+442035550123", "number_label": "Sales", "started_at": "2026-10-14T09:30:12+01:00" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/notifications": { "get": { "operationId": "listNotifications", "tags": [ "Notifications" ], "summary": "List notifications", "description": "The key's user's notifications, the same ones as the bell in the portal, newest first, with how many are unread.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "name": "unread", "in": "query", "description": "`1` for unread notifications only.", "schema": { "type": "integer", "enum": [ 0, 1 ] } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "A page of notifications.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "required": [ "data", "unread_count" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } }, "unread_count": { "type": "integer" } } } ] }, "example": { "data": [ { "id": "9b2f6c1e-3d4a-4f8b-9c7d-2e1a5b6c7d8e", "type": "missed_call", "title": "Missed call from +447700900123", "body": "To Sales, 09:30", "url": "https://app.linehq.co.uk/dashboard", "read": false, "created_at": "2026-10-14T09:31:00+01:00", "read_at": null } ], "unread_count": 1, "current_page": 1, "last_page": 1, "per_page": 25, "total": 1, "next_page_url": null, "prev_page_url": null } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/notifications/{notification}/read": { "post": { "operationId": "markNotificationRead", "tags": [ "Notifications" ], "summary": "Mark a notification read", "description": "Needs a key with the `inbox:write` permission.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "inbox:write", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "name": "notification", "in": "path", "required": true, "description": "The notification's `id`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Marked read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "read", "unread_count" ], "properties": { "id": { "type": "string" }, "read": { "type": "boolean" }, "unread_count": { "type": "integer" } } }, "example": { "id": "9b2f6c1e-3d4a-4f8b-9c7d-2e1a5b6c7d8e", "read": true, "unread_count": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/notifications/read-all": { "post": { "operationId": "markAllNotificationsRead", "tags": [ "Notifications" ], "summary": "Mark every notification read", "description": "Needs a key with the `inbox:write` permission.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "inbox:write", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "responses": { "200": { "description": "All read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "unread_count" ], "properties": { "unread_count": { "type": "integer" } } }, "example": { "unread_count": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reception-messages": { "get": { "operationId": "listMessageSlips", "tags": [ "Message slips" ], "summary": "List message slips", "description": "Messages callers left with the virtual receptionist, newest first. The recordings play through Get a recording link.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "name": "search", "in": "query", "description": "Part of the caller's number, as international digits.", "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "`all` (the default), `today`, `7d`, `30d`, `month` (this calendar month), or `custom` with `date_from` and `date_to`.", "schema": { "type": "string", "enum": [ "all", "today", "7d", "30d", "month", "custom" ] } }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "description": "`unheard` or `heard`.", "schema": { "type": "string", "enum": [ "unheard", "heard" ] } }, { "name": "sentiment", "in": "query", "schema": { "type": "string", "enum": [ "positive", "neutral", "negative" ] } }, { "name": "urgency", "in": "query", "schema": { "type": "string", "enum": [ "low", "normal", "high" ] } }, { "$ref": "#/components/parameters/Page" }, { "name": "per_page", "in": "query", "description": "Message slips per page, up to 100. Defaults to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "A page of message slips.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageSlip" } } } } ] }, "example": { "data": [ { "public_id": "Hs4Jf0Pg7YaRk3Lm8Nq2Tz6Vb1Xc5Wd9", "from_e164": "+447700900123", "department": "Sales", "received_at": "2026-10-14T18:42:00+01:00", "heard_at": null, "name_recording_public_id": "Nq2Tz6Vb1Xc5Wd9Hs4Jf0Pg7YaRk3Lm8", "message_recording_public_id": "Pg7YaRk3Lm8Nq2Tz6Vb1Xc5Wd9Hs4Jf0", "transcript_status": "completed", "caller_name": "Jo Smith", "summary_status": "completed", "sentiment": "neutral", "urgency": "normal" } ], "current_page": 1, "last_page": 1, "per_page": 20, "total": 1, "next_page_url": null, "prev_page_url": null } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/job-requests": { "get": { "operationId": "listJobRequests", "tags": [ "Job requests" ], "summary": "List job requests", "description": "Jobs the AI picked out of message slips and calls (who, what, where and when), newest first. Open ones by default.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": "job_capture", "parameters": [ { "name": "status", "in": "query", "description": "`open` (the default: `new` and `confirmed`), one status (`new`, `confirmed`, `done`, `declined`), or `all`.", "schema": { "type": "string", "enum": [ "open", "new", "confirmed", "done", "declined", "all" ] } }, { "$ref": "#/components/parameters/Page" }, { "name": "per_page", "in": "query", "description": "Job requests per page, up to 100. Defaults to 20.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "A page of job requests.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobRequest" } } } } ] }, "example": { "data": [ { "public_id": "Yk3Lm8Nq2Tz6Vb1Xc5Wd9Hs4Jf0Pg7Ra", "status": "new", "caller_name": "Jo Smith", "caller_e164": "+447700900123", "contact_e164": "+447700900123", "line_e164": "+442035550123", "line_label": "Sales", "job_type": "Boiler repair", "description": "Boiler stopped working, no hot water.", "address": "4 Harbour Street, Hull", "postcode": "HU1 1AA", "preferred_when": "Tomorrow morning", "preferred_date": "2026-10-15", "preferred_time_window": "morning", "received_at": "2026-10-14T18:43:10+01:00", "done_at": null, "done_by": null, "message_recording_public_id": "Pg7YaRk3Lm8Nq2Tz6Vb1Xc5Wd9Hs4Jf0", "call_public_id": "Qm4Tz8Kc1Lp6Wr3Nx9Bv2Hd7Fs5Jy0Ga" } ], "current_page": 1, "last_page": 1, "per_page": 20, "total": 1, "next_page_url": null, "prev_page_url": null } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/blocked-callers": { "get": { "operationId": "listBlockedCallers", "tags": [ "Blocked callers" ], "summary": "List blocked callers", "description": "Numbers the account has blocked, newest first. Each says what its calls get.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "responses": { "200": { "description": "Every blocked caller.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BlockedCaller" } } } }, "example": { "data": [ { "public_id": "Kc1Lp6Wr3Nx9Bv2Hd7Fs5Jy0GaQm4Tz8", "e164": "+447700900666", "action": "reject", "label": "Sales calls", "number": null, "created_at": "2026-10-02" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/analytics": { "get": { "operationId": "getAnalytics", "tags": [ "Analytics" ], "summary": "Call analytics", "description": "Call totals for the last 7, 30 or 90 days: outcomes, calls per day and per hour, calls per number, and the mood of summarised calls. Calls call protection filtered out are counted separately in `summary.filtered`.", "x-linehq-capability": null, "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "name": "days", "in": "query", "description": "`7`, `30` (the default) or `90`.", "schema": { "type": "integer", "enum": [ 7, 30, 90 ] } }, { "name": "number", "in": "query", "description": "Only calls to this number: its `public_id`, from List numbers. A `public_id` that names none of the account's live numbers is a `404`. `by_number` always covers every number.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The totals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Analytics" }, "example": { "days": 7, "summary": { "total": 46, "filtered": 3, "answered": 38, "missed": 5, "voicemail": 2, "blocked": 1, "answer_rate": 83, "avg_forward_seconds": 151 }, "by_day": { "2026-10-07": 4, "2026-10-08": 5, "2026-10-09": 7, "2026-10-10": 6, "2026-10-11": 2, "2026-10-12": 1, "2026-10-13": 11, "2026-10-14": 10 }, "by_hour": [ 0, 0, 0, 0, 0, 0, 0, 0, 3, 6, 7, 5, 4, 3, 5, 4, 3, 2, 0, 0, 0, 0, 0, 0 ], "by_number": [ { "public_id": "8kQ2mVn4Lr7Tz1Xc9Bw3Hd6Fs0Jy5Pa2", "e164": "+442035550123", "label": "Sales", "total": 46, "answered": 38 } ], "sentiment": { "positive": 12, "neutral": 20, "negative": 3 } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/billing/ledger": { "get": { "operationId": "listLedgerEntries", "tags": [ "Billing" ], "summary": "List balance movements", "description": "Every change to the prepaid balance, newest first.", "x-linehq-capability": null, "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "A page of balance movements.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } } } } ] }, "example": { "data": [ { "type": "charge", "amount_pence": -12, "balance_after_pence": 2488, "note": "Forwarded call 7d3e9a41-2b6c-4f85-9e17-c0a4b8d25f6e", "created_at": "2026-10-14T09:33:20+01:00" }, { "type": "topup", "amount_pence": 2500, "balance_after_pence": 2500, "note": "Calling credit", "created_at": "2026-10-01T10:00:00+01:00" } ], "current_page": 1, "last_page": 1, "per_page": 25, "total": 2, "next_page_url": null, "prev_page_url": null } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/billing/receipts": { "get": { "operationId": "listReceipts", "tags": [ "Billing" ], "summary": "List receipts", "description": "The account's last 48 payments, newest first.", "x-linehq-capability": null, "x-linehq-api-key-permission": "read", "x-linehq-account-role": "any", "x-linehq-platform-switch": null, "responses": { "200": { "description": "The receipts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Receipt" } } } }, "example": { "data": [ { "number": "LHQ-261001-K7Q2XM", "kind": "topup", "amount_pence": 2500, "description": "Calling credit", "paid_at": "2026-10-01T10:00:00+01:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "description": "The account's webhook endpoints. Owners only, with a key holding the `webhooks:manage` permission, because an endpoint's address can be a secret.", "x-linehq-capability": null, "x-linehq-api-key-permission": "webhooks:manage", "x-linehq-account-role": "owner", "x-linehq-platform-switch": "integrations", "responses": { "200": { "description": "The endpoints, and what can be added.", "content": { "application/json": { "schema": { "type": "object", "required": [ "can_add", "events", "max", "endpoints" ], "properties": { "can_add": { "type": "boolean", "description": "Whether the account holds Integrations, through its plan, the add-on or a complimentary period. Adding still fails once it has `max` endpoints." }, "events": { "type": "array", "description": "Every event an endpoint can receive.", "items": { "type": "string" } }, "max": { "type": "integer", "description": "How many endpoints an account may have." }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "example": { "can_add": true, "events": [ "call.ended", "voicemail.received", "transcript.ready" ], "max": 5, "endpoints": [ { "public_id": "Fs5Jy0GaQm4Tz8Kc1Lp6Wr3Nx9Bv2Hd7", "name": "Acme CRM", "url": "https://crm.acmeplumbing.co.uk/hooks/linehq", "events": [ "call.ended", "transcript.ready" ], "status": "active", "failing_since": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Add a webhook endpoint", "description": "Add an endpoint. Its signing secret is returned once, here; store it to check each delivery's signature. The address must be public HTTPS. At most 20 a minute.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "webhooks:manage", "x-linehq-account-role": "owner", "x-linehq-platform-switch": "integrations", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "url", "events" ], "properties": { "name": { "type": "string", "maxLength": 60 }, "url": { "type": "string", "format": "uri", "maxLength": 500, "description": "An `https://` address on the public internet." }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "example": { "name": "Acme CRM", "url": "https://crm.acmeplumbing.co.uk/hooks/linehq", "events": [ "call.ended", "transcript.ready" ] } } } }, "responses": { "201": { "description": "Added. The secret is never shown again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" }, "example": { "endpoint": { "public_id": "Fs5Jy0GaQm4Tz8Kc1Lp6Wr3Nx9Bv2Hd7", "name": "Acme CRM", "url": "https://crm.acmeplumbing.co.uk/hooks/linehq", "events": [ "call.ended", "transcript.ready" ], "status": "active", "failing_since": null }, "secret": "whsec_3f9c2b7a1d8e4f60b5c2a9e7d1f3b8c4" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks/{endpoint}": { "patch": { "operationId": "updateWebhook", "tags": [ "Webhooks" ], "summary": "Change a webhook endpoint", "description": "Change any of its name, address or events, or pause and resume it.", "x-linehq-capability": null, "x-linehq-api-key-permission": "webhooks:manage", "x-linehq-account-role": "owner", "x-linehq-platform-switch": "integrations", "parameters": [ { "$ref": "#/components/parameters/WebhookEndpoint" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "url": { "type": "string", "format": "uri", "maxLength": 500 }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "status": { "type": "string", "enum": [ "active", "paused" ] } } }, "example": { "status": "paused" } } } }, "responses": { "200": { "description": "The endpoint.", "content": { "application/json": { "schema": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "example": { "endpoint": { "public_id": "Fs5Jy0GaQm4Tz8Kc1Lp6Wr3Nx9Bv2Hd7", "name": "Acme CRM", "url": "https://crm.acmeplumbing.co.uk/hooks/linehq", "events": [ "call.ended", "transcript.ready" ], "status": "active", "failing_since": null } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Remove a webhook endpoint", "description": "Remove the endpoint. Deliveries to it stop at once.", "x-linehq-capability": null, "x-linehq-api-key-permission": "webhooks:manage", "x-linehq-account-role": "owner", "x-linehq-platform-switch": "integrations", "parameters": [ { "$ref": "#/components/parameters/WebhookEndpoint" } ], "responses": { "204": { "description": "Removed." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks/{endpoint}/rotate": { "post": { "operationId": "rotateWebhookSecret", "tags": [ "Webhooks" ], "summary": "Replace a webhook endpoint's secret", "description": "Issue a new signing secret, returned once, here. Deliveries are signed with the new one from now on.", "x-linehq-capability": null, "x-linehq-api-key-permission": "webhooks:manage", "x-linehq-account-role": "owner", "x-linehq-platform-switch": "integrations", "parameters": [ { "$ref": "#/components/parameters/WebhookEndpoint" } ], "responses": { "200": { "description": "The new secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" }, "example": { "endpoint": { "public_id": "Fs5Jy0GaQm4Tz8Kc1Lp6Wr3Nx9Bv2Hd7", "name": "Acme CRM", "url": "https://crm.acmeplumbing.co.uk/hooks/linehq", "events": [ "call.ended", "transcript.ready" ], "status": "active", "failing_since": null }, "secret": "whsec_8d1e4a7c2f9b3e60a5d2c8f1b7e4a9c3" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks/{endpoint}/test": { "post": { "operationId": "sendTestWebhook", "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Queue a signed test delivery to an active endpoint. At most 10 a minute.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "webhooks:manage", "x-linehq-account-role": "owner", "x-linehq-platform-switch": "integrations", "parameters": [ { "$ref": "#/components/parameters/WebhookEndpoint" } ], "responses": { "202": { "description": "Queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Queued" }, "example": { "queued": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The endpoint is paused or stopped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Resume Acme CRM first: a paused or stopped webhook receives nothing." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks/{endpoint}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "List deliveries", "description": "The endpoint's latest 100 deliveries from the last 30 days, newest first.", "x-linehq-capability": null, "x-linehq-api-key-permission": "webhooks:manage", "x-linehq-account-role": "owner", "x-linehq-platform-switch": "integrations", "parameters": [ { "$ref": "#/components/parameters/WebhookEndpoint" } ], "responses": { "200": { "description": "The deliveries.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deliveries" ], "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } }, "example": { "deliveries": [ { "event": "call.ended", "event_id": "2c9e7b14-5f3a-4d8e-b1c6-7a9f0e2d4b63", "status": "failed", "attempts": 6, "response_code": 500, "last_error": "HTTP 500", "created_at": "2026-10-14T09:33:21+01:00", "next_attempt_at": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks/{endpoint}/deliveries/{eventId}/resend": { "post": { "operationId": "resendWebhookDelivery", "tags": [ "Webhooks" ], "summary": "Resend a delivery", "description": "Send a failed or cancelled delivery again, as a fresh delivery with the same event id so your receiver can spot the repeat. At most 30 a minute.", "x-linehq-capability": "integrations", "x-linehq-api-key-permission": "webhooks:manage", "x-linehq-account-role": "owner", "x-linehq-platform-switch": "integrations", "parameters": [ { "$ref": "#/components/parameters/WebhookEndpoint" }, { "name": "eventId", "in": "path", "required": true, "description": "The delivery's `event_id`.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Queued" }, "example": { "queued": true } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "The event was delivered or is still being tried (only a failed or cancelled delivery can be resent), or the endpoint is paused or stopped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "That event was delivered or is still being tried." } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key created on the portal's API keys page by the account owner (or a member the owner has allowed to manage keys), sent as `Authorization: Bearer `. Each key holds the permissions chosen when it was created; every key can `read`." } }, "parameters": { "Number": { "name": "number", "in": "path", "required": true, "description": "The number's `public_id`, from List numbers.", "schema": { "type": "string" } }, "Call": { "name": "call", "in": "path", "required": true, "description": "The call's `public_id`, from List calls.", "schema": { "type": "string" } }, "Recording": { "name": "recording", "in": "path", "required": true, "description": "The recording's `public_id`, a call's `recording_public_id`.", "schema": { "type": "string" } }, "Conversation": { "name": "conversation", "in": "path", "required": true, "description": "The conversation's `public_id`, from List text conversations.", "schema": { "type": "string" } }, "Contact": { "name": "contact", "in": "path", "required": true, "description": "The contact's `public_id`.", "schema": { "type": "string" } }, "WebhookEndpoint": { "name": "endpoint", "in": "path", "required": true, "description": "The endpoint's `public_id`, from List webhooks.", "schema": { "type": "string" } }, "Page": { "name": "page", "in": "query", "description": "The page to return, from 1.", "schema": { "type": "integer", "minimum": 1 } }, "PerPage": { "name": "per_page", "in": "query", "description": "Records per page, up to 100. Defaults to 25.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "responses": { "Unauthenticated": { "description": "The key is missing, revoked or wrong.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "NotFound": { "description": "There is no such record on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Not Found" } } } }, "TooManyRequests": { "description": "More than 60 requests in a minute from this user. Wait for the `Retry-After` header's seconds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Too Many Attempts." } } } }, "Forbidden": { "description": "The API key doesn't hold the permission the request needs, its user's role doesn't allow it (some requests are for owners only), or the account's plan doesn't include the feature. When the account is the reason, `reason`, `capability` and `pricing_url` say what's needed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refusal" }, "example": { "message": "This API key needs the contacts:read permission." } } } }, "ValidationFailed": { "description": "Something in the request was missing or invalid. `errors` names each field.", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "errors" ], "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "example": { "message": "The display name field is required.", "errors": { "display_name": [ "The display name field is required." ] } } } } } }, "schemas": { "Error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A plain-English explanation." } } }, "Refusal": { "type": "object", "description": "A 403. When the account's plan is the reason, it also says why in a form your code can act on; `message` is for people and its wording may change.", "required": [ "message" ], "properties": { "message": { "type": "string" }, "reason": { "type": "string", "description": "`addon_required`, `plan_required`, `account_inactive` or `platform_disabled`." }, "capability": { "type": "string", "description": "What the account needs, such as `integrations`." }, "pricing_url": { "type": "string", "format": "uri", "description": "Where the account owner can see the plans and add-ons." } } }, "Me": { "type": "object", "required": [ "tenant", "user", "abilities", "can_transcribe", "realtime" ], "properties": { "tenant": { "type": "object", "description": "The account the key belongs to.", "required": [ "name", "status" ], "properties": { "name": { "type": "string" }, "status": { "type": "string", "description": "`active` while the account can take calls; anything else means it is paused or closed." } } }, "user": { "type": "object", "description": "The person who created the key. The key acts as them.", "required": [ "name", "email", "role" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "description": "`owner` or `member`." } } }, "abilities": { "type": "array", "description": "The permissions this key holds, such as `read`, `contacts:read` or `webhooks:manage`.", "items": { "type": "string" } }, "can_transcribe": { "type": "boolean", "description": "Whether this key may start a paid transcription." }, "realtime": { "$ref": "#/components/schemas/Realtime" } } }, "Realtime": { "type": "object", "description": "Where to subscribe for live call events (a Pusher-protocol WebSocket). When `enabled` is false the other fields are null; poll instead.", "required": [ "enabled", "channel", "key", "host", "port", "scheme" ], "properties": { "enabled": { "type": "boolean" }, "channel": { "type": [ "string", "null" ], "description": "The private channel to authorise at `POST /api/broadcasting/auth` with the same API key. Treat it as an opaque name and use it exactly as given." }, "key": { "type": [ "string", "null" ] }, "host": { "type": [ "string", "null" ] }, "port": { "type": [ "integer", "null" ] }, "scheme": { "type": [ "string", "null" ] } } }, "Balance": { "type": "object", "required": [ "balance_pence", "currency" ], "properties": { "balance_pence": { "type": "integer", "description": "The prepaid wallet balance in pence. 2500 is £25.00." }, "currency": { "type": "string", "enum": [ "GBP" ] } } }, "NumberSummary": { "type": "object", "required": [ "public_id", "e164", "label", "status", "sms_capable", "sms_ready", "cli_eligible", "is_default_caller_id" ], "properties": { "public_id": { "type": "string", "description": "The number's id in every other request." }, "e164": { "type": "string", "description": "The number in international format." }, "label": { "type": [ "string", "null" ], "description": "The account's own name for the number." }, "status": { "$ref": "#/components/schemas/NumberStatus" }, "sms_capable": { "type": "boolean", "description": "Whether the number can receive text messages." }, "sms_ready": { "type": "boolean", "description": "Whether the number is set up to send text messages." }, "cli_eligible": { "type": "boolean", "description": "Whether the number may be shown as caller ID on calls the account makes." }, "is_default_caller_id": { "type": "boolean", "description": "Whether it is the number the account's outgoing calls show by default." } } }, "Number": { "type": "object", "required": [ "public_id", "e164", "label", "status", "ownership", "business_profile", "release_at", "sms_capable", "sms_ready", "cli_eligible", "cli_verified", "is_default_caller_id", "forward_cli" ], "properties": { "public_id": { "type": "string" }, "e164": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/NumberStatus" }, "ownership": { "type": "string", "description": "`platform` for a number bought from LineHQ, `byo` for one connected from the account's own carrier." }, "business_profile": { "description": "The business this number answers as, when the account has more than one.", "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "public_id", "name" ], "properties": { "public_id": { "type": "string" }, "name": { "type": "string" } } } ] }, "release_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a number the account has given up will be released." }, "sms_capable": { "type": "boolean" }, "sms_ready": { "type": "boolean" }, "cli_eligible": { "type": "boolean" }, "cli_verified": { "type": "boolean", "description": "Whether the account has proved it controls this number to the carrier." }, "is_default_caller_id": { "type": "boolean" }, "forward_cli": { "$ref": "#/components/schemas/ForwardCallerId" } } }, "NumberStatus": { "type": "string", "description": "`assigned` once the number is live. A new number can be `pending_documents` while its paperwork is checked, and a number moving to LineHQ is `porting` until the move completes." }, "ForwardCallerId": { "type": "object", "description": "What the person answering a forwarded call sees as the caller.", "required": [ "mode", "shows", "own_e164", "platform_e164", "own_available" ], "properties": { "mode": { "type": "string", "description": "The number's setting." }, "shows": { "type": "string", "description": "What is shown on forwarded calls now: `own` (this number), `caller` (the caller's number) or `platform` (a LineHQ number)." }, "own_e164": { "type": "string" }, "platform_e164": { "type": [ "string", "null" ] }, "own_available": { "type": "boolean", "description": "Whether the carrier forwarding the call can show this number." } } }, "NumberRouting": { "type": "object", "required": [ "number", "default", "schedules", "override" ], "properties": { "number": { "type": "object", "required": [ "public_id", "e164", "status", "voicemail_transcription_enabled", "call_transcription_enabled", "privacy_mode_enabled" ], "properties": { "public_id": { "type": "string" }, "e164": { "type": "string" }, "status": { "$ref": "#/components/schemas/NumberStatus" }, "voicemail_transcription_enabled": { "type": "boolean", "description": "Whether voicemails left on this number are transcribed automatically." }, "call_transcription_enabled": { "type": "boolean", "description": "Whether recorded calls on this number are transcribed automatically." }, "privacy_mode_enabled": { "type": "boolean", "description": "Whether privacy mode is on, which stops recording and transcription on this number." } } }, "default": { "$ref": "#/components/schemas/Route" }, "schedules": { "type": "array", "description": "Routes that apply during their windows, highest priority first.", "items": { "allOf": [ { "$ref": "#/components/schemas/Route" }, { "type": "object", "required": [ "name", "windows" ], "properties": { "name": { "type": "string" }, "windows": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduleWindow" } } } } ] } }, "override": { "description": "A temporary route that replaces the others between `from` and `until`, or null.", "oneOf": [ { "type": "null" }, { "allOf": [ { "$ref": "#/components/schemas/Route" }, { "type": "object", "required": [ "name", "from", "until", "in_effect", "timezone" ], "properties": { "name": { "type": "string" }, "from": { "type": [ "string", "null" ], "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "in_effect": { "type": "boolean" }, "timezone": { "type": "string", "description": "The time zone the portal shows these times in." } } } ] } ] } } }, "Route": { "type": "object", "required": [ "mode", "recording_enabled", "voicemail_fallback", "whisper", "ai_cover", "forward_targets", "ivr" ], "properties": { "mode": { "type": "string", "description": "`forward` rings the targets, `voicemail` goes straight to voicemail, `ivr` plays a keypad menu and `receptionist` hands the call to a virtual receptionist." }, "recording_enabled": { "type": "boolean" }, "voicemail_fallback": { "type": "boolean", "description": "Whether an unanswered call goes to voicemail." }, "whisper": { "type": "boolean", "description": "Whether the person answering hears which number was called before the call connects." }, "ai_cover": { "type": "string", "description": "When the AI receptionist answers: `off`, `no_answer`, `closed_or_no_answer` or `always`." }, "forward_targets": { "type": "array", "description": "Who rings, in order.", "items": { "type": "object", "required": [ "kind", "e164", "ring_seconds" ], "properties": { "kind": { "type": "string" }, "e164": { "type": [ "string", "null" ], "description": "The phone number rung. Null when the target is one of the account's own devices." }, "staff_label": { "type": [ "string", "null" ], "description": "Who answers at this target, as the account named them." }, "ring_seconds": { "type": "integer" } } } }, "ivr": { "type": "object", "description": "The keypad menu, used when `mode` is `ivr`.", "required": [ "options" ], "properties": { "options": { "type": "array", "items": { "type": "object", "required": [ "digit", "action" ], "properties": { "digit": { "type": "string" }, "action": { "type": "string", "description": "`forward`, `voicemail` or `ai`." }, "e164": { "type": "string", "description": "The number this option forwards to." }, "ring_seconds": { "type": "integer" } } } } } } } }, "ScheduleWindow": { "type": "object", "required": [ "days", "start", "end" ], "properties": { "days": { "type": "array", "description": "ISO weekdays, 1 for Monday to 7 for Sunday.", "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "start": { "type": "string", "description": "24-hour time, HH:MM." }, "end": { "type": "string", "description": "24-hour time, HH:MM." } } }, "Page": { "type": "object", "description": "Lists come a page at a time. Follow `next_page_url` until it is null.", "required": [ "current_page", "last_page", "per_page", "total", "next_page_url", "prev_page_url" ], "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "next_page_url": { "type": [ "string", "null" ] }, "prev_page_url": { "type": [ "string", "null" ] } } }, "CallOutcome": { "type": "string", "description": "How the call ended.", "enum": [ "answered", "no-answer", "voicemail", "failed", "in-progress", "busy", "blocked" ] }, "Call": { "type": "object", "required": [ "public_id", "from", "caller_display_name", "to", "to_name", "direction", "disposition", "started_at", "forward_seconds", "total_rated_amount_pence", "recording_public_id", "transcript" ], "properties": { "public_id": { "type": "string" }, "from": { "type": [ "string", "null" ], "description": "Who called. A UK number is in international format; a withheld or overseas caller is shown as their network presented it, which may not be a phone number." }, "caller_display_name": { "type": [ "string", "null" ], "description": "Who the caller is, matched from the account's contacts or a connected CRM." }, "to": { "type": [ "string", "null" ], "description": "The number dialled. On an outgoing call, the number the account called." }, "to_name": { "type": [ "string", "null" ], "description": "On an incoming call, the account's label for the number called." }, "direction": { "type": "string", "description": "`inbound` or `outbound`. `internal_extension` is a call between two LineHQ accounts' phones, where `from` and `to` are extensions rather than phone numbers. New kinds of call may appear." }, "disposition": { "$ref": "#/components/schemas/CallOutcome" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "forward_seconds": { "type": [ "integer", "null" ], "description": "How long the call was connected to whoever answered, in seconds." }, "total_rated_amount_pence": { "type": "integer", "description": "The call's forwarding, incoming-call and voicemail charges from the prepaid balance, in pence. Minutes inside the plan cost 0." }, "recording_public_id": { "type": [ "string", "null" ], "description": "The recording's id, for Get a recording link and Get a transcript. Null when the call wasn't recorded." }, "transcript": { "description": "The transcription and its AI summary, from the moment one is started (check `status` and `summary_status`); null when the call has never been transcribed.", "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "status", "summary_status", "summary", "intent", "sentiment", "urgency", "action_items", "callback_number" ], "properties": { "status": { "$ref": "#/components/schemas/TranscriptStatus" }, "summary_status": { "$ref": "#/components/schemas/SummaryStatus" }, "summary": { "type": [ "string", "null" ] }, "intent": { "type": [ "string", "null" ], "description": "What the caller wanted, in a few words." }, "sentiment": { "type": [ "string", "null" ], "description": "`positive`, `neutral` or `negative`." }, "urgency": { "type": [ "string", "null" ], "description": "`low`, `normal` or `high`." }, "action_items": { "oneOf": [ { "type": "null" }, { "type": "array", "items": { "type": "string" } } ] }, "callback_number": { "type": [ "string", "null" ], "description": "A number the caller asked to be called back on." } } } ] } } }, "TranscriptStatus": { "type": "string", "description": "`pending` and `processing` while it runs, then `completed` or `failed`. `skipped_insufficient_credit` means the balance couldn't cover it." }, "SummaryStatus": { "type": [ "string", "null" ], "description": "`pending`, `processing`, `completed`, `skipped` or `failed`." }, "Transcript": { "type": "object", "required": [ "status", "text", "language", "minutes", "rated_amount_pence", "summary_status", "summary", "segments", "intent", "sentiment", "urgency", "action_items", "callback_number" ], "properties": { "status": { "$ref": "#/components/schemas/TranscriptStatus" }, "text": { "type": [ "string", "null" ], "description": "The whole transcript as plain text." }, "language": { "type": [ "string", "null" ], "description": "The language heard, as a two-letter code." }, "minutes": { "type": [ "integer", "null" ], "description": "The minutes charged for." }, "rated_amount_pence": { "type": [ "integer", "null" ], "description": "What it cost from the prepaid balance, in pence." }, "summary_status": { "$ref": "#/components/schemas/SummaryStatus" }, "summary": { "type": [ "string", "null" ] }, "segments": { "type": "array", "description": "Who said what, and when, in seconds from the start of the recording.", "items": { "type": "object", "required": [ "start", "end", "speaker", "text" ], "properties": { "start": { "type": "number" }, "end": { "type": "number" }, "speaker": { "type": "string", "description": "`customer` (the other party) or `agent` (the account's side, a person or the AI receptionist). Empty when the recording isn't split by side." }, "text": { "type": "string" } } } }, "intent": { "type": [ "string", "null" ] }, "sentiment": { "type": [ "string", "null" ] }, "urgency": { "type": [ "string", "null" ] }, "action_items": { "type": "array", "items": { "type": "string" } }, "callback_number": { "type": [ "string", "null" ] } } }, "TranscriptionEstimate": { "type": "object", "required": [ "available", "minutes", "cost_pence", "rate_pence_per_min", "within_allowance", "bundle_minutes", "balance_pence", "affordable", "existing_status" ], "properties": { "available": { "type": "boolean", "description": "Whether the account's plan includes transcription." }, "minutes": { "type": "integer", "description": "The minutes it would be charged for." }, "cost_pence": { "type": "integer", "description": "What would come from the prepaid balance, in pence, after the plan's allowance and any bundle." }, "rate_pence_per_min": { "type": "integer" }, "within_allowance": { "type": "boolean", "description": "Whether it would cost nothing from the balance." }, "bundle_minutes": { "type": "integer", "description": "Minutes that would come from a prepaid transcription bundle." }, "balance_pence": { "type": "integer" }, "affordable": { "type": "boolean", "description": "Whether Transcribe a call would go ahead now." }, "existing_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TranscriptStatus" } ], "description": "The status of a transcript the recording already has, if any." } } }, "SmsConversation": { "type": "object", "required": [ "public_id", "counterparty_e164", "number_e164", "number_label", "last_message_at", "last_message_preview", "unread_count" ], "properties": { "public_id": { "type": "string" }, "counterparty_e164": { "type": "string", "description": "The other party's number." }, "number_e164": { "type": [ "string", "null" ], "description": "The account's number the thread is on." }, "number_label": { "type": [ "string", "null" ] }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_message_preview": { "type": [ "string", "null" ] }, "unread_count": { "type": "integer" } } }, "SmsMessage": { "type": "object", "required": [ "conversation_public_id", "direction", "from_e164", "to_e164", "body", "status", "segments", "received_at" ], "properties": { "conversation_public_id": { "type": [ "string", "null" ] }, "direction": { "type": "string", "description": "`inbound` or `outbound`." }, "from_e164": { "type": "string" }, "to_e164": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "`received` for an incoming text; `queued`, `sent`, `delivered`, `undelivered` or `failed` for one sent." }, "segments": { "type": "integer", "description": "How many SMS segments the message used." }, "received_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Contact": { "type": "object", "required": [ "public_id", "display_name", "first_name", "last_name", "company", "email", "notes", "source", "external_id", "source_created_at", "source_updated_at", "phones", "links", "created_at", "updated_at" ], "properties": { "public_id": { "type": "string" }, "display_name": { "type": "string", "description": "The name LineHQ shows for a caller with one of this contact's numbers." }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ], "description": "Which system the contact came from." }, "external_id": { "type": [ "string", "null" ], "description": "Its id in that system." }, "source_created_at": { "type": [ "string", "null" ], "format": "date-time" }, "source_updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "phones": { "type": "array", "items": { "type": "object", "required": [ "e164", "raw_number", "label", "is_primary" ], "properties": { "e164": { "type": [ "string", "null" ], "description": "The number in international format." }, "raw_number": { "type": [ "string", "null" ], "description": "The number as it was sent." }, "label": { "type": [ "string", "null" ] }, "is_primary": { "type": "boolean" } } } }, "links": { "type": "array", "description": "Where the contact lives in other systems.", "items": { "type": "object", "required": [ "source", "external_id", "external_url" ], "properties": { "source": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "external_url": { "type": [ "string", "null" ] } } } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ContactInput": { "type": "object", "required": [ "display_name", "phones" ], "properties": { "source": { "type": "string", "maxLength": 60, "description": "Your system's name. With `external_id`, it identifies the contact so a repeat send updates it." }, "external_id": { "type": [ "string", "null" ], "maxLength": 190 }, "display_name": { "type": "string", "maxLength": 190 }, "first_name": { "type": [ "string", "null" ], "maxLength": 100 }, "last_name": { "type": [ "string", "null" ], "maxLength": 100 }, "company": { "type": [ "string", "null" ], "maxLength": 190 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 190 }, "notes": { "type": [ "string", "null" ], "maxLength": 5000 }, "external_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000, "description": "A link to the contact in your system." }, "source_created_at": { "type": [ "string", "null" ], "format": "date-time" }, "source_updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "phones": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "required": [ "number" ], "properties": { "number": { "type": "string", "maxLength": 40, "description": "Any common UK or international format." }, "label": { "type": [ "string", "null" ], "maxLength": 40 }, "is_primary": { "type": "boolean" } } } } } }, "Todo": { "type": "object", "required": [ "public_id", "text", "status", "callback_e164", "sentiment", "urgency", "summary_snippet", "created_at", "updated_at", "completed_at", "done_by", "call" ], "properties": { "public_id": { "type": "string" }, "text": { "type": "string", "description": "What to do." }, "status": { "type": "string", "enum": [ "open", "done" ] }, "callback_e164": { "type": [ "string", "null" ], "description": "A number to call back, when the to-do is a call back." }, "sentiment": { "type": [ "string", "null" ], "description": "The call summary's sentiment." }, "urgency": { "type": [ "string", "null" ], "description": "The call summary's urgency." }, "summary_snippet": { "type": [ "string", "null" ], "description": "The start of the call's AI summary." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "done_by": { "description": "Who ticked it off.", "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } ] }, "call": { "description": "The call it came from.", "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "public_id", "from_e164", "to_e164", "number_label", "started_at" ], "properties": { "public_id": { "type": "string" }, "from_e164": { "type": [ "string", "null" ] }, "to_e164": { "type": [ "string", "null" ] }, "number_label": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" } } } ] } } }, "Notification": { "type": "object", "required": [ "id", "type", "title", "body", "url", "read", "created_at", "read_at" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "description": "What happened, such as `missed_call`, `voicemail`, `recording`, `reception_message`, `sms_received` or `job_request`; `other` for the rest." }, "title": { "type": "string" }, "body": { "type": "string" }, "url": { "type": [ "string", "null" ], "description": "Where it opens in the portal." }, "read": { "type": "boolean" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "read_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "MessageSlip": { "type": "object", "required": [ "public_id", "from_e164", "department", "received_at", "heard_at", "name_recording_public_id", "message_recording_public_id", "transcript_status", "caller_name", "summary_status", "sentiment", "urgency" ], "properties": { "public_id": { "type": "string" }, "from_e164": { "type": [ "string", "null" ] }, "department": { "type": [ "string", "null" ], "description": "The receptionist department the caller chose." }, "received_at": { "type": [ "string", "null" ], "format": "date-time" }, "heard_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When someone first played it; null while unheard." }, "name_recording_public_id": { "type": [ "string", "null" ], "description": "The caller saying their name, for Get a recording link." }, "message_recording_public_id": { "type": [ "string", "null" ], "description": "The message itself, for Get a recording link and Get a transcript." }, "transcript_status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TranscriptStatus" } ] }, "caller_name": { "type": [ "string", "null" ], "description": "The caller's spoken name, as transcribed." }, "summary_status": { "$ref": "#/components/schemas/SummaryStatus" }, "sentiment": { "type": [ "string", "null" ] }, "urgency": { "type": [ "string", "null" ] } } }, "JobRequest": { "type": "object", "required": [ "public_id", "status", "caller_name", "caller_e164", "contact_e164", "line_e164", "line_label", "job_type", "description", "address", "postcode", "preferred_when", "preferred_date", "preferred_time_window", "received_at", "done_at", "done_by", "message_recording_public_id", "call_public_id" ], "properties": { "public_id": { "type": "string" }, "status": { "type": "string", "description": "`new`, `confirmed`, `done` or `declined`." }, "caller_name": { "type": [ "string", "null" ] }, "caller_e164": { "type": [ "string", "null" ], "description": "The number they called from." }, "contact_e164": { "type": [ "string", "null" ], "description": "The number to reach them on, which they may have given in the message." }, "line_e164": { "type": [ "string", "null" ], "description": "The account's number they rang. Call back from it so they recognise you." }, "line_label": { "type": [ "string", "null" ] }, "job_type": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "postcode": { "type": [ "string", "null" ] }, "preferred_when": { "type": [ "string", "null" ], "description": "When they'd like it done, in their words." }, "preferred_date": { "type": [ "string", "null" ], "format": "date" }, "preferred_time_window": { "type": [ "string", "null" ] }, "received_at": { "type": [ "string", "null" ], "format": "date-time" }, "done_at": { "type": [ "string", "null" ], "format": "date-time" }, "done_by": { "type": [ "string", "null" ], "description": "The name of who closed it." }, "message_recording_public_id": { "type": [ "string", "null" ], "description": "The recording it came from, for Get a recording link." }, "call_public_id": { "type": [ "string", "null" ] } } }, "BlockedCaller": { "type": "object", "required": [ "public_id", "e164", "action", "label", "number", "created_at" ], "properties": { "public_id": { "type": "string" }, "e164": { "type": "string", "description": "The blocked number." }, "action": { "type": "string", "description": "What a blocked call gets, such as `reject` or `voicemail`." }, "label": { "type": [ "string", "null" ], "description": "The account's note on why." }, "number": { "type": [ "string", "null" ], "description": "The account's number the block applies to; null for every number." }, "created_at": { "type": [ "string", "null" ], "format": "date" } } }, "Analytics": { "type": "object", "required": [ "days", "summary", "by_day", "by_hour", "by_number", "sentiment" ], "properties": { "days": { "type": "integer", "description": "The window counted, in days." }, "summary": { "type": "object", "required": [ "total", "filtered", "answered", "missed", "voicemail", "blocked", "answer_rate", "avg_forward_seconds" ], "properties": { "total": { "type": "integer" }, "filtered": { "type": "integer", "description": "Calls call protection screened out. Not part of `total`." }, "answered": { "type": "integer" }, "missed": { "type": "integer", "description": "Unanswered, failed or busy." }, "voicemail": { "type": "integer" }, "blocked": { "type": "integer" }, "answer_rate": { "type": "number", "description": "Answered calls as a percentage of `total`." }, "avg_forward_seconds": { "type": "integer", "description": "The average length of an answered call, in seconds." } } }, "by_day": { "type": "object", "description": "Calls on each day, keyed by date (YYYY-MM-DD), from the start of the day `days` days ago through today (so `days` + 1 entries), including days with none.", "additionalProperties": { "type": "integer" } }, "by_hour": { "type": "array", "description": "Calls in each hour of the day, 24 entries from midnight.", "items": { "type": "integer" } }, "by_number": { "type": "array", "description": "Every live number's calls in the window, whichever number is filtered.", "items": { "type": "object", "required": [ "public_id", "e164", "label", "total", "answered" ], "properties": { "public_id": { "type": "string" }, "e164": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "answered": { "type": "integer" } } } }, "sentiment": { "type": "object", "description": "How summarised calls felt.", "required": [ "positive", "neutral", "negative" ], "properties": { "positive": { "type": "integer" }, "neutral": { "type": "integer" }, "negative": { "type": "integer" } } } } }, "LedgerEntry": { "type": "object", "required": [ "type", "amount_pence", "balance_after_pence", "note", "created_at" ], "properties": { "type": { "type": "string", "description": "What moved the balance, such as `topup`, `charge` (a forwarded call), `outbound`, `voicemail`, `sms`, `transcription`, `ai_receptionist` or `refund`. New types may appear." }, "amount_pence": { "type": "integer", "description": "Positive adds to the balance, negative takes from it." }, "balance_after_pence": { "type": "integer" }, "note": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Receipt": { "type": "object", "required": [ "number", "kind", "amount_pence", "description", "paid_at" ], "properties": { "number": { "type": "string", "description": "The receipt number." }, "kind": { "type": "string", "description": "What was paid for, such as `topup`." }, "amount_pence": { "type": "integer" }, "description": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookEvent": { "type": "string", "enum": [ "call.ended", "voicemail.received", "transcript.ready" ] }, "WebhookEndpoint": { "type": "object", "required": [ "public_id", "name", "url", "events", "status", "failing_since" ], "properties": { "public_id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "status": { "type": "string", "description": "`active`, `paused` by the account, or `disabled` by LineHQ after 24 hours of failed deliveries." }, "failing_since": { "type": [ "string", "null" ], "format": "date-time", "description": "When deliveries started failing; null while they succeed." } } }, "WebhookEndpointWithSecret": { "type": "object", "required": [ "endpoint", "secret" ], "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "secret": { "type": "string", "description": "The signing secret. Shown only in this response." } } }, "WebhookDelivery": { "type": "object", "required": [ "event", "event_id", "status", "attempts", "response_code", "last_error", "created_at", "next_attempt_at" ], "properties": { "event": { "type": "string" }, "event_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "`pending`, `delivered`, `failed` or `cancelled`." }, "attempts": { "type": "integer" }, "response_code": { "type": [ "integer", "null" ], "description": "Your endpoint's HTTP status on the last attempt." }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Queued": { "type": "object", "required": [ "queued" ], "properties": { "queued": { "type": "boolean", "enum": [ true ] } } } } } }