{ "openapi": "3.1.0", "info": { "title": "AVANSER Telco API", "version": "202610", "description": "AVANSER Telco API is designed to provide an easy way to order and manage client services.\n\nAVANSER Telco API is Agency friendly. Users can be configured to have access to multiple AVANSER accounts, facilitating service automation.\n" }, "servers": [ { "url": "https://tapi.avanser.com/v1/", "description": "Avanser Production" } ], "security": [ { "HTTP_BASIC": [] } ], "tags": [ { "name": "Accounts" }, { "name": "Search Numbers", "description": "Search into the AVANSER inventory. Search for AVAILABLE Numbers to be ACTIVATED." }, { "name": "Requests" }, { "name": "Request Details" }, { "name": "Manage Services" }, { "name": "Manage Templates", "description": "Allows the customer to configure a template for Email and SMS Call Reporting" }, { "name": "AI Agents" } ], "paths": { "/accounts": { "get": { "tags": [ "Accounts" ], "summary": "List Accounts", "operationId": "listAccounts", "description": "List all available accounts associated with the user.", "x-apiary-uri-template": "/accounts?type={type}", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Indicates whether the caller intends to use the account for configuration-related endpoints or billing-related endpoints.", "schema": { "type": "string", "enum": [ "configuration", "billing" ], "default": "configuration" }, "example": "configuration" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Accounts" } } } }, "400": { "$ref": "#/components/responses/BadRequestInvalidAccount" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } }, "post": { "tags": [ "Accounts" ], "summary": "Switch Account", "operationId": "switchAccount", "description": "Switch between available accounts associated with the user.", "x-apiary-uri-template": "/accounts?account-id={account-id}", "parameters": [ { "name": "account-id", "in": "query", "required": true, "description": "Enter the desired account ID (client ID).", "schema": { "type": "number" } } ], "responses": { "200": { "$ref": "#/components/responses/GenericSuccess" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/accounts/details": { "get": { "tags": [ "Accounts" ], "summary": "List Account Details", "operationId": "listAccountDetails", "description": "List details of selected account.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountDetails" } } } } } } }, "/accounts/packages": { "get": { "tags": [ "Accounts" ], "summary": "List Account Packages", "operationId": "listAccountPackages", "description": "Lists all of the packages for the currently selected client.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountPackages" } } } } } } }, "/accounts/number_rates": { "get": { "tags": [ "Accounts" ], "summary": "List Number Rates", "operationId": "listNumberRates", "description": "Lists all of the number rates for the currently selected client.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountNumberRates" } } } } } } }, "/accounts/call_rates": { "get": { "tags": [ "Accounts" ], "summary": "List Call Rates", "operationId": "listCallRates", "description": "Lists all of the call rates for the currently selected client.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountCallRates" } } } } } } }, "/accounts/transcription_rates": { "get": { "tags": [ "Accounts" ], "summary": "List Transcription Rates", "operationId": "listTranscriptionRates", "description": "Lists all of the transcription rates for the currently selected client.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountTranscriptionRates" } } } } } } }, "/accounts/features": { "get": { "tags": [ "Accounts" ], "summary": "List Account Features", "operationId": "listAccountFeatures", "description": "Lists all of the features for the currently selected client.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accountFeatures" } } } } } } }, "/numbers?country={country}&location={location}": { "get": { "tags": [ "Search Numbers" ], "summary": "by Location", "operationId": "searchNumbersByLocation", "description": "Search for available numbers by location will return all available numbers within a provided radius from the search location.", "x-apiary-uri-template": "/numbers?country={country}&location={location}&radius={radius}", "parameters": [ { "name": "country", "in": "path", "required": true, "description": "Search country.", "schema": { "type": "string" } }, { "name": "location", "in": "path", "required": true, "description": "Search into AVANSER inventory by Address eg. \"Level 2 150-152 Elizabeth St, 2000 NSW, Australia\".", "schema": { "type": "string" } }, { "name": "radius", "in": "query", "required": false, "description": "Search radius in kilometers.", "schema": { "type": "number", "default": 20 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchElement" } } } }, "300": { "description": "Multiple addresses (by Location only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MultipleAddresses" } } } }, "400": { "$ref": "#/components/responses/ErrorDetail" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/numbers?country={country}&lat={lat}&lng={lng}": { "get": { "tags": [ "Search Numbers" ], "summary": "by Coordinates", "operationId": "searchNumbersByCoordinates", "description": "Search for available numbers by latitude and longitude, will return all available number within the provided radius from the search coordinates.", "x-apiary-uri-template": "/numbers?country={country}&lat={lat}&lng={lng}&radius={radius}", "parameters": [ { "name": "country", "in": "path", "required": true, "description": "Search country.", "schema": { "type": "string" } }, { "name": "lat", "in": "path", "required": true, "description": "Latitude", "schema": { "type": "number" } }, { "name": "lng", "in": "path", "required": true, "description": "Longitude", "schema": { "type": "number" } }, { "name": "radius", "in": "query", "required": false, "description": "Search radius in kilometers.", "schema": { "type": "number", "default": 20 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchElement" } } } }, "400": { "$ref": "#/components/responses/ErrorDetail" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/numbers?country={country}&number={number}": { "get": { "tags": [ "Search Numbers" ], "summary": "by Matching prefix", "operationId": "searchNumbersByMatchingPrefix", "description": "Search for available numbers matching provided number as close as possible.\n\nChecks are performed trying first to get a perfect match, than reducing the matching length by 1 up to 6 digits.\n\n### Example: matching 61290081596\n\n1. Attempt: matching 61290081596\n2. Attempt: matching 6129008159X\n3. Attempt: matching 612900815XX\n4. Attempt: matching 61290081XXX\n5. Attempt: matching 6129008XXXX\n6. Attempt: matching 612900XXXXX\n7. Attempt: matching 61290XXXXXX\n", "x-apiary-uri-template": "/numbers?country={country}&number={number}", "parameters": [ { "name": "country", "in": "path", "required": true, "description": "Search country.", "schema": { "type": "string" } }, { "name": "number", "in": "path", "required": true, "description": "Valid phone number (E164 format)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchElement" } } } }, "400": { "$ref": "#/components/responses/ErrorDetail" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/numbers?country={country}&number_type={number_type}": { "get": { "tags": [ "Search Numbers" ], "summary": "by Number Type", "operationId": "searchNumbersByNumberType", "description": "Search for available numbers matching provided number as close as possible.\n\n### Number Types\n\n| Type | Description\n|:---------|-------------\n| GEO | Local Numbers, more efficient search using other options\n| TOLLFREE | TOLLFREE numbers, same rate for the calling party independently from the area.\n| FREECALL | For the calling party, a call to a toll-free number from a landline is free of charge.\n| MOBILE | Mobile numbers\n", "x-apiary-uri-template": "/numbers?country={country}&number_type={number_type}", "parameters": [ { "name": "country", "in": "path", "required": true, "description": "Search country.", "schema": { "type": "string" } }, { "name": "number_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "GEO", "TOLLFREE", "FREECALL", "MOBILE" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchElement" } } } }, "400": { "$ref": "#/components/responses/ErrorDetail" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/numbers?szu={szu}": { "get": { "tags": [ "Search Numbers" ], "summary": "by SZU Australia", "operationId": "searchNumbersBySzuAustralia", "description": "Search for available numbers matching the numbers by Standard Zone Unit (SZU), this option is available for Australia only.\n\nMost updated list of available Standard Zone Unit for Australia can be found [here](http://acma.gov.au/Industry/Telco/Numbering/Managing-numbers/numbering-charging-districts-zones-and-precincts)\n", "x-apiary-uri-template": "/numbers?szu={szu}", "parameters": [ { "name": "szu", "in": "path", "required": true, "description": "Valid Australian SZU", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchElement" } } } }, "400": { "$ref": "#/components/responses/ErrorDetail" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/requests": { "get": { "tags": [ "Requests" ], "summary": "List Requests", "operationId": "listRequests", "description": "Returns all requests, requests are returned in batches of 100.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRequests" } } } } } }, "post": { "tags": [ "Requests" ], "summary": "Request new Service", "operationId": "requestNewService", "description": "Submit a new service request.\n\nWhen the request is accepted a number is reserved for this service.\n\n### Automatic number allocation\n\nAlong with the service details each new request requires to specify `service_number`\n\nThe `service_number` object allow our customer to specify the \"search rules\" for the new service number easing the number selection process.\n\nWhat follow is a series of examples on how tok use the automatic number allocation feature:\n\n#### by location\n```\n{\n \"service_number\":\n {\n \"country\": \"AU\",\n \"search_type\": \"location\",\n \"location\": \"LEVEL 2 150-152 Elizabeth St, 2000 NSW Australia\",\n \"radius\": 20\n }\n}\n```\n#### by coordinates\n```\n{\n \"service_number\":\n {\n \"country\": \"AU\",\n \"search_type\": \"location\",\n \"lat\": -33.865143,\n \"lng\": 151.209900,\n \"radius\": 20\n }\n}\n```\n#### by \"matching prefix\" or \"service number\"\n```\n{\n \"service_number\":\n {\n \"country\": \"AU\",\n \"search_type\": \"number\",\n \"number\": \"61290081596\"\n }\n}\n```\n\n`number` can be either the number to match as close as possible or one of AVANSER's available service number chosen through Search Numbers service available for this API.\n\n#### by number type\n```\n{\n \"service_number\":\n {\n \"country\": \"AU\",\n \"search_type\": \"number_type\",\n \"number_type\": \"MOBILE\"\n }\n}\n```\n#### by szu\n```\n{\n \"service_number\":\n {\n \"country\": \"AU\",\n \"search_type\": \"szu\",\n \"szu\": \"sydney\"\n }\n}\n```\n\n### Example: new transfer service\n\nTransfer service allows our customer to transfer the Caller Party to the desired Answer Point\n\n### Example: new voicemail service\n\nVoicemail service allows our customers to play a message to the Caller Party and record a message.\n\nMessage is stored along with the CDR data and is always available either in the Portal or using our WebAPI service.\n\n### Example: new prompt service\n\nPrompt service allows our customers to play a message to the Caller Party.\n", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundRequest" }, "examples": { "transfer": { "summary": "new transfer service", "value": { "name": "TAPI Transfer EXAMPLE", "custom_id": "tapi-transfer-example-1", "service_number": { "country": "AU", "search_type": "number_type", "number_type": "MOBILE" }, "service": { "type": "transfer", "answer_point_name": "TAPI answer point EXAMPLE #1", "answer_point": "61420123123", "call_whisper": "https://example.tld/audio/call_whisper.wav", "voicemail": "https://example.tld/audio/voicemail.wav", "record_call": false, "transcription": { "transcribe_call": true, "enable_pci_redaction": true, "enable_pii_redaction": true }, "call_reporting": { "report": "none" } }, "call_uri": "http://example.tld/debug.php?call-uri", "sms_forward_uri": "http://example.tld/debug.php?sms_forward_uri", "callback_uri": "http://example.tld/debug.php?callback_uri" } }, "transferToAiAgent": { "summary": "new transfer service answered by an AI Agent", "value": { "name": "TAPI AI Agent transfer", "service_number": { "country": "AU", "search_type": "number_type", "number_type": "mobile" }, "service": { "type": "transfer", "answer_point_name": "AI Reception", "answer_point": "+AIA-AIAGENTID155", "record_call": false } } }, "voicemail": { "summary": "new voicemail service", "value": { "name": "TAPI Voicemail EXAMPLE", "custom_id": "tapi-voicemail-example-1", "service_number": { "country": "AU", "search_type": "number_type", "number_type": "MOBILE" }, "service": { "type": "voicemail", "answer_point_name": "TAPI answer point EXAMPLE #2", "voicemail": "https://example.tld/audio/voicemail.mp3", "call_reporting": { "report": "missed", "email": { "subject": "call for Voicemail", "email_to": [ "no-reply@avanser.com.au" ], "template": "html_email_template" }, "sms": { "mobile": "61420123123", "template": "text_sms_template" } } }, "call_uri": "http://example.tld/debug.php?call-uri", "sms_forward_uri": "http://example.tld/debug.php?sms_forward_uri", "callback_uri": "http://example.tld/debug.php?callback_uri" } }, "prompt": { "summary": "new prompt service", "value": { "name": "TAPI Prompt EXAMPLE", "custom_id": "tapi-prompt-example-1", "service_number": { "country": "AU", "search_type": "number_type", "number_type": "MOBILE" }, "service": { "type": "prompt", "answer_point_name": "TAPI answer point EXAMPLE #3", "call_greeting": "https://example.tld/audio/call_greeting.wav" }, "call_reporting": { "report": "missed", "email": { "subject": "call for Prompt", "email_to": [ "no-reply@avanser.com.au" ], "template": "html_email_template" }, "sms": { "mobile": "61420123123", "template": "text_sms_template" } }, "call_uri": "http://example.tld/debug.php?call-uri", "sms_forward_uri": "http://example.tld/debug.php?sms_forward_uri", "callback_uri": "http://example.tld/debug.php?callback_uri" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgmentReplyWithServiceNumber" } } } }, "400": { "$ref": "#/components/responses/ErrorDetail" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/requests/{request_id}/request_body": { "get": { "tags": [ "Request Details" ], "summary": "Request Body", "operationId": "getRequestBody", "description": "Returns the submitted user body, this is the request as received", "parameters": [ { "$ref": "#/components/parameters/requestId" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceDetail" } } } } } } }, "/requests/{request_id}/acknowledgment_body": { "get": { "tags": [ "Request Details" ], "summary": "Acknowledgment Body", "operationId": "getAcknowledgmentBody", "description": "Returns the acknowledgment request response", "parameters": [ { "$ref": "#/components/parameters/requestId" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgmentReply" } } } } } } }, "/requests/{request_id}/callback_body": { "get": { "tags": [ "Request Details" ], "summary": "Callback Body", "operationId": "getCallbackBody", "description": "Returns the callback body set to client's Callback URL", "parameters": [ { "$ref": "#/components/parameters/requestId" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackBody" } } } } } } }, "/services": { "get": { "tags": [ "Manage Services" ], "summary": "List Services", "operationId": "listServices", "description": "List all active services, services are returned in batches of 100, sorted by name", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceList" } } } } } } }, "/services/{service_number}/": { "parameters": [ { "$ref": "#/components/parameters/serviceNumber" } ], "post": { "tags": [ "Manage Services" ], "summary": "Request service update", "operationId": "updateService", "description": "Update the selected service. When updating a service, only the required changes can be submitted.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceDetail" }, "examples": { "disableCallReporting": { "summary": "Disable call_reporting service", "value": { "call_reporting": { "report": "none" } } }, "updateAnswerPointName": { "summary": "Update answer_point_name", "value": { "service": { "answer_point_name": "Sidney Office New" } } }, "configureTranscription": { "summary": "Enable transcription and configure redaction", "value": { "service": { "transcription": { "transcribe_call": true, "enable_pci_redaction": true, "enable_pii_redaction": true } } } }, "assignToAiAgent": { "summary": "Assign a transfer service to an AI Agent", "value": { "service": { "answer_point": "+AIA-AIAGENTID155" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgmentReply" } } } }, "400": { "$ref": "#/components/responses/ErrorDetail" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } }, "delete": { "tags": [ "Manage Services" ], "summary": "Request service decommission", "operationId": "decommissionService", "description": "Decommission (cease) the selected service.", "requestBody": { "required": false, "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcknowledgmentReply" } } } }, "400": { "$ref": "#/components/responses/ErrorDetail" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/templates": { "get": { "tags": [ "Manage Templates" ], "summary": "List", "operationId": "listTemplates", "description": "List all available Templates", "x-apiary-uri-template": "/templates", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } }, "post": { "tags": [ "Manage Templates" ], "summary": "Create or Update", "operationId": "createOrUpdateTemplate", "description": "Templates support Call Tags", "x-apiary-uri-template": "/templates?type={type}&name={name}&country={country}", "parameters": [ { "$ref": "#/components/parameters/templateName" }, { "$ref": "#/components/parameters/templateCountry" }, { "$ref": "#/components/parameters/templateType" } ], "requestBody": { "required": false, "content": { "text/html": { "schema": { "type": "string" }, "example": "\n \n New Call for your service `__adname__` (`__bnum__`) at `__dateTime__`.\n\n We tried to forward the call to `__outnum__`.\n\n Download the voicemail at `__LINK__`\n \n\n" } } }, "responses": { "200": { "$ref": "#/components/responses/GenericSuccess" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } }, "delete": { "tags": [ "Manage Templates" ], "summary": "Delete Template", "operationId": "deleteTemplate", "description": "Delete the selected template", "x-apiary-uri-template": "/templates?type={type}&name={name}&country={country}", "parameters": [ { "name": "name", "in": "query", "required": true, "description": "desired template to preview", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/templateCountry" }, { "$ref": "#/components/parameters/templateType" } ], "requestBody": { "required": false, "content": { "text/html": { "schema": { "type": "string" } } } }, "responses": { "200": { "$ref": "#/components/responses/GenericSuccess" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "DELETE", "path": "/templates", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "Template is in use", "code": 400 }, "errors": { "name": "template is in use" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/templates?name={name}&country={country}": { "get": { "tags": [ "Manage Templates" ], "summary": "Preview Template", "operationId": "previewTemplate", "description": "Preview the selected template", "x-apiary-uri-template": "/templates?name={name}&country={country}", "parameters": [ { "name": "name", "in": "path", "required": true, "description": "desired template name", "schema": { "type": "string" } }, { "name": "country", "in": "path", "required": true, "description": "country this template is for", "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/GenericSuccess" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/aiagents": { "get": { "tags": [ "AI Agents" ], "summary": "List AI Agents", "operationId": "listAiAgents", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentList" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": "1234", "request": { "api-version": "v1", "method": "GET", "path": "/v1/aiagents", "time": "2026-10-07T20:46:29+11:00", "ms": "1.710" } }, "response": [ { "id": 120, "agent_name": "Education Assistant", "agent_role": "info", "custom_agent_role": null, "business_type": "education", "custom_business_type": null, "business_name": "Example Education", "business_description": "Answers course questions and helps book consultations.", "contact_email": "info@example.tld", "greeting": "friendly", "voice": "alloy", "instructions": "Answer questions about education services and help callers book a consultation.", "created_at": "2026-01-30T05:34:00.000Z", "@links": { "agent_uri": "/aiagents/120" } }, { "id": 223, "agent_name": "Dental Reception Assistant", "agent_role": "other", "custom_agent_role": "reception dentistry assistant", "business_type": "other", "custom_business_type": "dental practice", "business_name": "Example Dental", "business_description": "Dental practice answering appointment and general enquiry calls.", "contact_email": null, "greeting": "friendly", "voice": "echo", "instructions": "Greet callers, answer general questions, and help schedule dental appointments.", "created_at": "2026-10-07T09:44:47.000Z", "@links": { "agent_uri": "/aiagents/223" } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/AIAgentServiceError" }, "503": { "$ref": "#/components/responses/AIAgentServiceNotConfigured" } } }, "post": { "tags": [ "AI Agents" ], "summary": "Create AI Agent", "operationId": "createAiAgent", "description": "`agent_name`, `voice`, and `business_description` are required. When `instructions` are omitted or empty, they are generated from the submitted details; `agent_role`, `business_type`, and `business_name` are then required, with the matching custom field when a role or business type is `other`.\n\n`greeting` is optional. When omitted, AVANSER stores `friendly`, which is returned in the created agent.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentCreateForm" }, "example": { "agent_name": "Reception AI", "voice": "alloy", "agent_role": "receptionist", "business_type": "realestate", "business_name": "Example Realty", "business_description": "Real estate agency based in Sydney", "contact_email": "reception@example.tld" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentReply" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": "1234", "request": { "api-version": "v1", "method": "POST", "path": "/v1/aiagents", "time": "2026-10-07T20:46:29+11:00", "ms": "7.015" } }, "response": { "message": "Success", "code": 200, "agent": { "id": 223, "agent_name": "Dental Reception Assistant", "agent_role": "other", "custom_agent_role": "reception dentistry assistant", "business_type": "other", "custom_business_type": "dental practice", "business_name": "Example Dental", "business_description": "Dental practice answering appointment and general enquiry calls.", "contact_email": null, "greeting": "friendly", "voice": "echo", "instructions": "Greet callers, answer general questions, and help schedule dental appointments.", "created_at": "2026-10-07T09:44:47.000Z", "@links": { "agent_uri": "/aiagents/223" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestAgentName" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/AIAgentServiceError" }, "503": { "$ref": "#/components/responses/AIAgentServiceNotConfigured" } } } }, "/aiagents/options": { "get": { "tags": [ "AI Agents" ], "summary": "List Agent Options", "operationId": "listAiAgentOptions", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentOptionsReply" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": "1234", "request": { "api-version": "v1", "method": "GET", "path": "/v1/aiagents/options", "time": "2026-10-07T20:46:29+11:00", "ms": "1.852" } }, "response": { "voices": [ { "label": "Alloy (neutral / clear)", "key": "alloy" }, { "label": "Ash (soft / intimate)", "key": "ash" }, { "label": "Ballad (melodic / storytelling)", "key": "ballad" }, { "label": "Coral (bright / engaging)", "key": "coral" }, { "label": "Echo (bold / resonant)", "key": "echo" }, { "label": "Sage (calm / thoughtful)", "key": "sage" }, { "label": "Shimmer (light / radiant)", "key": "shimmer" }, { "label": "Verse (poetic / lyrical)", "key": "verse" }, { "label": "Marin (smooth / flowing)", "key": "marin" }, { "label": "Cedar (warm / grounded)", "key": "cedar" } ], "assistantTypes": [ { "label": "Personal Assistant", "key": "personal" }, { "label": "Business Assistant", "key": "business" } ], "businessTypes": [ { "label": "Professional Services", "key": "professional" }, { "label": "Healthcare", "key": "healthcare" }, { "label": "Real Estate", "key": "realestate" }, { "label": "Legal Services", "key": "legal" }, { "label": "Home Services", "key": "home" }, { "label": "Retail/E-commerce", "key": "retail" }, { "label": "Restaurant/Food", "key": "restaurant" }, { "label": "Technology", "key": "technology" }, { "label": "Education", "key": "education" }, { "label": "Automotive", "key": "automotive" }, { "label": "Governance", "key": "governance" }, { "label": "Consulting", "key": "consulting" }, { "label": "Marketing", "key": "marketing" }, { "label": "Directory", "key": "directory" }, { "label": "OEM (Original Equipment Manufacturer)", "key": "oem" }, { "label": "Insurance", "key": "insurance" }, { "label": "Finance", "key": "finance" }, { "label": "Other", "key": "other", "formFields": [ { "component": "input", "model": "customBusinessType", "props": { "label": "Enter Business Type", "placeholder": "e.g., Transportation services" } } ] } ], "personalAgentRoles": [ { "label": "Personal Assistant", "key": "personal_assistant" }, { "label": "Call Screener", "key": "call_screener" }, { "label": "Message Taker", "key": "message_taker" } ], "agentRoles": [ { "label": "Receptionist/Assistant", "key": "receptionist" }, { "label": "Customer Support", "key": "support" }, { "label": "Sales Assistant", "key": "sales" }, { "label": "Information Provider", "key": "info" }, { "label": "Other", "key": "other", "formFields": [ { "component": "input", "model": "customAgentRole", "props": { "label": "Enter Agent Role", "placeholder": "e.g., Booking Assistant" } } ] } ], "greetingStyles": [ { "label": "Professional & Formal", "key": "formal" }, { "label": "Friendly & Casual", "key": "friendly" }, { "label": "Brief & Direct", "key": "brief" }, { "label": "Warm & Personal", "key": "warm" } ], "transferBehaviors": [ { "label": "Transfer immediately for urgent matters", "key": "urgent_immediate" }, { "label": "Try to help first, then transfer", "key": "help_first" }, { "label": "Only transfer during business hours", "key": "business_hours" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/AIAgentServiceError" }, "503": { "$ref": "#/components/responses/AIAgentServiceNotConfigured" } } } }, "/aiagents/preview-instruction": { "post": { "tags": [ "AI Agents" ], "summary": "Preview AI Agent Instructions", "operationId": "previewAiAgentInstructions", "description": "Generate instructions without creating an agent. `agent_name`, `agent_role`, `business_type`, `business_name`, and `business_description` are required, with the matching custom field when a role or business type is `other`. `greeting` is optional; `voice` and `instructions` are ignored.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentInstructionsForm" }, "example": { "agent_name": "Reception AI", "agent_role": "receptionist", "business_type": "realestate", "business_name": "Example Realty", "business_description": "Real estate agency based in Sydney", "contact_email": "reception@example.tld", "greeting": "warm" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentInstructionsReply" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": "1234", "request": { "api-version": "v1", "method": "POST", "path": "/v1/aiagents/preview-instruction", "time": "2026-10-07T20:46:29+11:00", "ms": "10.389" } }, "response": { "message": "Success", "code": 200, "instructions": "### Role and Responsibilities\n- Answer callers as a reception assistant.\n- Help with appointments and general questions." } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/AIAgentServiceError" }, "503": { "$ref": "#/components/responses/AIAgentServiceNotConfigured" } } } }, "/aiagents/{agent_id}": { "parameters": [ { "$ref": "#/components/parameters/agentId" } ], "get": { "tags": [ "AI Agents" ], "summary": "Get AI Agent Details", "operationId": "getAiAgent", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentDetailReply" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": "1234", "request": { "api-version": "v1", "method": "GET", "path": "/v1/aiagents/120", "time": "2026-10-07T20:46:29+11:00", "ms": "1.731" } }, "response": { "id": 120, "agent_name": "Education Assistant", "agent_role": "info", "custom_agent_role": null, "business_type": "education", "custom_business_type": null, "business_name": "Example Education", "business_description": "Answers course questions and helps book consultations.", "contact_email": "info@example.tld", "greeting": "friendly", "voice": "alloy", "instructions": "Answer questions about education services and help callers book a consultation.", "created_at": "2026-01-30T05:34:00.000Z", "@links": { "agent_uri": "/aiagents/120" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestAgentId" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/AgentNotFound" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/AIAgentServiceError" }, "503": { "$ref": "#/components/responses/AIAgentServiceNotConfigured" } } }, "put": { "tags": [ "AI Agents" ], "summary": "Update AI Agent", "operationId": "updateAiAgent", "description": "Only submitted fields are changed. The resulting `agent_name`, `voice`, `business_description`, and `instructions` must remain populated, including when a field is omitted from the request. A resulting `agent_role` or `business_type` of `other` requires its matching custom field to remain populated.\n\nSubmitted `agent_role`, `business_type`, and `greeting` values are checked against List Agent Options. The resulting `voice` is checked even when it was retained from the existing agent. Instructions are never regenerated on update.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentUpdateForm" }, "examples": { "greeting": { "summary": "Update the agent greeting", "value": { "greeting": "warm" } }, "instructions": { "summary": "Update the agent instructions", "value": { "instructions": "You are the Example Realty phone assistant. Answer politely and collect the caller details." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentReply" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": "1234", "request": { "api-version": "v1", "method": "PUT", "path": "/v1/aiagents/120", "time": "2026-10-07T20:46:29+11:00", "ms": "3.150" } }, "response": { "message": "Success", "code": 200, "agent": { "id": 120, "agent_name": "Education Assistant", "agent_role": "info", "custom_agent_role": null, "business_type": "education", "custom_business_type": null, "business_name": "Example Education", "business_description": "Answers course questions and helps book consultations.", "contact_email": "info@example.tld", "greeting": "friendly", "voice": "alloy", "instructions": "Answer questions about education services and help callers book a consultation.", "created_at": null, "@links": { "agent_uri": "/aiagents/120" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestAgentName" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/AgentNotFound" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/AIAgentServiceError" }, "503": { "$ref": "#/components/responses/AIAgentServiceNotConfigured" } } }, "delete": { "tags": [ "AI Agents" ], "summary": "Delete AI Agent", "operationId": "deleteAiAgent", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentDeleteReply" } } } }, "400": { "$ref": "#/components/responses/BadRequestAgentAssigned" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/AgentNotFound" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/AIAgentServiceError" }, "503": { "$ref": "#/components/responses/AIAgentServiceNotConfigured" } } } }, "/aiagents/{agent_id}/advanced-settings": { "parameters": [ { "$ref": "#/components/parameters/agentId" } ], "get": { "tags": [ "AI Agents" ], "summary": "Get AI Agent Advanced Settings", "operationId": "getAiAgentAdvancedSettings", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentAdvancedSettingsGetReply" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": "1234", "request": { "api-version": "v1", "method": "GET", "path": "/v1/aiagents/120/advanced-settings", "time": "2026-10-07T20:46:29+11:00", "ms": "2.127" } }, "response": { "tools": { "label": "Tools", "type": "group", "description": "Available tools for the agent", "children": { "scheduling": { "label": "Add Calendar", "type": "boolean", "component": "checkBox", "default": false, "description": "", "value": true, "formFields": [ { "component": "input", "model": "scheduleLink", "value": "https://calendly.com/example", "props": { "label": "Schedule Link", "placeholder": "e.g., https://calendly.com/your-link" } } ] }, "send_email": { "label": "Send Email", "type": "boolean", "component": "checkBox", "default": false, "description": "Allows the AI to send emails during the call.", "value": true }, "red_alert": { "label": "Enable Red Alert Webhook", "type": "boolean", "component": "checkBox", "default": false, "description": "Send a red alert webhook when urgent escalation is required", "value": true, "formFields": [ { "component": "input", "model": "red_alert_webhook_url", "value": "https://example.tld/webhook", "props": { "label": "Red Alert Webhook URL", "placeholder": "e.g., https://your-domain.com/webhook" } } ] }, "background_audio": { "label": "Enable Background Audio", "type": "boolean", "component": "checkBox", "default": false, "description": "Play ambient background audio during the conversation.", "value": false, "formFields": [ { "component": "input", "model": "office_noise_url", "value": null, "props": { "label": "Background Audio URL", "placeholder": "e.g., https://example.com/audio.mp3" } }, { "component": "input", "model": "office_noise_volume", "value": 0.5, "props": { "label": "Background Audio Volume", "placeholder": "Enter a value between 0 and 1 (e.g., 0.3)" }, "type": "number", "min": 0, "max": 1, "default": 0.5 } ] }, "call_outcome_webhook": { "label": "Enable Call Outcome Webhook", "type": "boolean", "component": "checkBox", "default": false, "description": "Send call outcome to webhook after call ends", "value": false, "formFields": [ { "component": "input", "model": "calloutcome_webhook_url", "value": null, "props": { "label": "Call Outcome Webhook URL", "placeholder": "e.g., https://your-domain.com/webhook" } } ] } } }, "transfer_call": { "label": "Transfer call", "type": "group", "description": "", "children": { "find_next_folder": { "label": "Transfer calls", "type": "boolean", "component": "checkBox", "default": false, "description": "", "value": true, "assigned_route_ids": [] } } }, "fine_tuning": { "label": "Speech Fine-tuning", "type": "group", "description": "", "children": { "speed": { "label": "Speech Speed", "type": "number", "component": "input", "default": 1, "description": "Controls how fast the AI speaks.", "value": 1, "min": 0.25, "max": 1.5 }, "temperature": { "label": "Response Creativity", "type": "number", "component": "input", "default": 0.8, "description": "Controls response randomness.", "value": 0.7, "min": 0, "max": 2 }, "no_barge_seconds": { "label": "No Barge Seconds", "type": "number", "component": "input", "default": null, "description": "Prevents callers from interrupting the greeting.", "value": 2, "min": 0, "max": 60 }, "drop_on_silence": { "label": "Drop Call on Silence", "type": "boolean", "component": "checkBox", "default": false, "description": "End calls after extended caller silence.", "value": true }, "silence_prompt_ms": { "label": "Silence Prompt (ms)", "type": "number", "component": "input", "default": null, "description": "Silence before asking whether the caller is still there.", "value": 1000, "conditional": { "field": "drop_on_silence", "value": true }, "min": 0, "max": 30000 }, "silence_drop_ms": { "label": "Silence Drop (ms)", "type": "number", "component": "input", "default": null, "description": "Maximum silence before ending a call.", "value": null, "conditional": { "field": "drop_on_silence", "value": true }, "min": 0, "max": 60000 }, "vad_method": { "label": "Voice Activity Detection Method", "type": "string", "component": "select", "default": "server_vad", "description": "Audio segmentation method.", "value": "server_vad", "options": [ { "label": "Server VAD (silence-based)", "value": "server_vad" }, { "label": "Semantic VAD (content-based)", "value": "semantic_vad" } ] }, "vad_prefix_padding_ms": { "label": "Voice Detection Prefix Padding (ms)", "type": "number", "component": "input", "default": 300, "description": "Audio kept before detected speech starts.", "value": 300, "conditional": { "field": "vad_method", "value": "server_vad" }, "min": 0, "max": 5000 }, "vad_silence_duration_ms": { "label": "Silence Duration Before Stop (ms)", "type": "number", "component": "input", "default": 700, "description": "Silence before speech is considered complete.", "value": 500, "conditional": { "field": "vad_method", "value": "server_vad" }, "min": 100, "max": 10000 }, "vad_threshold": { "label": "Voice Activity Detection Threshold", "type": "number", "component": "input", "default": 0.7, "description": "Sensitivity for detecting speech against background noise.", "value": 0.1, "conditional": { "field": "vad_method", "value": "server_vad" }, "min": 0, "max": 1 }, "vad_eagerness": { "label": "VAD Eagerness", "type": "number", "component": "input", "default": 0.6, "description": "How eager semantic VAD is to stop listening.", "value": 0.1, "conditional": { "field": "vad_method", "value": "semantic_vad" }, "min": 0, "max": 1 }, "avanser_bnum_in_instr": { "label": "Inject tracking number into AI instructions", "type": "boolean", "component": "checkBox", "default": false, "description": "Inserts the tracking number into AI instructions.", "value": false } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestAgentId" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/AgentNotFound" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/AIAgentServiceError" }, "503": { "$ref": "#/components/responses/AIAgentServiceNotConfigured" } } }, "put": { "tags": [ "AI Agents" ], "summary": "Update AI Agent Advanced Settings", "operationId": "updateAiAgentAdvancedSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentAdvancedSettingsForm" }, "example": { "tools": { "scheduling": true, "scheduleLink": "https://calendly.com/example-realty", "send_email": false, "red_alert": true, "red_alert_webhook_url": "https://example.tld/webhook/red-alert", "background_audio": false, "office_noise_url": null, "office_noise_volume": 0.5, "call_outcome_webhook": true, "calloutcome_webhook_url": "https://example.tld/webhook/call-outcome", "find_next_folder": true }, "fine_tuning": { "speed": 1, "temperature": 0.7, "no_barge_seconds": 2, "drop_on_silence": true, "silence_prompt_ms": 1000, "silence_drop_ms": 3000, "vad_method": "server_vad", "vad_prefix_padding_ms": 300, "vad_silence_duration_ms": 500, "vad_threshold": 0.1, "vad_eagerness": 0.6, "avanser_bnum_in_instr": false }, "routes": [ { "route_id": "298788", "aiTags": [ "sales", "new-business" ] }, { "route_id": "337622", "deleted": true } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentAdvancedSettingsReply" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": "1234", "request": { "api-version": "v1", "method": "PUT", "path": "/v1/aiagents/120/advanced-settings", "time": "2026-10-07T20:46:29+11:00", "ms": "4.984" } }, "response": { "message": "Advanced settings saved successfully", "code": 200, "advanced_settings": { "tools": { "label": "Tools", "type": "group", "description": "Available tools for the agent", "children": { "scheduling": { "label": "Add Calendar", "type": "boolean", "component": "checkBox", "default": false, "description": "", "value": true, "formFields": [ { "component": "input", "model": "scheduleLink", "value": "https://calendly.com/example", "props": { "label": "Schedule Link", "placeholder": "e.g., https://calendly.com/your-link" } } ] }, "send_email": { "label": "Send Email", "type": "boolean", "component": "checkBox", "default": false, "description": "Allows the AI to send emails during the call.", "value": true }, "red_alert": { "label": "Enable Red Alert Webhook", "type": "boolean", "component": "checkBox", "default": false, "description": "Send a red alert webhook when urgent escalation is required", "value": true, "formFields": [ { "component": "input", "model": "red_alert_webhook_url", "value": "https://example.tld/webhook", "props": { "label": "Red Alert Webhook URL", "placeholder": "e.g., https://your-domain.com/webhook" } } ] }, "background_audio": { "label": "Enable Background Audio", "type": "boolean", "component": "checkBox", "default": false, "description": "Play ambient background audio during the conversation.", "value": false, "formFields": [ { "component": "input", "model": "office_noise_url", "value": null, "props": { "label": "Background Audio URL", "placeholder": "e.g., https://example.com/audio.mp3" } }, { "component": "input", "model": "office_noise_volume", "value": 0.5, "props": { "label": "Background Audio Volume", "placeholder": "Enter a value between 0 and 1 (e.g., 0.3)" }, "type": "number", "min": 0, "max": 1, "default": 0.5 } ] }, "call_outcome_webhook": { "label": "Enable Call Outcome Webhook", "type": "boolean", "component": "checkBox", "default": false, "description": "Send call outcome to webhook after call ends", "value": false, "formFields": [ { "component": "input", "model": "calloutcome_webhook_url", "value": null, "props": { "label": "Call Outcome Webhook URL", "placeholder": "e.g., https://your-domain.com/webhook" } } ] } } }, "transfer_call": { "label": "Transfer call", "type": "group", "description": "", "children": { "find_next_folder": { "label": "Transfer calls", "type": "boolean", "component": "checkBox", "default": false, "description": "", "value": true, "assigned_route_ids": [] } } }, "fine_tuning": { "label": "Speech Fine-tuning", "type": "group", "description": "", "children": { "speed": { "label": "Speech Speed", "type": "number", "component": "input", "default": 1, "description": "Controls how fast the AI speaks.", "value": 1, "min": 0.25, "max": 1.5 }, "temperature": { "label": "Response Creativity", "type": "number", "component": "input", "default": 0.8, "description": "Controls response randomness.", "value": 0.7, "min": 0, "max": 2 }, "no_barge_seconds": { "label": "No Barge Seconds", "type": "number", "component": "input", "default": null, "description": "Prevents callers from interrupting the greeting.", "value": 2, "min": 0, "max": 60 }, "drop_on_silence": { "label": "Drop Call on Silence", "type": "boolean", "component": "checkBox", "default": false, "description": "End calls after extended caller silence.", "value": true }, "silence_prompt_ms": { "label": "Silence Prompt (ms)", "type": "number", "component": "input", "default": null, "description": "Silence before asking whether the caller is still there.", "value": 1000, "conditional": { "field": "drop_on_silence", "value": true }, "min": 0, "max": 30000 }, "silence_drop_ms": { "label": "Silence Drop (ms)", "type": "number", "component": "input", "default": null, "description": "Maximum silence before ending a call.", "value": null, "conditional": { "field": "drop_on_silence", "value": true }, "min": 0, "max": 60000 }, "vad_method": { "label": "Voice Activity Detection Method", "type": "string", "component": "select", "default": "server_vad", "description": "Audio segmentation method.", "value": "server_vad", "options": [ { "label": "Server VAD (silence-based)", "value": "server_vad" }, { "label": "Semantic VAD (content-based)", "value": "semantic_vad" } ] }, "vad_prefix_padding_ms": { "label": "Voice Detection Prefix Padding (ms)", "type": "number", "component": "input", "default": 300, "description": "Audio kept before detected speech starts.", "value": 300, "conditional": { "field": "vad_method", "value": "server_vad" }, "min": 0, "max": 5000 }, "vad_silence_duration_ms": { "label": "Silence Duration Before Stop (ms)", "type": "number", "component": "input", "default": 700, "description": "Silence before speech is considered complete.", "value": 500, "conditional": { "field": "vad_method", "value": "server_vad" }, "min": 100, "max": 10000 }, "vad_threshold": { "label": "Voice Activity Detection Threshold", "type": "number", "component": "input", "default": 0.7, "description": "Sensitivity for detecting speech against background noise.", "value": 0.1, "conditional": { "field": "vad_method", "value": "server_vad" }, "min": 0, "max": 1 }, "vad_eagerness": { "label": "VAD Eagerness", "type": "number", "component": "input", "default": 0.6, "description": "How eager semantic VAD is to stop listening.", "value": 0.1, "conditional": { "field": "vad_method", "value": "semantic_vad" }, "min": 0, "max": 1 }, "avanser_bnum_in_instr": { "label": "Inject tracking number into AI instructions", "type": "boolean", "component": "checkBox", "default": false, "description": "Inserts the tracking number into AI instructions.", "value": false } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestAdvancedSettings" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/AIAgentServiceError" }, "503": { "$ref": "#/components/responses/AIAgentServiceNotConfigured" } } } }, "/aiagents/{agent_id}/assigned-numbers": { "parameters": [ { "$ref": "#/components/parameters/agentId" } ], "get": { "tags": [ "AI Agents" ], "summary": "List AI Agent Assigned Numbers", "operationId": "listAiAgentAssignedNumbers", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AIAgentAssignedNumberList" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": "1234", "request": { "api-version": "v1", "method": "GET", "path": "/v1/aiagents/120/assigned-numbers", "time": "2026-10-07T20:46:29+11:00", "ms": "2.814" } }, "response": [ { "service_number": "61267110101", "name": "Example Campaign", "custom_id": null, "custom_group": null, "number_type": "GEO", "country": "AU", "campaign_start": "2026-10-07", "answer_point": { "route_id": "342650", "name": "Example Agent", "action": "xfr", "type": "Transfer", "target": "+AIA-AIAGENTID120" }, "@links": { "service_uri": "/services/61267110101" } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequestAgentId" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/AgentNotFound" }, "500": { "$ref": "#/components/responses/UnexpectedError" }, "502": { "$ref": "#/components/responses/AIAgentServiceError" }, "503": { "$ref": "#/components/responses/AIAgentServiceNotConfigured" } } } }, "/transferroutes": { "get": { "tags": [ "AI Agents" ], "summary": "List Transfer Routes", "operationId": "listTransferRoutes", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferRouteList" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": "1234", "request": { "api-version": "v1", "method": "GET", "path": "/v1/transferroutes", "time": "2026-10-07T20:46:29+11:00", "ms": "0.837" } }, "response": [ { "id": "131219", "name": "Example transfer route", "action": "xfr", "type": "Transfer", "assignable": true, "ai_tags": [], "assigned_agent_ids": [] }, { "id": "148196", "name": "Example DONA route", "action": "don", "type": "DONA", "assignable": true, "ai_tags": [], "assigned_agent_ids": [] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequestTransferRoutes" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFoundTransferRoutes" }, "500": { "$ref": "#/components/responses/UnexpectedError" } } } } }, "components": { "securitySchemes": { "HTTP_BASIC": { "type": "http", "scheme": "basic", "description": "Contact AVANSER Support to obtain your credentials." } }, "schemas": { "Transaction": { "type": "object", "properties": { "@transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique transaction ID", "example": "c9220015e2f48bc7cf4b38186a7b2025" }, "account-id": { "type": [ "string", "number" ], "description": "Currently selected account. AI Agent responses serialize this as a string.", "example": "5995" }, "request": { "type": "object", "properties": { "api-version": { "type": "string", "description": "API Version", "example": "v1" }, "method": { "type": "string", "description": "HTTP Request Method", "example": "POST" }, "path": { "type": "string", "description": "Current resource url", "example": "/{resource}/?{parameters}" }, "time": { "type": "string", "description": "Response date/time", "example": "2016-09-06T16:13:38+10:00", "format": "date-time" }, "ms": { "type": [ "string", "number" ], "description": "Request process time in milliseconds. AI Agent responses serialize this as a string.", "example": "0.837" } } } } } } }, "items": { "type": "object", "properties": { "account-id": { "type": "number", "description": "Currently selected account" }, "account": { "type": "string", "description": "Friendly name assigned to the account", "example": "Test Account" } } }, "Accounts": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/items" } } } } ] }, "ErrorDetail": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "example": "Bad Request" }, "code": { "example": 400 } } }, "errors": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "answer_point": "invalid number" } } } } ] }, "ErrorResponse": { "allOf": [ { "$ref": "#/components/schemas/ErrorDetail" }, { "type": "object", "properties": { "errors": { "type": "object", "properties": { "description": { "type": "string", "description": "Error description", "example": "error message" }, "code": { "type": "string", "description": "Error code", "example": "error code" } } } } } ] }, "GenericSuccess": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message", "example": "Success" }, "code": { "type": "number", "description": "Confirmation code", "example": 200 } } } } } ] }, "items-2": { "type": "object", "properties": { "client_name": { "type": "string", "example": "# AVANSER test EDB" }, "client_id": { "type": "string", "example": "5995" }, "abn": { "type": "string", "example": "11 223 491 505" }, "primary_contact": { "type": "object", "properties": { "name": { "type": "string", "example": "AVANSER" }, "email": { "type": "string", "example": "test@email.com" }, "phone": { "type": "string", "example": "0412345678" } } }, "billing_contact": { "type": "object", "properties": { "name": { "type": "string", "example": "AVANSER" }, "email": { "type": "string", "example": "test@email.com" } } }, "invoice_address": { "type": "object", "properties": { "client_name": { "type": "string", "example": "AVANSER test EDB" }, "address_line_1": { "type": "string", "example": "Level 2, 152 Elizabeth St" }, "address_line_2": { "type": "string", "example": "" }, "suburb": { "type": "string", "example": "Sydney" }, "state": { "type": "string", "example": "NSW" }, "post_code": { "type": "string", "example": "2000" } } } } }, "accountDetails": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/items-2" } } } } ] }, "items-3": { "type": "object", "properties": { "package_code": { "type": "string", "example": "corporate" }, "start_date": { "type": "string", "example": "2016-12-07" }, "end_date": { "type": "string", "example": "2017-01-07" }, "setup_charge": { "type": "string", "example": "250.00" }, "monthly_charge": { "type": "string", "example": "1.00" }, "email": { "type": "string", "example": "test@email.com" }, "fixed_call_rate": { "type": "object", "properties": { "included": { "type": "string", "example": "0" }, "perMinute": { "type": "string", "example": "1.50" } } }, "rates": { "type": "array", "items": { "type": "object", "properties": { "callType": { "type": "string", "example": "default" }, "price": { "type": "string", "example": "0.25" }, "usage": { "type": "string", "example": "100" } } } } } }, "accountPackages": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/items-3" } } } } ] }, "items-4": { "type": "object", "properties": { "rate_code": { "type": "string", "example": "61" }, "description": { "type": "string", "example": "Test MMT" }, "setup_date": { "type": "string", "example": "2017-01-07" }, "setup_charge": { "type": "string", "example": "0.00" }, "rental_charge": { "type": "string", "example": "0.00" } } }, "accountNumberRates": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/items-4" } } } } ] }, "items-5": { "type": "object", "properties": { "rate_code": { "type": "string", "example": "61" }, "call_type": { "type": "string", "example": "L" }, "cost_per_minute": { "type": "string", "example": "0.39" }, "free_seconds": { "type": "string", "example": "0.00" }, "minimum_seconds": { "type": "string", "example": "0.00" } } }, "accountCallRates": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/items-5" } } } } ] }, "items-6": { "type": "object", "properties": { "setup_date": { "type": "string", "example": "2020-09-08" }, "rate": { "type": "string", "example": "0.1" } } }, "accountTranscriptionRates": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/items-6" } } } } ] }, "items-7": { "type": "object", "properties": { "feature_code": { "type": "string", "example": "TBR" }, "description": { "type": "string", "example": "Time Based Routing" }, "start_date": { "type": "string", "example": "2017-08-01" }, "end_date": { "type": "string", "example": "2017-10-01" }, "setup_charge": { "type": "string", "example": "350.00" }, "monthly_charge": { "type": "string", "example": "250.00" }, "change_charge": { "type": "string", "example": "0.00" }, "charging_method": { "type": "string", "example": "usage" }, "charge_term": { "type": "string", "example": "advance" } } }, "accountFeatures": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/items-7" } } } } ] }, "SearchElement": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "object", "properties": { "E164 Number": { "type": "object", "properties": { "country": { "type": "string", "description": "Service Country", "example": "AU" }, "region": { "type": "string", "description": "Number Region", "example": "NSW: Sydney" }, "type": { "type": "string", "description": "Number Type", "example": "GEO" }, "national": { "type": "string", "description": "Number in national format", "example": "0290081596" }, "calling_code": { "type": "string", "description": "International calling code", "example": "+61" } } } } } } } ] }, "MultipleAddresses": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "errors": { "type": "object", "properties": { "location": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Location address", "example": "Sydney, NSW, AU" }, "state": { "type": "string", "description": "Location state", "example": "NSW" }, "country": { "type": "string", "description": "Location country", "example": "AU" }, "lat_lng": { "type": "array", "description": "Geo Location", "items": { "type": "number" }, "example": [ -33.8688197, 151.2092955 ] } } } } } } } } ] }, "RequestRecord": { "type": "object", "properties": { "id": { "type": "string", "description": "Request unique id", "example": "8bc7cf4015e2f4b38186c9220a7b2025" }, "request_type": { "type": "string", "description": "Request Type", "enum": [ "create", "update", "delete" ], "example": "create" }, "custom_id": { "type": "string", "description": "Desired unique id (50 chars max)", "example": "desired id" }, "custom_group": { "type": "string", "description": "Desired unique id (50 chars max)", "example": "desired group" }, "request_date": { "type": "string", "description": "Date and time request was received (ISO 8601 Date format)", "example": "2016-09-06T16:13:38+10:00" }, "callback_date": { "type": "string", "description": "Date and time reply was sent to client's callback url (ISO 8601 Date format)", "example": "2016-09-06T16:13:38+10:00" }, "request_status": { "type": "string", "description": "Request Status", "enum": [ "pending", "completed", "pending_confirmation", "failed", "reported" ], "example": "completed" }, "message": { "type": "string", "description": "Request status notes", "example": "Request completed successfully" }, "service_number": { "type": "string", "description": "Provisioned service number", "example": "6129008596" }, "answer_point": { "type": "string", "description": "Answer Point specified at request submission", "example": "61401010000" }, "callback_url": { "type": "string", "description": "Callback-URL specified at request submission", "example": "http://preferred/host/" }, "@links": { "type": "object", "description": "Links to request raw data, returned as plain text", "properties": { "request_body": { "type": "string", "description": "submitted request body", "example": "/requests/{request_id}/request_body" }, "acknowledgment_body": { "type": "string", "description": "request acknowledgment reply body", "example": "/requests/{request_id}/acknowledgment_body" }, "callback_body": { "type": "string", "description": "request callback body sent to client's endpoint", "example": "/requests/{request_id}/callback_body" } } }, "@callback": { "type": "object", "description": "Callback information", "properties": { "last_update": { "type": "string", "description": "date of last attempt to contact client's callback-URL", "example": "2016-09-06T16:13:38+10:00" }, "status": { "description": "callback status", "enum": [ "pending", "success", "retry", "failed" ], "example": "pending" }, "http_reply": { "type": "number", "description": "Received HTTP Status code", "example": 0 } } } } }, "ListRequests": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "@next": { "type": "string", "description": "link to next 100 requests", "example": "/requests/2" }, "response": { "type": "array", "items": { "$ref": "#/components/schemas/RequestRecord" } } } } ] }, "CallReporting": { "type": "object", "description": "Email & SMS Call Reporting configuration", "properties": { "report": { "type": "string", "description": "configure Call Reporting", "enum": [ "missed", "missed-voicemail", "all-calls", "none" ], "default": "none", "example": "missed" }, "email": { "type": "object", "description": "configure email specific settings, settings are required if this object is defined", "required": [ "subject", "email_to", "email_cc", "email_bcc" ], "properties": { "subject": { "type": "string", "description": "supports call_tags", "example": "email subject" }, "email_to": { "type": "array", "description": "email TO recipient list", "items": { "type": "string" }, "example": [ "email@email.com", "another@email.com" ] }, "email_cc": { "type": "array", "description": "email CC recipient list", "items": { "type": "string" }, "example": [ "email@email.com", "another@email.com" ] }, "email_bcc": { "type": "array", "description": "email BCC recipient list", "items": { "type": "string" }, "example": [ "email@email.com", "another@email.com" ] }, "template": { "type": "string", "description": "if defined must be a valid template previously saved, if empty a standard template is used", "example": "html_email_template" } } }, "sms": { "type": "object", "description": "configure sms specific settings, settings are required if this object is defined", "required": [ "mobile" ], "properties": { "sms_id": { "type": "string", "description": "desired sms id", "default": "AVANSER", "example": "call report" }, "mobile": { "type": "string", "description": "sms recipient", "example": "614200220001" }, "template": { "type": "string", "description": "if defined must be a valid template previously saved, if empty a standard AVANSER template is used", "example": "text_sms_template" } } } } }, "Transcription": { "type": "object", "description": "Call transcription and sensitive-data redaction settings", "properties": { "transcribe_call": { "type": "boolean", "description": "Enable or disable call transcription", "example": true }, "enable_pci_redaction": { "type": "boolean", "description": "Enable or disable Payment Card Industry (PCI) data redaction in call transcriptions", "example": true }, "enable_pii_redaction": { "type": "boolean", "description": "Enable or disable Personally Identifiable Information (PII) redaction in call transcriptions", "example": true } } }, "InboundService": { "type": "object", "description": "Service configuration details", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "requested service type", "enum": [ "transfer", "voicemail", "prompt" ], "example": "transfer" }, "answer_point": { "type": "string", "description": "Desired Answer Point: an E164 number or an AI Agent answer point (+AIA-AIAGENTID{id}, +AIM-AIAGENTID{id}, or +AIS-AIAGENTID{id}); required if type = transfer.", "example": "61401010023" }, "answer_point_name": { "description": "friendly Name for Answer Point", "example": "Sydney Office" }, "record_call": { "type": "boolean", "description": "enable or disable call recording service, required if type = transfer", "example": true }, "transcription": { "$ref": "#/components/schemas/Transcription" }, "call_greeting": { "type": "string", "description": "this message is played to the calling party, type = transfer only, if empty uses client's default greeting", "example": "http://path/to/greeting.wav" }, "call_whisper": { "type": "string", "description": "this message is played to the answer point when a call is forwarded, type = transfer only, if empty uses client's default greeting", "example": "http://path/to/greeting.wav" }, "voicemail": { "type": "string", "description": "this message is played to the calling party if the call is not forwarded before recording a voicemail message, type = transfer only, if empty uses client's default greeting", "example": "http://path/to/voicemail.wav" }, "call_reporting": { "$ref": "#/components/schemas/CallReporting" } } }, "InboundRequest": { "type": "object", "properties": { "name": { "description": "Friendly name", "example": "Tracking Service 1" }, "custom_id": { "description": "custom_id is returned in the confirmation callback", "example": "{any custom unique id}" }, "service_number": { "type": "object", "description": "Provide information about the requested service", "properties": { "country": { "description": "country (ISO 3166-1 alpha-2 format)", "example": "AU" }, "search_type": { "type": "string", "description": "lookup type, only one search type supported", "enum": [ "coordinates", "location", "prefix", "number_type", "number" ], "example": "szu" }, "szu": { "type": "string", "description": "specify the SZU, required if search_type = szu", "example": "sydney" }, "radius": { "type": "number", "description": "area search radius, required if search_type = coordinates or search_type = location", "example": 20 }, "lat": { "type": "number", "description": "specify latitude, required if search_type = coordinates", "example": 55 }, "long": { "type": "number", "description": "specify longitude, required if search_type = coordinates", "example": 88.1 }, "location": { "type": "string", "description": "location address, required if search_type = location", "example": "Sydney, 2000 NSW, Australia" }, "number_type": { "type": "string", "description": "search by number type, required if search_type = number_type", "enum": [ "tollfree", "freecall", "mobile" ], "example": "tollfree" }, "number": { "description": "Number found through the Search functionalities", "example": 61290081596 } } }, "service": { "$ref": "#/components/schemas/InboundService" }, "call_uri": { "type": "string", "description": "if defined sets the url for the Call-URI functionality, each call is reported to this url if configured.", "example": "http://path/to/call_reporting_uri" }, "sms_forward_uri": { "type": "string", "description": "If defined, each inbound SMS is sent to this URL using HTTP POST, with the parameters in the request body.", "example": "http://path/to/sms_forward_uri" }, "callback_uri": { "type": "string", "description": "if defined sets the url for the Callback-URI functionality, if defined callback is sent when request status is updated.", "example": "http://path/to/callback_uri" } } }, "AcknowledgmentReply": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccess" }, { "type": "object", "properties": { "response": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Unique Request id", "example": "c9220015e2f48bc7cf4b38186a7b2025" }, "message": { "type": "string", "description": "Confirmation message", "example": "Success" }, "code": { "type": "number", "description": "Confirmation code", "example": 200 } } } } } ] }, "AcknowledgmentReplyWithServiceNumber": { "allOf": [ { "$ref": "#/components/schemas/AcknowledgmentReply" }, { "type": "object", "properties": { "response": { "type": "object", "properties": { "service_number": { "type": "string", "description": "reserved number", "example": "6129008596" }, "request_id": { "type": "string", "description": "Unique Request id", "example": "c9220015e2f48bc7cf4b38186a7b2025" }, "message": { "type": "string", "description": "Confirmation message", "example": "Success" }, "code": { "type": "number", "description": "Confirmation code", "example": 200 } } } } } ] }, "ServiceDetail": { "type": "object", "properties": { "name": { "type": "string", "description": "desired service friendly name", "example": "Tracking Service 1" }, "service_number": { "type": "string", "description": "configured service number (E164 format)", "example": "61290081596" }, "service": { "type": "object", "description": "Service configuration details", "properties": { "type": { "type": "string", "description": "requested service type", "enum": [ "transfer", "voicemail" ], "example": "transfer" }, "answer_point": { "type": "string", "description": "Desired Answer Point: an E164 number or an AI Agent answer point (+AIA-AIAGENTID{id}, +AIM-AIAGENTID{id}, or +AIS-AIAGENTID{id}); required if type = transfer.", "example": "61401010023" }, "answer_point_name": { "type": "string", "description": "friendly Name for Answer Point", "example": "Sydney Office" }, "record_call": { "type": "boolean", "description": "enable or disable call recording service, required if type = transfer", "example": true }, "transcription": { "$ref": "#/components/schemas/Transcription" }, "call_greeting": { "type": "string", "description": "this message is played to the calling party, type = transfer only, if empty uses client's default greeting", "example": "http://path/to/greeting.wav" }, "call_whisper": { "type": "string", "description": "this message is played to the answer point when a call is forwarded, type = transfer only, if empty uses client's default greeting", "example": "http://path/to/greeting.wav" }, "voicemail": { "type": "string", "description": "this message is played to the calling party if the call is not forwarded before recording a voicemail message, type = transfer only, if empty uses client's default greeting", "example": "http://path/to/voicemail.wav" }, "call_reporting": { "$ref": "#/components/schemas/CallReporting" } } }, "call_uri": { "type": "string", "description": "if defined sets the url for the Call-URI functionality, each call is reported to this url if configured.", "example": "http://path/to/call_reporting_uri" }, "sms_forward_uri": { "type": "string", "description": "If defined, each inbound SMS is sent to this URL using HTTP POST, with the parameters in the request body.", "example": "http://path/to/sms_forward_uri" }, "@links": { "type": "object", "properties": { "service_uri": { "type": "string", "description": "service update link", "example": "/services/61290081596" } } } } }, "CallbackBody": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Request Unique Id", "example": "c9220015e2f48bc7cf4b38186a7b2025" }, "custom_id": { "type": "string", "description": "Custom Id submitted during service creation", "example": "custom client id" }, "status": { "type": "string", "description": "Request status", "enum": [ "completed", "failed" ], "example": "completed" }, "message": { "type": "string", "description": "Request status explained or error reason", "example": "Request completed successfully" }, "service_number": { "type": "string", "description": "Provisioned service number, if any (E164 format)", "example": "61290081596" }, "answer_point": { "type": "string", "description": "AnswerPoint submitted during service creation (E164 format)", "example": "614201010100" } } }, "ServiceList": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "@next": { "type": "string", "description": "link to next 100 services", "example": "/services/2" }, "response": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceDetail" } } } } ] }, "Template": { "type": "object", "properties": { "name": { "type": "string", "description": "unique template name", "example": "template name" }, "type": { "type": "string", "description": "template type", "enum": [ "email", "sms" ], "example": "email" }, "country": { "type": "string", "description": "country the template is available for", "example": "AU" } } }, "TemplateList": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } } } ] }, "AIAgentDetail": { "type": "object", "description": "Configured AI Agent details.", "properties": { "id": { "type": [ "integer", "string" ], "description": "Unique agent ID.", "example": 120 }, "agent_name": { "type": "string", "description": "Friendly agent name; required on create and must remain populated on update.", "example": "Reception AI", "minLength": 1 }, "voice": { "type": "string", "description": "Voice key returned by List Agent Options; required on create and validated against current options after merging an update with stored details.", "example": "alloy", "enum": [ "alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar" ] }, "agent_role": { "type": [ "string", "null" ], "description": "Role key returned by List Agent Options.", "example": "receptionist", "enum": [ "receptionist", "support", "sales", "info", "other", null ] }, "custom_agent_role": { "type": [ "string", "null" ], "description": "Required for instruction generation when agent_role is other, and on update when the resulting role is other.", "example": "After hours receptionist" }, "business_type": { "type": [ "string", "null" ], "description": "Business type key returned by List Agent Options.", "example": "realestate", "enum": [ "professional", "healthcare", "realestate", "legal", "home", "retail", "restaurant", "technology", "education", "automotive", "governance", "consulting", "marketing", "directory", "oem", "insurance", "finance", "other", null ] }, "custom_business_type": { "type": [ "string", "null" ], "description": "Required for instruction generation when business_type is other, and on update when the resulting business type is other.", "example": "Boat dealership" }, "business_name": { "type": [ "string", "null" ], "description": "Business name used by the agent.", "example": "Example Realty" }, "business_description": { "type": [ "string", "null" ], "description": "Short business description; required on create and preview, and must remain populated on update.", "example": "Real estate agency based in Sydney" }, "contact_email": { "type": [ "string", "null" ], "description": "Business contact email; must be a valid email address when provided.", "example": "reception@example.tld", "format": "email" }, "greeting": { "type": [ "string", "null" ], "description": "Stored greeting style key returned by List Agent Options; friendly is returned when greeting was omitted on create.", "example": "friendly", "enum": [ "formal", "friendly", "brief", "warm", null ] }, "instructions": { "type": [ "string", "null" ], "description": "Agent conversational instructions, 4000 characters max. Omission or an empty value on create generates them; they must remain populated and are never regenerated on update.", "example": "You are the Example Realty phone assistant.", "maxLength": 4000 }, "created_at": { "type": [ "string", "null" ], "description": "Agent creation date and time; may be null in an update response.", "example": "2026-08-11T10:00:00+10:00", "format": "date-time" }, "@links": { "type": "object", "properties": { "agent_uri": { "type": "string", "description": "Agent detail link.", "example": "/aiagents/155" } } } } }, "AIAgentDetailReply": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "$ref": "#/components/schemas/AIAgentDetail" } } } ] }, "AIAgentList": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgentDetail" } } } } ] }, "AIAgentForm": { "type": "object", "description": "Shared agent detail fields for create and update. Update changes only submitted fields; null clears optional details. Instructions are never regenerated on update.", "properties": { "agent_name": { "type": "string", "description": "Friendly agent name; required on create and must remain populated on update.", "example": "Reception AI", "minLength": 1 }, "voice": { "type": "string", "description": "Voice key returned by List Agent Options; required on create and validated against current options after merging an update with stored details.", "example": "alloy", "enum": [ "alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar" ] }, "agent_role": { "type": [ "string", "null" ], "description": "Role key returned by List Agent Options. Required when instructions are generated.", "example": "receptionist", "enum": [ "receptionist", "support", "sales", "info", "other", null ] }, "custom_agent_role": { "type": [ "string", "null" ], "description": "Required for instruction generation when agent_role is other, and on update when the resulting role is other.", "example": "After hours receptionist" }, "business_type": { "type": [ "string", "null" ], "description": "Business type key returned by List Agent Options. Required when instructions are generated.", "example": "realestate", "enum": [ "professional", "healthcare", "realestate", "legal", "home", "retail", "restaurant", "technology", "education", "automotive", "governance", "consulting", "marketing", "directory", "oem", "insurance", "finance", "other", null ] }, "custom_business_type": { "type": [ "string", "null" ], "description": "Required for instruction generation when business_type is other, and on update when the resulting business type is other.", "example": "Boat dealership" }, "business_name": { "type": [ "string", "null" ], "description": "Business name used by the agent. Required when instructions are generated.", "example": "Example Realty" }, "business_description": { "type": "string", "description": "Short business description; required on create and preview, and cannot be cleared on update.", "example": "Real estate agency based in Sydney", "minLength": 1 }, "contact_email": { "type": [ "string", "null" ], "description": "Business contact email; must be a valid email address when provided.", "example": "reception@example.tld", "format": "email" }, "greeting": { "type": [ "string", "null" ], "description": "Greeting style key returned by List Agent Options; defaults to friendly when omitted on create, and null clears it on update.", "example": "warm", "enum": [ "formal", "friendly", "brief", "warm", null ] }, "instructions": { "type": [ "string", "null" ], "description": "Agent conversational instructions, 4000 characters max. Omission or an empty value on create generates them; they cannot be cleared or regenerated on update.", "example": "You are the Example Realty phone assistant.", "maxLength": 4000 } } }, "AIAgentCreateForm": { "allOf": [ { "$ref": "#/components/schemas/AIAgentForm" }, { "type": "object", "required": [ "agent_name", "voice", "business_description" ], "properties": { "greeting": { "default": "friendly" } }, "if": { "not": { "required": [ "instructions" ], "properties": { "instructions": { "type": "string", "minLength": 1 } } } }, "then": { "required": [ "agent_role", "business_type", "business_name" ], "properties": { "agent_role": { "type": "string" }, "business_type": { "type": "string" }, "business_name": { "type": "string", "minLength": 1 } }, "allOf": [ { "if": { "required": [ "agent_role" ], "properties": { "agent_role": { "const": "other" } } }, "then": { "required": [ "custom_agent_role" ], "properties": { "custom_agent_role": { "type": "string", "minLength": 1 } } } }, { "if": { "required": [ "business_type" ], "properties": { "business_type": { "const": "other" } } }, "then": { "required": [ "custom_business_type" ], "properties": { "custom_business_type": { "type": "string", "minLength": 1 } } } } ] } } ], "description": "agent_name, voice, and business_description are required. When instructions are omitted or empty, agent_role, business_type, and business_name are required; an other role or business type then requires its matching custom field. Greeting is optional and defaults to friendly when omitted." }, "AIAgentUpdateForm": { "allOf": [ { "$ref": "#/components/schemas/AIAgentForm" }, { "type": "object", "properties": { "instructions": { "type": "string", "minLength": 1 } } } ], "description": "Submitted fields merge with existing details. The resulting agent_name, voice, business_description, and instructions must remain populated. A resulting other role or business type requires its matching custom field. Submitted agent_role, business_type, and greeting values are checked against their option lists; the resulting voice is always checked, even if omitted." }, "AIAgentInstructionsForm": { "type": "object", "description": "Details used to generate an instruction preview. agent_name, agent_role, business_type, business_name, and business_description are required; greeting is optional, while voice and instructions are ignored.", "required": [ "agent_name", "agent_role", "business_type", "business_name", "business_description" ], "allOf": [ { "if": { "required": [ "agent_role" ], "properties": { "agent_role": { "const": "other" } } }, "then": { "required": [ "custom_agent_role" ], "properties": { "custom_agent_role": { "type": "string", "minLength": 1 } } } }, { "if": { "required": [ "business_type" ], "properties": { "business_type": { "const": "other" } } }, "then": { "required": [ "custom_business_type" ], "properties": { "custom_business_type": { "type": "string", "minLength": 1 } } } } ], "properties": { "agent_name": { "type": "string", "description": "Friendly agent name; required for an instruction preview.", "example": "Reception AI", "minLength": 1 }, "agent_role": { "type": "string", "description": "Role key returned by List Agent Options. Required when instructions are generated.", "example": "receptionist", "enum": [ "receptionist", "support", "sales", "info", "other" ] }, "custom_agent_role": { "type": [ "string", "null" ], "description": "Required when agent_role is other.", "example": "After hours receptionist" }, "business_type": { "type": "string", "description": "Business type key returned by List Agent Options. Required when instructions are generated.", "example": "realestate", "enum": [ "professional", "healthcare", "realestate", "legal", "home", "retail", "restaurant", "technology", "education", "automotive", "governance", "consulting", "marketing", "directory", "oem", "insurance", "finance", "other" ] }, "custom_business_type": { "type": [ "string", "null" ], "description": "Required when business_type is other.", "example": "Boat dealership" }, "business_name": { "type": "string", "description": "Business name used by the agent. Required when instructions are generated.", "example": "Example Realty", "minLength": 1 }, "business_description": { "type": "string", "description": "Short business description; required for an instruction preview.", "example": "Real estate agency based in Sydney", "minLength": 1 }, "contact_email": { "type": [ "string", "null" ], "description": "Business contact email; must be a valid email address when provided.", "example": "reception@example.tld", "format": "email" }, "greeting": { "type": [ "string", "null" ], "description": "Optional greeting style key returned by List Agent Options.", "example": "warm", "enum": [ "formal", "friendly", "brief", "warm", null ] } } }, "AIAgentReply": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccess" }, { "type": "object", "properties": { "response": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message.", "example": "Success" }, "code": { "type": "number", "description": "Confirmation code.", "example": 200 }, "agent": { "$ref": "#/components/schemas/AIAgentDetail" } } } } } ] }, "AIAgentInstructionsReply": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccess" }, { "type": "object", "properties": { "response": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message.", "example": "Success" }, "code": { "type": "number", "description": "Confirmation code.", "example": 200 }, "instructions": { "type": "string", "description": "Generated instructions.", "example": "You are the Example Realty phone assistant." } } } } } ] }, "AIAgentOption": { "type": "object", "required": [ "key", "label" ], "properties": { "key": { "type": "string", "description": "Value to submit.", "example": "alloy" }, "label": { "type": "string", "description": "Value to display.", "example": "Alloy (neutral / clear)" }, "formFields": { "type": "array", "description": "Additional inputs for this option, such as the custom value required by other.", "items": { "type": "object", "properties": { "component": { "type": "string", "example": "input" }, "model": { "type": "string", "example": "customAgentRole" }, "props": { "type": "object", "properties": { "label": { "type": "string", "example": "Enter Agent Role" }, "placeholder": { "type": "string", "example": "e.g., Booking Assistant" } } } } } } } }, "AIAgentOptionsReply": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "object", "properties": { "voices": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgentOption" }, "description": "Values accepted by voice." }, "assistantTypes": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgentOption" }, "description": "Assistant type options returned for client interfaces." }, "agentRoles": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgentOption" }, "description": "Values accepted by agent_role." }, "personalAgentRoles": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgentOption" }, "description": "Personal assistant role options returned for client interfaces." }, "businessTypes": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgentOption" }, "description": "Values accepted by business_type." }, "greetingStyles": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgentOption" }, "description": "Values accepted by greeting." }, "transferBehaviors": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgentOption" }, "description": "Transfer behavior options returned for client interfaces." } } } } } ] }, "AIAgentSetting": { "type": "object", "description": "Descriptor for one advanced setting.", "properties": { "label": { "type": "string", "description": "Setting label.", "example": "Send Email" }, "type": { "type": "string", "description": "Value type.", "example": "boolean", "enum": [ "boolean", "number", "string" ] }, "component": { "type": "string", "description": "Suggested input component.", "example": "checkBox", "enum": [ "checkBox", "input", "select" ] }, "default": { "description": "Value applied when submitted empty.", "oneOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "description": { "type": "string", "description": "What this setting does.", "example": "Allows the AI to send emails during the call." }, "value": { "description": "Value currently configured for this agent.", "oneOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "min": { "type": "number", "description": "Minimum accepted input value." }, "max": { "type": "number", "description": "Maximum accepted input value." }, "conditional": { "type": "object", "properties": { "field": { "type": "string", "description": "Setting this one depends on.", "example": "drop_on_silence" }, "value": { "description": "Value the dependent setting must hold.", "oneOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "null" } ] } } }, "options": { "type": "array", "description": "Accepted select values.", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Value to display.", "example": "Server VAD - silence based" }, "value": { "type": "string", "description": "Value to submit.", "example": "server_vad" } } } }, "formFields": { "type": "array", "description": "Additional fields enabled by a toggle.", "items": { "type": "object", "properties": { "component": { "type": "string", "description": "Suggested input component.", "example": "input" }, "model": { "type": "string", "description": "Field name to submit beside the toggle.", "example": "scheduleLink" }, "value": { "description": "Current field value.", "oneOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "props": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label.", "example": "Schedule Link" }, "placeholder": { "type": "string", "description": "Display placeholder.", "example": "e.g., https://calendly.com/your-link" } } }, "type": { "type": "string", "description": "Numeric type when applicable.", "example": "number" }, "min": { "type": "number" }, "max": { "type": "number" }, "default": { "type": "number" } } } }, "assigned_route_ids": { "type": "array", "description": "Routes assigned to this agent; returned for find_next_folder.", "items": { "type": "string" }, "example": [ "298788", "337622" ] } } }, "AIAgentSettingsGroup": { "type": "object", "properties": { "label": { "type": "string", "description": "Group label.", "example": "Tools" }, "type": { "type": "string", "description": "Always group.", "example": "group", "enum": [ "group" ] }, "description": { "type": "string", "description": "Group description.", "example": "Available tools for the agent." }, "children": { "type": "object", "description": "Settings keyed by setting name.", "additionalProperties": { "$ref": "#/components/schemas/AIAgentSetting" } } } }, "AIAgentAdvancedSettings": { "type": "object", "description": "Advanced settings returned as field descriptors. find_next_folder is returned in transfer_call.", "properties": { "tools": { "$ref": "#/components/schemas/AIAgentSettingsGroup" }, "transfer_call": { "$ref": "#/components/schemas/AIAgentSettingsGroup" }, "fine_tuning": { "$ref": "#/components/schemas/AIAgentSettingsGroup" } } }, "AIAgentAdvancedSettingsGetReply": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "$ref": "#/components/schemas/AIAgentAdvancedSettings" } } } ] }, "AIAgentRouteAssignment": { "type": "object", "required": [ "route_id" ], "properties": { "route_id": { "type": "string", "description": "Account menu or transfer route ID.", "example": "298788" }, "deleted": { "type": "boolean", "description": "False assigns the route; true releases it.", "default": false }, "aiTags": { "type": "array", "description": "Nonempty tags replace route tags. Omitted, empty, or blank-only tags keep existing tags.", "items": { "type": "string" }, "example": [ "sales", "new-business" ] } } }, "AIAgentAdvancedSettingsForm": { "type": "object", "description": "PUT replaces settings. Read current values, change what is needed, and submit all tools and fine_tuning fields.", "properties": { "tools": { "type": "object", "description": "Submit all tool values. Omitted fields reset to defaults; find_next_folder is submitted here.", "properties": { "scheduling": { "type": "boolean", "description": "Lets the agent share a booking link.", "default": false }, "scheduleLink": { "type": [ "string", "null" ], "description": "Booking link; cleared when scheduling is false.", "example": "https://calendly.com/example-realty", "format": "uri" }, "send_email": { "type": "boolean", "description": "Allows the agent to send email notifications during calls.", "default": false }, "red_alert": { "type": "boolean", "description": "Sends a webhook for urgent escalation.", "default": false }, "red_alert_webhook_url": { "type": [ "string", "null" ], "description": "Urgent escalation webhook; cleared when red_alert is false.", "example": "https://example.tld/webhook/red-alert", "format": "uri" }, "background_audio": { "type": "boolean", "description": "Plays ambient background audio.", "default": false }, "office_noise_url": { "type": [ "string", "null" ], "description": "Background audio URL; cleared when background_audio is false.", "example": "https://example.tld/office.mp3", "format": "uri" }, "office_noise_volume": { "type": "number", "description": "Background audio volume; cleared when background_audio is false. Submitting 0 applies the default.", "minimum": 0, "maximum": 1, "default": 0.5 }, "call_outcome_webhook": { "type": "boolean", "description": "Posts the call outcome when the call ends.", "default": false }, "calloutcome_webhook_url": { "type": [ "string", "null" ], "description": "Call outcome webhook; cleared when call_outcome_webhook is false.", "example": "https://example.tld/webhook/call-outcome", "format": "uri" }, "find_next_folder": { "type": "boolean", "description": "Lets the agent transfer calls to assigned routes. Returned in transfer_call; submitted in tools.", "default": false } } }, "fine_tuning": { "type": "object", "description": "Submit all speech settings. Omitted fields reset to defaults.", "properties": { "speed": { "type": "number", "description": "Speech speed.", "minimum": 0.25, "maximum": 1.5, "default": 1 }, "temperature": { "type": "number", "description": "Response creativity. Submitting 0 applies the default.", "minimum": 0, "maximum": 2, "default": 0.8 }, "no_barge_seconds": { "type": "number", "description": "Seconds after call start during which the caller cannot interrupt; submitting 0 applies the default.", "minimum": 0, "maximum": 60 }, "drop_on_silence": { "type": "boolean", "description": "Automatically ends a call after caller silence.", "default": false }, "silence_prompt_ms": { "type": "number", "description": "Silence before asking “Sorry, are you there?” Cleared when drop_on_silence is false.", "minimum": 0, "maximum": 30000 }, "silence_drop_ms": { "type": "number", "description": "Maximum silence before ending a call. Cleared when drop_on_silence is false.", "minimum": 0, "maximum": 60000 }, "vad_method": { "type": "string", "description": "Voice activity detection method.", "example": "server_vad", "enum": [ "server_vad", "semantic_vad" ], "default": "server_vad" }, "vad_prefix_padding_ms": { "type": "number", "description": "Audio kept before detected speech starts; server_vad only. Submitting 0 applies the default.", "minimum": 0, "maximum": 5000, "default": 300 }, "vad_silence_duration_ms": { "type": "number", "description": "Silence before speech is considered complete; server_vad only.", "minimum": 100, "maximum": 10000, "default": 700 }, "vad_threshold": { "type": "number", "description": "Speech against background noise sensitivity; server_vad only. Submitting 0 applies the default.", "minimum": 0, "maximum": 1, "default": 0.7 }, "vad_eagerness": { "type": "number", "description": "Eagerness to stop listening; semantic_vad only. Submitting 0 applies the default.", "minimum": 0, "maximum": 1, "default": 0.6 }, "avanser_bnum_in_instr": { "type": "boolean", "description": "Adds the tracking number to the agent instructions.", "default": false } } }, "routes": { "type": "array", "description": "Route assignments are merged: routes left out keep their current assignment.", "items": { "$ref": "#/components/schemas/AIAgentRouteAssignment" } } } }, "AIAgentAdvancedSettingsReply": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccess" }, { "type": "object", "properties": { "response": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message.", "example": "Advanced settings saved successfully" }, "code": { "type": "number", "example": 200 }, "advanced_settings": { "$ref": "#/components/schemas/AIAgentAdvancedSettings" } } } } } ] }, "AIAgentAnswerPoint": { "type": "object", "properties": { "route_id": { "type": "string", "description": "Menu answer point route ID.", "example": "298788" }, "name": { "type": "string", "description": "Answer point name.", "example": "AI Reception" }, "action": { "type": "string", "description": "Action type.", "example": "xfr" }, "type": { "type": [ "string", "null" ], "description": "Action type label; null when unknown.", "example": "Transfer" }, "target": { "type": "string", "description": "Stored target using an AU, MY, or SG AI Agent prefix.", "example": "+AIA-AIAGENTID155" } } }, "AIAgentAssignedNumber": { "type": "object", "properties": { "service_number": { "type": "string", "description": "Assigned service number in E164 format; as stored for virtual numbers.", "example": "61290081596" }, "name": { "type": [ "string", "null" ], "description": "Service name, when present.", "example": "Google Ads - Sydney" }, "custom_id": { "type": [ "string", "null" ], "description": "Service custom ID, when present.", "example": "GA-SYD" }, "custom_group": { "type": [ "string", "null" ], "description": "Service custom group, when present.", "example": "sydney-campaign" }, "number_type": { "type": "string", "description": "Number type; VIRT for a number provisioned without a type.", "example": "GEO" }, "country": { "type": "string", "description": "Service country, ISO 3166-1 alpha-2.", "example": "AU" }, "campaign_start": { "type": [ "string", "null" ], "description": "Campaign start date, when present.", "example": "2026-01-05", "format": "date" }, "answer_point": { "$ref": "#/components/schemas/AIAgentAnswerPoint" }, "@links": { "type": "object", "description": "Empty for a virtual number without an E164 form.", "properties": { "service_uri": { "type": "string", "description": "Service detail link, omitted for virtual numbers.", "example": "/services/61290081596" } } } } }, "AIAgentAssignedNumberList": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/AIAgentAssignedNumber" } } } } ] }, "AIAgentDeleteReply": { "allOf": [ { "$ref": "#/components/schemas/GenericSuccess" }, { "type": "object", "properties": { "response": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message.", "example": "Success" }, "code": { "type": "number", "example": 200 }, "agent_id": { "type": "string", "description": "Deleted agent ID.", "example": "155" } } } } } ] }, "TransferRoute": { "type": "object", "properties": { "id": { "type": "string", "description": "Route ID to submit as route_id in an advanced settings update.", "example": "298788" }, "name": { "type": "string", "description": "Route name.", "example": "Sales" }, "action": { "type": "string", "description": "Route action type.", "example": "xfr" }, "type": { "type": [ "string", "null" ], "description": "Action type label; null when unknown.", "example": "Transfer" }, "assignable": { "type": "boolean", "description": "Whether this route type may be assigned to an AI Agent." }, "ai_tags": { "type": "array", "description": "Current route tags, # prefixed and shared by all assigned agents.", "items": { "type": "string" }, "example": [ "#sales", "#new-business" ] }, "assigned_agent_ids": { "type": "array", "description": "AI Agents currently transferring to this route.", "items": { "type": "string" }, "example": [ "155", "177" ] } } }, "TransferRouteList": { "allOf": [ { "$ref": "#/components/schemas/Transaction" }, { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/TransferRoute" } } } } ] } }, "responses": { "BadRequestInvalidAccount": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "GET", "path": "/{resource}/?{parameters}", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "Bad Request", "code": 400 }, "errors": { "account-id": "invalid account" } } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "GET", "path": "/{resource}/?{parameters}", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "Unauthorized", "code": 401 }, "errors": { "description": "Authentication credentials were not accepted", "code": "unauthorized" } } } } }, "UnexpectedError": { "description": "Unexpected Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "GET", "path": "/{resource}/?{parameters}", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "Unexpected Error", "code": 500 }, "errors": { "description": "An unexpected server error occurred", "code": "unexpected_error" } } } } }, "GenericSuccess": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericSuccess" } } } }, "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "POST", "path": "/{resource}/?{parameters}", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "Bad Request", "code": 400 }, "errors": { "request": "invalid request" } } } } }, "ErrorDetail": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "BadRequestAgentName": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "POST", "path": "/aiagents", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "Bad Request", "code": 400 }, "errors": { "agent_name": "required" } } } } }, "AgentNotFound": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "GET", "path": "/aiagents/{agent_id}", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "Not Found", "code": 404 }, "errors": { "agent_id": "agent not found" } } } } }, "AIAgentServiceError": { "description": "AI Agent service error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "GET", "path": "/aiagents", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "AI Agent service error", "code": 502 }, "errors": { "description": "The AI Agent service returned an error", "code": "ai_agent_service_error" } } } } }, "AIAgentServiceNotConfigured": { "description": "AI Agent service is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "GET", "path": "/aiagents", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "AI Agent service is not configured", "code": 503 }, "errors": { "description": "The AI Agent service is not configured for this account", "code": "ai_agent_service_not_configured" } } } } }, "BadRequestAgentId": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "GET", "path": "/aiagents/{agent_id}", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "Bad Request", "code": 400 }, "errors": { "agent_id": "invalid" } } } } }, "BadRequestAgentAssigned": { "description": "Bad Request. The agent still has assigned tracking numbers or is targeted by a menu route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": "1234", "request": { "api-version": "v1", "method": "DELETE", "path": "/v1/aiagents/120", "time": "2026-10-07T23:09:50+11:00", "ms": "4.580" } }, "error": { "message": "Bad Request", "code": 400 }, "errors": { "agent_id": "agent has assigned tracking numbers" } } } } }, "BadRequestAdvancedSettings": { "description": "Bad Request. agent_id may be invalid or route_id may be an unsupported route type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "PUT", "path": "/aiagents/{agent_id}/advanced-settings", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "Bad Request", "code": 400 }, "errors": { "route_id": "unsupported route type" } } } } }, "BadRequestTransferRoutes": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "GET", "path": "/transferroutes", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "Bad Request", "code": 400 }, "errors": { "account-id": "user has no CONF/ADMIN rights the selected account" } } } } }, "NotFoundTransferRoutes": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "@transaction": { "id": "c9220015e2f48bc7cf4b38186a7b2025", "account-id": 1234, "request": { "api-version": "v1", "method": "GET", "path": "/transferroutes", "time": "2016-09-06T16:13:38+10:00", "ms": 0.039 } }, "error": { "message": "Not Found", "code": 404 }, "errors": { "description": "Transfer routes were not found", "code": "transfer_routes_not_found" } } } } } }, "parameters": { "requestId": { "name": "request_id", "in": "path", "required": true, "description": "Valid request id", "schema": { "type": "string" }, "example": "c9220015e2f48bc7cf4b38186a7b2025" }, "serviceNumber": { "name": "service_number", "in": "path", "required": true, "description": "valid service number (E164 format)", "schema": { "type": "string" } }, "templateName": { "name": "name", "in": "query", "required": true, "description": "desired template name", "schema": { "type": "string" } }, "templateCountry": { "name": "country", "in": "query", "required": true, "description": "country this template is for", "schema": { "type": "string" } }, "templateType": { "name": "type", "in": "query", "required": false, "description": "Type of template", "schema": { "type": "string", "enum": [ "email", "sms" ], "default": "email" }, "example": "email" }, "agentId": { "name": "agent_id", "in": "path", "required": true, "description": "Agent ID containing letters, digits, hyphens, or underscores only.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" }, "example": "155" } } } }