{ "openapi": "3.0.0", "paths": { "/health": { "get": { "description": "Returns HTTP 200 when the API can serve requests. No API key is needed. This path is at the root of the server, not under `/v1`.", "operationId": "getHealth", "parameters": [], "responses": { "200": { "description": "The API is up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "public-api" }, "uptimeSeconds": { "type": "integer", "description": "Seconds since this instance started.", "example": 3600 } }, "required": [ "status", "service", "uptimeSeconds" ] } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "503": { "description": "No API instance is healthy. The load balancer answers with this until one is." } }, "security": [], "summary": "Check that the API is up", "tags": [ "Health" ] } }, "/v1/agents": { "get": { "description": "Returns one page of the voice agents in your organization.", "operationId": "listAgents", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "The page to return. The first page is 1.", "schema": { "example": 1, "type": "number" } }, { "name": "pageSize", "required": false, "in": "query", "description": "The number of items in each page. Default: 50. Maximum: 1000.", "schema": { "example": 50, "type": "number" } } ], "responses": { "200": { "description": "A page of agents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentsListResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "List agents", "tags": [ "Agents" ] } }, "/v1/agents/{agentId}": { "get": { "description": "Returns one agent and its configuration.", "operationId": "getAgent", "parameters": [ { "name": "agentId", "required": true, "in": "path", "description": "The agent `id` (UUID) or `entityKey` (`AGT-\u2026`).", "schema": { "example": "AGT-A1B2C3", "type": "string" } } ], "responses": { "200": { "description": "The agent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no agent with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get an agent", "tags": [ "Agents" ] } }, "/v1/agents/{agentId}/calls": { "post": { "description": "Starts an outbound call. The agent talks to the person who answers. Send the number to call in `phoneNumber`. This endpoint does not use `customerId`. The call goes through `telephonyProviderId` when you send it, or through the default provider of your organization. Only `mode: \"agent\"` is possible here. A `human` call needs an operator in the web app.", "operationId": "triggerAgentCall", "parameters": [ { "name": "agentId", "required": true, "in": "path", "description": "The agent `id` (UUID) or `entityKey` (`AGT-\u2026`).", "schema": { "example": "AGT-A1B2C3", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerCallDto" } } } }, "responses": { "201": { "description": "The call is started. Use `sessionId` to find the call session later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerCallResponseDto" } } } }, "400": { "description": "The request body is not valid, or `mode` is `human`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no agent with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Start a call with an agent", "tags": [ "Agents" ] } }, "/v1/campaigns": { "get": { "description": "Returns one page of the campaigns in your organization.", "operationId": "listCampaigns", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "The page to return. The first page is 1.", "schema": { "example": 1, "type": "number" } }, { "name": "pageSize", "required": false, "in": "query", "description": "The number of items in each page. Default: 50. Maximum: 1000.", "schema": { "example": 50, "type": "number" } } ], "responses": { "200": { "description": "A page of campaigns.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignsListResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "List campaigns", "tags": [ "Campaigns" ] } }, "/v1/campaigns/{campaignId}": { "get": { "description": "Returns one campaign with its schedule, pacing, guardrails, outcomes, and source file.", "operationId": "getCampaign", "parameters": [ { "name": "campaignId", "required": true, "in": "path", "description": "The campaign `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The campaign.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no campaign with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get a campaign", "tags": [ "Campaigns" ] } }, "/v1/campaigns/{campaignId}/calls": { "post": { "description": "Starts one outbound call with the agent and the telephony provider of the campaign. Send the number to call in `phoneNumber`. This endpoint uses only `phoneNumber` and `fromNumber`. It ignores `customerId`, `mode`, and `telephonyProviderId`.", "operationId": "triggerCampaignCall", "parameters": [ { "name": "campaignId", "required": true, "in": "path", "description": "The campaign `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerCallDto" } } } }, "responses": { "201": { "description": "The call is started. Use `sessionId` to find the call session later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerCallResponseDto" } } } }, "400": { "description": "The request body or a parameter is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no campaign with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Start a campaign call", "tags": [ "Campaigns" ] } }, "/v1/campaigns/{campaignId}/sessions": { "get": { "description": "Returns one page of the calls made for this campaign, one session per call. An unknown campaign returns an empty page.", "operationId": "listCampaignSessions", "parameters": [ { "name": "campaignId", "required": true, "in": "path", "description": "The campaign `id` (UUID).", "schema": { "format": "uuid", "type": "string" } }, { "name": "page", "required": false, "in": "query", "description": "The page to return. The first page is 1.", "schema": { "example": 1, "type": "number" } }, { "name": "pageSize", "required": false, "in": "query", "description": "The number of items in each page. Default: 50. Maximum: 1000.", "schema": { "example": 50, "type": "number" } } ], "responses": { "200": { "description": "A page of call sessions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionsListResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "List the call sessions of a campaign", "tags": [ "Campaigns" ] } }, "/v1/tools/discounted-amount": { "post": { "description": "Applies percentage discounts to a total amount. Send either a `discounts` list or a `minDiscount` and `maxDiscount` pair. The pair makes a ladder of 4 discounts between the two bounds. When you send both, the pair wins.", "operationId": "calculateDiscountedAmounts", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscountedAmountRequestDto" } } } }, "responses": { "200": { "description": "The amount after each discount, in ascending order, rounded to 2 decimals.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DiscountedAmountResponseDto" } } } } }, "400": { "description": "`totalAmount` or a discount is not valid, only one bound of the pair is sent, or `minDiscount` is larger than `maxDiscount`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Calculate discounted amounts", "tags": [ "Agent Tools" ] } }, "/v1/tools/payment-dates": { "get": { "description": "Returns the earliest and the latest date a customer can promise a payment for, from the payment rules of your organization. All dates are in the organization time zone.", "operationId": "getPaymentDates", "parameters": [], "responses": { "200": { "description": "The allowed payment-date window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentDatesResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "Your organization has no payment-date rules configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get the allowed payment dates", "tags": [ "Agent Tools" ] } }, "/v1/questions": { "post": { "description": "Adds a question to a questionnaire. Drellia answers it for each conversation it evaluates. For an `options` question, send the possible answers in `allowedAnswers`.", "operationId": "createQuestion", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuestionDto" } } } }, "responses": { "201": { "description": "The new question.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionDto" } } } }, "400": { "description": "The request body or a parameter is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Create a question", "tags": [ "Questions" ] }, "get": { "description": "Returns one page of the questions in your organization. Each filter is optional. A list filter takes values separated by commas.", "operationId": "listQuestions", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "The page to return. The first page is 1.", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "deprecated": true, "description": "The older name of `pageSize`. Use `pageSize`.", "schema": { "type": "number" } }, { "name": "searchTerm", "required": false, "in": "query", "description": "Return only questions whose title contains this text.", "schema": { "example": "greeting", "type": "string" } }, { "name": "questionnaireIds", "required": false, "in": "query", "description": "Return only questions in these questionnaires. UUIDs separated by commas.", "schema": { "example": "550e8400-e29b-41d4-a716-446655440000,6f1c2d3e-4b5a-4c6d-8e7f-90a1b2c3d4e5", "type": "string" } }, { "name": "types", "required": false, "in": "query", "description": "Return only questions of these types. Values separated by commas. One of: boolean, options, text.", "schema": { "example": "boolean,options", "type": "string" } }, { "name": "alertTypeIds", "required": false, "in": "query", "description": "Return only questions linked to these alert types. UUIDs separated by commas.", "schema": { "type": "string" } }, { "name": "pageSize", "required": false, "in": "query", "description": "The number of items in each page. Default: 50. Maximum: 1000.", "schema": { "example": 50, "type": "number" } } ], "responses": { "200": { "description": "A page of questions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "List questions", "tags": [ "Questions" ] } }, "/v1/questions/{questionId}": { "get": { "description": "Returns one question.", "operationId": "getQuestion", "parameters": [ { "name": "questionId", "required": true, "in": "path", "description": "The question `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The question.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no question with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get a question", "tags": [ "Questions" ] }, "put": { "description": "Changes the fields you send. Fields you do not send do not change.", "operationId": "updateQuestion", "parameters": [ { "name": "questionId", "required": true, "in": "path", "description": "The question `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateQuestionDto" } } } }, "responses": { "200": { "description": "The updated question.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionDto" } } } }, "400": { "description": "The request body or a parameter is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no question with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Update a question", "tags": [ "Questions" ] }, "delete": { "description": "Deletes the question. Answers already recorded for it stay.", "operationId": "deleteQuestion", "parameters": [ { "name": "questionId", "required": true, "in": "path", "description": "The question `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "The question is deleted." }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no question with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Delete a question", "tags": [ "Questions" ] } }, "/v1/questions/{questionId}/stats": { "get": { "description": "Returns how many answers this question has and how many employees answered it.", "operationId": "getQuestionStats", "parameters": [ { "name": "questionId", "required": true, "in": "path", "description": "The question `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The question statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionStatsResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no question with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get question statistics", "tags": [ "Questions" ] } }, "/v1/employees": { "post": { "description": "Creates an employee. An employee must be in a department before you can create a conversation for them. Send `departmentId` here, or add them to a department later.", "operationId": "createEmployee", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmployeeDto" } } } }, "responses": { "201": { "description": "The new employee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDto" } } } }, "400": { "description": "The request body or a parameter is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Create an employee", "tags": [ "Employees" ] }, "get": { "description": "Returns one page of the employees in your organization.", "operationId": "listEmployees", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "The page to return. The first page is 1.", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "deprecated": true, "description": "The older name of `pageSize`. Use `pageSize`.", "schema": { "type": "number" } }, { "name": "searchTerm", "required": false, "in": "query", "description": "Return only employees whose name contains this text.", "schema": { "example": "Anna", "type": "string" } }, { "name": "pageSize", "required": false, "in": "query", "description": "The number of items in each page. Default: 50. Maximum: 1000.", "schema": { "example": 50, "type": "number" } }, { "name": "ignoreDeleted", "required": false, "in": "query", "description": "When `true`, leave out deleted employees.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "A page of employees.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "List employees", "tags": [ "Employees" ] } }, "/v1/employees/{employeeId}": { "get": { "description": "Returns one employee.", "operationId": "getEmployee", "parameters": [ { "name": "employeeId", "required": true, "in": "path", "description": "The employee `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The employee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no employee with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get an employee", "tags": [ "Employees" ] }, "put": { "description": "Changes the fields you send. Fields you do not send do not change.", "operationId": "updateEmployee", "parameters": [ { "name": "employeeId", "required": true, "in": "path", "description": "The employee `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmployeeDto" } } } }, "responses": { "200": { "description": "The updated employee.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDto" } } } }, "400": { "description": "The request body or a parameter is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no employee with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Update an employee", "tags": [ "Employees" ] }, "delete": { "description": "Deletes the employee. Their conversations stay. Use `ignoreDeleted=true` on the list endpoint to hide deleted employees.", "operationId": "deleteEmployee", "parameters": [ { "name": "employeeId", "required": true, "in": "path", "description": "The employee `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "The employee is deleted." }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no employee with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Delete an employee", "tags": [ "Employees" ] } }, "/v1/employees/{employeeId}/stats": { "get": { "description": "Returns counts of the conversations and answers recorded for this employee.", "operationId": "getEmployeeStats", "parameters": [ { "name": "employeeId", "required": true, "in": "path", "description": "The employee `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The employee statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeStatsResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no employee with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get employee statistics", "tags": [ "Employees" ] } }, "/v1/employees/{employeeId}/departments/{departmentId}": { "post": { "description": "An employee can be in more than one department.", "operationId": "addEmployeeToDepartment", "parameters": [ { "name": "employeeId", "required": true, "in": "path", "description": "The employee `id` (UUID).", "schema": { "format": "uuid", "type": "string" } }, { "name": "departmentId", "required": true, "in": "path", "description": "The department `id` (UUID) or `entityKey` (`DEP-\u2026`).", "schema": { "example": "DEP-A1B2C3", "type": "string" } } ], "responses": { "200": { "description": "The employee, with the department added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no employee or no department with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Add an employee to a department", "tags": [ "Employees" ] }, "delete": { "description": "Returns HTTP 200 with the employee, not 204, so you can see the departments that remain.", "operationId": "removeEmployeeFromDepartment", "parameters": [ { "name": "employeeId", "required": true, "in": "path", "description": "The employee `id` (UUID).", "schema": { "format": "uuid", "type": "string" } }, { "name": "departmentId", "required": true, "in": "path", "description": "The department `id` (UUID) or `entityKey` (`DEP-\u2026`).", "schema": { "example": "DEP-A1B2C3", "type": "string" } } ], "responses": { "200": { "description": "The employee, with the department removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no employee or no department with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Remove an employee from a department", "tags": [ "Employees" ] } }, "/v1/departments": { "post": { "description": "Creates a department. Set `evaluateTransfer` and `transferContext` when Drellia must judge whether a transfer to this department was correct.", "operationId": "createDepartment", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDepartmentDto" } } } }, "responses": { "201": { "description": "The new department.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepartmentResponseDto" } } } }, "400": { "description": "The request body or a parameter is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Create a department", "tags": [ "Departments" ] }, "get": { "description": "Returns one page of the departments in your organization.", "operationId": "listDepartments", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "The page to return. The first page is 1.", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "deprecated": true, "description": "The older name of `pageSize`. Use `pageSize`.", "schema": { "type": "number" } }, { "name": "pageSize", "required": false, "in": "query", "description": "The number of items in each page. Default: 50. Maximum: 1000.", "schema": { "example": 50, "type": "number" } } ], "responses": { "200": { "description": "A page of departments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepartmentsListResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "List departments", "tags": [ "Departments" ] } }, "/v1/departments/{departmentId}": { "get": { "description": "Returns one department.", "operationId": "getDepartment", "parameters": [ { "name": "departmentId", "required": true, "in": "path", "description": "The department `id` (UUID) or `entityKey` (`DEP-\u2026`).", "schema": { "example": "DEP-A1B2C3", "type": "string" } } ], "responses": { "200": { "description": "The department.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepartmentResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no department with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get a department", "tags": [ "Departments" ] }, "put": { "description": "Changes the fields you send. Fields you do not send do not change.", "operationId": "updateDepartment", "parameters": [ { "name": "departmentId", "required": true, "in": "path", "description": "The department `id` (UUID) or `entityKey` (`DEP-\u2026`).", "schema": { "example": "DEP-A1B2C3", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDepartmentDto" } } } }, "responses": { "200": { "description": "The updated department.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepartmentResponseDto" } } } }, "400": { "description": "The request body or a parameter is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no department with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Update a department", "tags": [ "Departments" ] }, "delete": { "description": "Deletes the department. Employees in it stay, without this department.", "operationId": "deleteDepartment", "parameters": [ { "name": "departmentId", "required": true, "in": "path", "description": "The department `id` (UUID) or `entityKey` (`DEP-\u2026`).", "schema": { "example": "DEP-A1B2C3", "type": "string" } } ], "responses": { "204": { "description": "The department is deleted." }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no department with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Delete a department", "tags": [ "Departments" ] } }, "/v1/questionnaires": { "post": { "description": "Creates a questionnaire in `draft` status. The `status` you send is ignored. Add questions to it, then set the status to `active` with an update.", "operationId": "createQuestionnaire", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuestionnaireDto" } } } }, "responses": { "201": { "description": "The new questionnaire.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireResponseDto" } } } }, "400": { "description": "The request body or a parameter is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Create a questionnaire", "tags": [ "Questionnaires" ] }, "get": { "description": "Returns one page of the questionnaires in your organization.", "operationId": "listQuestionnaires", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "The page to return. The first page is 1.", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "deprecated": true, "description": "The older name of `pageSize`. Use `pageSize`.", "schema": { "type": "number" } }, { "name": "pageSize", "required": false, "in": "query", "description": "The number of items in each page. Default: 50. Maximum: 1000.", "schema": { "example": 50, "type": "number" } } ], "responses": { "200": { "description": "A page of questionnaires.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnairesListResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "List questionnaires", "tags": [ "Questionnaires" ] } }, "/v1/questionnaires/{questionnaireId}": { "get": { "description": "Returns one questionnaire.", "operationId": "getQuestionnaire", "parameters": [ { "name": "questionnaireId", "required": true, "in": "path", "description": "The questionnaire `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The questionnaire.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no questionnaire with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get a questionnaire", "tags": [ "Questionnaires" ] }, "put": { "description": "Changes the fields you send. Fields you do not send do not change. Set `status` to `active` to start evaluations, or to `archived` to stop them.", "operationId": "updateQuestionnaire", "parameters": [ { "name": "questionnaireId", "required": true, "in": "path", "description": "The questionnaire `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateQuestionnaireDto" } } } }, "responses": { "200": { "description": "The updated questionnaire.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireResponseDto" } } } }, "400": { "description": "The request body or a parameter is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no questionnaire with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Update a questionnaire", "tags": [ "Questionnaires" ] }, "delete": { "description": "Deletes the questionnaire and stops its evaluations.", "operationId": "deleteQuestionnaire", "parameters": [ { "name": "questionnaireId", "required": true, "in": "path", "description": "The questionnaire `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "The questionnaire is deleted." }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no questionnaire with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Delete a questionnaire", "tags": [ "Questionnaires" ] } }, "/v1/questionnaires/{questionnaireId}/alerts": { "get": { "description": "Returns the alert types selected for this questionnaire. Drellia raises one of these alerts when a conversation meets its criteria.", "operationId": "getQuestionnaireAlerts", "parameters": [ { "name": "questionnaireId", "required": true, "in": "path", "description": "The questionnaire `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The selected alerts.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionnaireAlertDto" } } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no questionnaire with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "List the alerts of a questionnaire", "tags": [ "Questionnaires" ] }, "put": { "description": "Replaces the full set of selected alert types. Send all the alert IDs you want. An alert you leave out is removed. The maximum is 10.", "operationId": "setQuestionnaireAlerts", "parameters": [ { "name": "questionnaireId", "required": true, "in": "path", "description": "The questionnaire `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetQuestionnaireAlertsDto" } } } }, "responses": { "200": { "description": "The selected alerts after the change.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionnaireAlertDto" } } } } }, "400": { "description": "`alertIds` is not valid: not UUIDs, not unique, or more than 10.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no questionnaire with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Set the alerts of a questionnaire", "tags": [ "Questionnaires" ] } }, "/v1/customers": { "post": { "description": "Creates a customer in your organization. Use `externalId` to keep the identifier from your own system. Use `metadata` for extra facts the voice agents can use.", "operationId": "createCustomer", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerDto" } } } }, "responses": { "201": { "description": "The new customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponseDto" } } } }, "400": { "description": "The request body or a parameter is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Create a customer", "tags": [ "Customers" ] }, "get": { "description": "Returns one page of the customers in your organization.", "operationId": "listCustomers", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "The page to return. The first page is 1.", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "deprecated": true, "description": "The older name of `pageSize`. Use `pageSize`.", "schema": { "type": "number" } }, { "name": "externalId", "required": false, "in": "query", "description": "Return only the customer with this `externalId`.", "schema": { "example": "EXT-001", "type": "string" } }, { "name": "pageSize", "required": false, "in": "query", "description": "The number of items in each page. Default: 50. Maximum: 1000.", "schema": { "example": 50, "type": "number" } } ], "responses": { "200": { "description": "A page of customers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomersListResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "List customers", "tags": [ "Customers" ] } }, "/v1/customers/{customerId}": { "get": { "description": "Returns one customer.", "operationId": "getCustomer", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "The customer `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no customer with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get a customer", "tags": [ "Customers" ] }, "put": { "description": "Changes the fields you send. Fields you do not send do not change. Send an empty string to clear a text field.", "operationId": "updateCustomer", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "The customer `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerDto" } } } }, "responses": { "200": { "description": "The updated customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponseDto" } } } }, "400": { "description": "The request body or a parameter is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no customer with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Update a customer", "tags": [ "Customers" ] }, "delete": { "description": "Deletes the customer. Conversations that refer to the customer stay.", "operationId": "deleteCustomer", "parameters": [ { "name": "customerId", "required": true, "in": "path", "description": "The customer `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "The customer is deleted." }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no customer with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Delete a customer", "tags": [ "Customers" ] } }, "/v1/conversations": { "post": { "description": "Registers a conversation for audit. This is step 1 of 3. Step 2: add the messages, or upload the audio. Step 3: read the evaluation in the web app. On this endpoint `employeeId` and `customerId` are both required, and the employee must be in a department.", "operationId": "createConversation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConversationDto" } } } }, "responses": { "201": { "description": "The new conversation, in `PENDING` status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponseDto" } } } }, "400": { "description": "The body is not valid, `employeeId` or `customerId` is missing, or the employee is in no department.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no employee or no customer with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Create a conversation", "tags": [ "Conversations" ] }, "get": { "description": "Returns one page of the conversations in your organization.", "operationId": "listConversations", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "The page to return. The first page is 1.", "schema": { "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "deprecated": true, "description": "The older name of `pageSize`. Use `pageSize`.", "schema": { "type": "number" } }, { "name": "pageSize", "required": false, "in": "query", "description": "The number of items in each page. Default: 50. Maximum: 1000.", "schema": { "example": 50, "type": "number" } } ], "responses": { "200": { "description": "A page of conversations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationsListResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "List conversations", "tags": [ "Conversations" ] } }, "/v1/conversations/{conversationId}": { "get": { "description": "Returns one conversation.", "operationId": "getConversation", "parameters": [ { "name": "conversationId", "required": true, "in": "path", "description": "The conversation `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no conversation with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get a conversation", "tags": [ "Conversations" ] }, "put": { "description": "Changes the fields you send. Fields you do not send do not change. Set `status` to `ARCHIVED` to close the conversation.", "operationId": "updateConversation", "parameters": [ { "name": "conversationId", "required": true, "in": "path", "description": "The conversation `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversationDto" } } } }, "responses": { "200": { "description": "The updated conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationResponseDto" } } } }, "400": { "description": "The request body or a parameter is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no conversation with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Update a conversation", "tags": [ "Conversations" ] }, "delete": { "description": "Deletes the conversation, its messages, its events, and its evaluation.", "operationId": "deleteConversation", "parameters": [ { "name": "conversationId", "required": true, "in": "path", "description": "The conversation `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "The conversation is deleted." }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no conversation with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Delete a conversation", "tags": [ "Conversations" ] } }, "/v1/conversations/{conversationId}/generate-upload-url": { "post": { "description": "Returns a pre-signed URL. Upload the audio file to that URL with an HTTP PUT. Drellia transcribes the audio and evaluates the conversation. Only audio content types are accepted. A conversation can have one audio file.", "operationId": "generateFileUploadUrl", "parameters": [ { "name": "conversationId", "required": true, "in": "path", "description": "The conversation `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "description": "The file you are going to upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "fileName": { "type": "string", "description": "The file name, with its extension.", "example": "call-2026-09-22.mp3" }, "fileSize": { "type": "number", "description": "The file size in bytes.", "example": 2457600 }, "contentType": { "type": "string", "description": "The MIME type of the file. Must start with `audio/`.", "example": "audio/mpeg" }, "employeeSpeakerId": { "type": "string", "description": "The diarization speaker that is the employee, as `speaker_`. When you omit it, Drellia finds the employee from the transcript.", "example": "speaker_0" } }, "required": [ "fileName", "fileSize", "contentType" ] } } } }, "responses": { "200": { "description": "The upload URL and the key of the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadUrlResponseDto" } } } }, "400": { "description": "The content type is not audio, `employeeSpeakerId` has the wrong format, or the conversation already has an audio file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no conversation with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get an upload URL for the audio recording", "tags": [ "Conversations" ] } }, "/v1/conversations/{conversationId}/messages": { "post": { "description": "Adds the transcript of a text conversation: the messages, and optionally the events, for example a transfer. Send them in one request. Drellia evaluates the conversation after this call. The body is an object with `messages` and `events`. A bare array of messages is still accepted, but it is deprecated.", "operationId": "createConversationMessage", "parameters": [ { "name": "conversationId", "required": true, "in": "path", "description": "The conversation `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "description": "The messages and events of the conversation. Use the object form. The bare array form is deprecated.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateConversationTimelineRequestDto" }, { "type": "array", "deprecated": true, "description": "Deprecated: only messages, with no events.", "items": { "$ref": "#/components/schemas/CreateConversationMessageRequest" } } ] } } } }, "responses": { "201": { "description": "How many messages and events were saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConversationTimelineResponseDto" } } } }, "400": { "description": "A message or an event is not valid. A transfer event needs `payload.toDepartmentId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no conversation with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Add messages and events to a conversation", "tags": [ "Conversations" ] }, "get": { "description": "Returns all messages and events, each list in time order.", "operationId": "getConversationMessages", "parameters": [ { "name": "conversationId", "required": true, "in": "path", "description": "The conversation `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The messages and events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationTimelineResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no conversation with this ID in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get the messages and events of a conversation", "tags": [ "Conversations" ] } }, "/v1/interaction-context/{interactionContextId}": { "put": { "description": "Creates or replaces the data for one interaction. Store it before the call, and the agent can read it during the call. The `id` in the path must be the same as the `id` in the body. The keys in `data` must match the context fields configured for your organization.", "operationId": "storeInteractionContext", "parameters": [ { "name": "interactionContextId", "required": true, "in": "path", "description": "The interaction context `id` (UUID v4). You choose this value when you store it.", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreInteractionContextDto" } } } }, "responses": { "200": { "description": "The stored interaction context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionContextResponseDto" } } } }, "400": { "description": "The body is not valid, or the `id` in the path is not the same as the `id` in the body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Store an interaction context", "tags": [ "Interaction Context" ] }, "get": { "description": "Returns the interaction context stored with this `id`.", "operationId": "getInteractionContext", "parameters": [ { "name": "interactionContextId", "required": true, "in": "path", "description": "The interaction context `id` (UUID v4). You choose this value when you store it.", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The interaction context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionContextResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no interaction context with this identifier in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get an interaction context", "tags": [ "Interaction Context" ] } }, "/v1/interaction-context/lookup": { "get": { "description": "Returns the interaction context stored with this `externalId`.", "operationId": "lookupInteractionContext", "parameters": [ { "name": "externalId", "required": true, "in": "query", "description": "The `externalId` you sent when you stored the context.", "schema": { "example": "crm-case-48213", "type": "string" } } ], "responses": { "200": { "description": "The interaction context.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionContextResponseDto" } } } }, "400": { "description": "`externalId` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "There is no interaction context with this identifier in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Find an interaction context by external ID", "tags": [ "Interaction Context" ] } }, "/v1/providers": { "get": { "description": "Returns the communication providers of your organization. A conversation refers to the provider it came through. This list is not paginated.", "operationId": "listProviders", "parameters": [], "responses": { "200": { "description": "The providers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvidersListResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "List providers", "tags": [ "Providers" ] } }, "/v1/tools/send-email": { "post": { "description": "Sends an email to the notification recipients configured for your organization. A voice agent calls this tool when a customer says something your team must act on, for example a promise to pay. The request has no recipient field: Drellia uses the recipients from your organization configuration.", "operationId": "sendEmail", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequestDto" } } } }, "responses": { "200": { "description": "The email is queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailResponseDto" } } } }, "400": { "description": "The subject or the body is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "Your organization has no notification recipients configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "429": { "description": "Your organization sent too many emails. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "502": { "description": "The email provider rejected the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "503": { "description": "Email sending is not configured on this server (EMAIL_NOT_CONFIGURED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Send an email to your team", "tags": [ "Agent Tools" ] } }, "/v1/tools/verify-identity": { "post": { "description": "Compares the value a caller said with the value on file. The comparison tolerates speech-to-text noise, such as spaces, separators, and spelled letters. Configure `expectedValue` as a dynamic variable in your agent platform. Do not let the model fill it.", "operationId": "verifyIdentity", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyIdentityRequestDto" } } } }, "responses": { "200": { "description": "The result. When `match` is false, `reason` says why. The response never contains the expected value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyIdentityResponseDto" } } } }, "400": { "description": "`fieldType` is not supported, a value is missing, or `expectedValue` has no usable format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Verify an identity value", "tags": [ "Agent Tools" ] } }, "/v1/working-hours": { "get": { "description": "Returns the schedule that applies to every employee without an override.", "operationId": "getOrgSchedule", "parameters": [], "responses": { "200": { "description": "The organization schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkingHoursResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "Your organization has no schedule yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get the organization working hours", "tags": [ "Working Hours" ] }, "put": { "description": "Replaces the full organization schedule. Send all 7 days. Campaigns with `workingHours.source: \"organization\"` use this schedule.", "operationId": "setOrgSchedule", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetWorkingHoursDto" } } } }, "responses": { "200": { "description": "The new organization schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkingHoursResponseDto" } } } }, "400": { "description": "The body is not valid. `days` must have exactly 7 entries, one for each `dayOfWeek` from 0 to 6.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Set the organization working hours", "tags": [ "Working Hours" ] } }, "/v1/working-hours/effective": { "get": { "description": "Returns the schedule that applies. With `employeeId`, that is the employee override when one exists, or else the organization schedule. Without `employeeId`, that is the organization schedule. `resolvedFrom` says which one you got.", "operationId": "getEffectiveSchedule", "parameters": [ { "name": "employeeId", "required": false, "in": "query", "description": "The employee `id` (UUID). Omit it to get the organization schedule.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The schedule that applies, with `resolvedFrom` set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkingHoursResponseDto" } } } }, "400": { "description": "`employeeId` is not a UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "No schedule applies. Set the organization working hours first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get the effective working hours", "tags": [ "Working Hours" ] } }, "/v1/working-hours/employees/{employeeId}": { "get": { "description": "Returns the schedule set for this employee only. It replaces the organization schedule for them.", "operationId": "getEmployeeSchedule", "parameters": [ { "name": "employeeId", "required": true, "in": "path", "description": "The employee `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "The employee override.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkingHoursResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." }, "404": { "description": "This employee has no override.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Get the working hours override of an employee", "tags": [ "Working Hours" ] }, "put": { "description": "Replaces the full override for this employee. Send all 7 days.", "operationId": "setEmployeeSchedule", "parameters": [ { "name": "employeeId", "required": true, "in": "path", "description": "The employee `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetWorkingHoursDto" } } } }, "responses": { "200": { "description": "The new employee override.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkingHoursResponseDto" } } } }, "400": { "description": "The body is not valid. `days` must have exactly 7 entries, one for each `dayOfWeek` from 0 to 6.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Set the working hours override of an employee", "tags": [ "Working Hours" ] }, "delete": { "description": "After this, the organization schedule applies to the employee again.", "operationId": "deleteEmployeeSchedule", "parameters": [ { "name": "employeeId", "required": true, "in": "path", "description": "The employee `id` (UUID).", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "204": { "description": "The override is deleted." }, "401": { "description": "The API key is missing, or it is not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponseDto" } } } }, "403": { "description": "Too many requests from your IP address in the last 5 minutes. See Rate limits." } }, "security": [ { "bearer": [] }, { "api-key": [] } ], "summary": "Delete the working hours override of an employee", "tags": [ "Working Hours" ] } } }, "info": { "title": "Drellia API", "description": "## Overview\n\nThe Drellia API connects your systems to the two Drellia modules:\n\n- **Audit** \u2014 send conversations, and Drellia evaluates them against your questionnaires.\n- **Voice Agents** \u2014 read your agents and campaigns, start calls, and give your voice agents tools they can call during a conversation.\n\nBoth modules use the same organization data: customers, employees, departments, working hours, and providers.\n\nAll paths in this reference include the `/v1` prefix. Send requests to the server for your environment.\n\n### Authentication\n\nEvery endpoint, except the health check, needs an API key. Send the key in one of these two ways:\n\n- the `x-api-key` header, or\n- the `Authorization: Bearer ` header.\n\nYour Drellia account manager gives you the key. The key is a secret. Do not put it in a URL, a log, an example, source control, or browser storage. Drellia shows the key only when it issues or rotates it.\n\nA request with no key, or with a key that is not valid, gets HTTP 401.\n\n### Identifiers\n\nEvery resource has an `id`. The `id` is a UUID. Some resources also have an `entityKey`, for example `AGT-A1B2C3`. The `entityKey` is shorter and easier to read. Where a path accepts an `entityKey`, the parameter description says so.\n\n### Pagination\n\nList endpoints accept the `page` and `pageSize` query parameters. The first page is 1. The default page size is 50. The maximum page size is 1000.\n\nA list response has this shape:\n\n```json\n{ \"results\": [], \"total\": 0, \"page\": 1, \"pageSize\": 50 }\n```\n\n### Dates and times\n\nTimestamps are ISO 8601 strings in UTC, for example `2026-09-22T10:15:30.000Z`. The exception is `originalDateTime`. That field is a Unix time in milliseconds, because it comes from your own system.\n\n### Errors\n\nAn error response has an HTTP status of 400 or higher and this JSON body:\n\n```json\n{ \"statusCode\": 404, \"message\": \"Agent not found\", \"error\": \"Not Found\" }\n```\n\nFor a validation error (HTTP 400), `message` is an array with one line for each field that is not valid. The API rejects a request body that has a field it does not know.\n\nA successful delete returns HTTP 204 with no body.\n\n### Rate limits\n\nThe API accepts up to 2,000 requests in each 5-minute window from one IP address. Above that, the API returns HTTP 403 until the window ends. Contact support if you need a higher limit.\n\n### Support\n\nFor API access or integration questions, write to [support@drellia.com](mailto:support@drellia.com).", "version": "1.0", "contact": { "name": "Drellia Engineering", "url": "https://drellia.com", "email": "contact@drellia.com" }, "license": { "name": "Proprietary", "url": "https://drellia.com/terms" } }, "tags": [ { "name": "Conversations", "description": "Send conversations for audit, add their messages and events, and read the result." }, { "name": "Questionnaires", "description": "Manage the questionnaires that Drellia evaluates conversations against." }, { "name": "Questions", "description": "Manage the questions in a questionnaire." }, { "name": "Agents", "description": "Read your voice agents and start a call with one of them." }, { "name": "Campaigns", "description": "Read your campaigns, their call sessions, and start a campaign call." }, { "name": "Agent Tools", "description": "Endpoints a voice agent calls during a conversation: send an email, verify an identity, and compute values with your business rules." }, { "name": "Interaction Context", "description": "Store data about an interaction before a call, so the agent can use it during the call." }, { "name": "Customers", "description": "Manage the customers that conversations and calls refer to." }, { "name": "Employees", "description": "Manage the employees that take part in conversations." }, { "name": "Departments", "description": "Manage the departments of your organization." }, { "name": "Working Hours", "description": "Set the hours your organization and your employees work. Campaigns and evaluations use them." }, { "name": "Providers", "description": "Read the communication providers configured for your organization." }, { "name": "Health", "description": "Check that the API is up. No API key is needed." } ], "servers": [ { "url": "https://api.drellia.com", "description": "Production" } ], "components": { "securitySchemes": { "api-key": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your organization API key." }, "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "description": "The same API key, sent as a bearer token." } }, "schemas": { "ApiErrorResponseDto": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "The HTTP status code of the error.", "example": 404 }, "message": { "description": "What went wrong. A validation error (HTTP 400) returns one line for each field that is not valid.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Agent not found" }, "error": { "type": "string", "description": "The short name of the HTTP status.", "example": "Not Found" } }, "required": [ "statusCode", "message" ] }, "AgentConfigResponseDto": { "type": "object", "properties": { "language": { "type": "string", "description": "The language the agent speaks, as a language code.", "example": "es" }, "prompt": { "type": "string", "description": "The system prompt: the instructions the agent follows." }, "greeting": { "type": "string", "description": "The first sentence the agent says, word for word, when the call starts.", "example": "Hello, this is Ana from Drellia. Am I speaking with Maria?" }, "llm": { "type": "string", "description": "The language model the agent uses." }, "temperature": { "type": "number", "description": "How creative the model is. 0 is the most predictable.", "example": 0.7 }, "voiceId": { "type": "string", "description": "The `id` of the text-to-speech voice." }, "voiceModel": { "type": "string", "description": "The text-to-speech model." }, "conversationProvider": { "type": "string", "description": "Which Drellia engine runs the conversation: `null` for Drellia Flow, any other value for Drellia Pulse.", "nullable": true }, "dynamicVariablesSchema": { "type": "object", "description": "The dynamic variables sent to an external conversation engine, as a map of variable name to template. Empty for a new agent.", "additionalProperties": { "type": "string" }, "example": { "contact_name": "{{ customer.firstName }}" } }, "speed": { "type": "number", "description": "How fast the agent speaks. 1 is normal speed.", "example": 1 } }, "required": [ "language", "prompt", "llm", "temperature", "dynamicVariablesSchema", "speed" ] }, "AgentResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The agent `id`.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "entityKey": { "type": "string", "description": "The short key of the agent. Agent paths accept it in place of `id`.", "example": "AGT-A1B2C3" }, "name": { "type": "string", "description": "The name of the agent.", "example": "Ana - Collections" }, "providerId": { "type": "string", "description": "The `id` of the provider the agent runs on." }, "externalId": { "type": "string", "description": "The `id` of the agent in the provider platform." }, "departmentId": { "type": "string", "description": "The `id` of the department the agent belongs to." }, "status": { "type": "string", "description": "The status. `ACTIVE`: can take calls. `PAUSED`: does not take calls. `DRAFT`: not ready. `ARCHIVED`: no longer in use.", "enum": [ "ACTIVE", "PAUSED", "DRAFT", "ARCHIVED" ], "example": "ACTIVE" }, "phoneNumber": { "type": "string", "description": "The phone number that rings this agent for inbound calls. `null` when there is none.", "nullable": true, "example": "+34910000000" }, "createdOn": { "format": "date-time", "type": "string", "description": "When the agent was created." }, "updatedOn": { "format": "date-time", "type": "string", "description": "When the agent was last changed." }, "config": { "description": "The configuration of the agent.", "allOf": [ { "$ref": "#/components/schemas/AgentConfigResponseDto" } ] }, "placeholderWarnings": { "description": "Placeholders in the prompt or the greeting of the external agent that nothing fills: not `dynamicVariablesSchema`, and not Drellia at call time. Only a warning. Absent when Drellia could not read the external agent.", "example": [ "contact_name" ], "type": "array", "items": { "type": "string" } } }, "required": [ "id", "entityKey", "name", "status", "createdOn", "updatedOn", "config" ] }, "AgentsListResponseDto": { "type": "object", "properties": { "page": { "type": "number", "description": "The page you got.", "example": 1 }, "pageSize": { "type": "number", "description": "The number of items in each page.", "example": 50 }, "total": { "type": "number", "description": "The total number of agents.", "example": 4 }, "results": { "description": "The agents in this page.", "type": "array", "items": { "$ref": "#/components/schemas/AgentResponseDto" } } }, "required": [ "page", "pageSize", "total", "results" ] }, "TriggerCallDto": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Not used on the public API. Send `phoneNumber` instead.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "phoneNumber": { "type": "string", "description": "The phone number to call, with the country code. The voice gateway validates the format and also accepts short internal extensions. Send one of `customerId` and `phoneNumber`, not both.", "example": "+1234567890", "maxLength": 50 }, "fromNumber": { "type": "string", "description": "The number the customer sees as the caller. Default: the number of the provider.", "example": "+34910000000", "maxLength": 50 }, "mode": { "type": "string", "description": "Who talks to the customer. `agent`: the AI agent. `human`: an operator in the web app, with no AI. Default: `agent`. The public API accepts `agent` only.", "enum": [ "agent", "human" ], "default": "agent" }, "telephonyProviderId": { "type": "string", "description": "The `id` of the telephony provider to call through. It must belong to your organization. Default: the default provider of your organization.", "example": "550e8400-e29b-41d4-a716-446655440000" } } }, "TriggerCallResponseDto": { "type": "object", "properties": { "sessionId": { "type": "string", "description": "The `id` of the call session. Use it to find the session in the sessions list.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "callId": { "type": "string", "description": "The `id` of the call in the voice gateway.", "example": "6f1c2d3e-4b5a-4c6d-8e7f-90a1b2c3d4e5" }, "status": { "type": "string", "description": "The status of the call when it was started.", "example": "initiated" } }, "required": [ "sessionId", "callId", "status" ] }, "CampaignGuardrailsDto": { "type": "object", "properties": { "maxCallDurationSeconds": { "type": "number", "description": "Maximum call duration in seconds", "example": 300 }, "transferPhoneNumber": { "type": "string", "description": "Number to transfer to when the customer asks for a person" }, "recordingEnabled": { "type": "boolean", "description": "Record & transcribe calls" } } }, "BreakDto": { "type": "object", "properties": { "startTime": { "type": "string", "description": "When the break starts, as `HH:mm` (24-hour clock).", "example": "12:00" }, "endTime": { "type": "string", "description": "When the break ends, as `HH:mm` (24-hour clock).", "example": "13:00" } }, "required": [ "startTime", "endTime" ] }, "WorkingHoursDayDto": { "type": "object", "properties": { "dayOfWeek": { "type": "number", "description": "The day of the week. 0 is Sunday, 1 is Monday, and 6 is Saturday.", "minimum": 0, "maximum": 6, "example": 1 }, "startTime": { "type": "string", "description": "When work starts, as `HH:mm` (24-hour clock).", "example": "09:00" }, "endTime": { "type": "string", "description": "When work ends, as `HH:mm` (24-hour clock).", "example": "17:00" }, "isEnabled": { "type": "boolean", "description": "Whether this is a working day. Send `false` for a day off.", "example": true }, "breaks": { "description": "Breaks inside the working hours, for example lunch.", "type": "array", "items": { "$ref": "#/components/schemas/BreakDto" } } }, "required": [ "dayOfWeek", "startTime", "endTime", "isEnabled" ] }, "CampaignWorkingHoursDto": { "type": "object", "properties": { "source": { "type": "string", "description": "Where calling hours come from: the organization's working-hours schedule (resolved at dial time) or a custom per-campaign schedule", "enum": [ "organization", "custom" ] }, "days": { "description": "Per-day calling windows; required when source is 'custom'", "type": "array", "items": { "$ref": "#/components/schemas/WorkingHoursDayDto" } } }, "required": [ "source" ] }, "CampaignScheduleDto": { "type": "object", "properties": { "mode": { "type": "string", "description": "When calls go out", "enum": [ "immediate", "one_time", "recurring" ] }, "startDate": { "type": "string", "description": "Start date (YYYY-MM-DD); required for one_time" }, "time": { "type": "string", "description": "Start time (HH:mm) in the campaign timezone" }, "timezone": { "type": "string", "description": "IANA timezone name the wall-clock values (time, working hours) are read in; required whenever the schedule carries a start time or working hours", "example": "America/Panama" }, "daysOfWeek": { "description": "ISO weekdays the campaign runs on (1 = Monday \u2026 7 = Sunday); recurring only", "type": "array", "items": { "type": "number" } }, "workingHours": { "description": "Per-weekday calling hours (org default or campaign-specific); unset = unrestricted", "allOf": [ { "$ref": "#/components/schemas/CampaignWorkingHoursDto" } ] } }, "required": [ "mode" ] }, "CampaignPacingDto": { "type": "object", "properties": { "maxConcurrentCalls": { "type": "number", "description": "The campaign's own cap on calls in progress at once; null or absent means the most its telephony provider allows. Must not exceed that limit.", "example": 3, "nullable": true, "minimum": 1 }, "retryAttempts": { "type": "number", "description": "Retry attempts per contact", "enum": [ 0, 2, 3, 5 ] }, "retryWaitMinutes": { "type": "number", "description": "Wait between retries in minutes", "enum": [ 60, 240, 1440 ] }, "retryOn": { "type": "string", "description": "Which outcomes trigger a retry", "enum": [ "no_answer_busy", "no_answer", "any_failure" ] } }, "required": [ "retryAttempts", "retryWaitMinutes", "retryOn" ] }, "CampaignOutcomeResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Outcome ID" }, "code": { "type": "string", "description": "Stable outcome code" }, "label": { "type": "string", "description": "Human-readable outcome label" }, "description": { "type": "string", "description": "What this outcome means" }, "displayOrder": { "type": "number", "description": "Display order" }, "categoryId": { "type": "object", "description": "Category this outcome is grouped under" } }, "required": [ "id", "code", "label", "displayOrder" ] }, "CampaignSourceFileColumnMappingDto": { "type": "object", "properties": { "sourceColumn": { "type": "string", "description": "Source file column header", "maxLength": 255 }, "targetField": { "type": "string", "description": "Contact field the column was mapped to (or 'skip' if ignored)", "maxLength": 255 }, "autoDetected": { "type": "boolean", "description": "Whether the mapping was auto-suggested rather than chosen by the user" } }, "required": [ "sourceColumn", "targetField" ] }, "CampaignSourceFileResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Source file record ID", "format": "uuid" }, "fileName": { "type": "string", "description": "Original file name" }, "fileSize": { "type": "number", "description": "File size in bytes" }, "contentType": { "type": "string", "description": "MIME type of the file" }, "uploadStatus": { "type": "string", "description": "Upload lifecycle status" }, "columnMapping": { "description": "How each column of the file was mapped onto contact fields", "type": "array", "items": { "$ref": "#/components/schemas/CampaignSourceFileColumnMappingDto" } }, "createdOn": { "format": "date-time", "type": "string", "description": "When the file was uploaded" } }, "required": [ "id", "fileName", "fileSize", "contentType", "uploadStatus", "columnMapping", "createdOn" ] }, "CampaignResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Campaign ID" }, "entityKey": { "type": "string", "description": "The short key of the campaign, as shown in the web app. On the public API, use `id`.", "example": "CAM-A1B2C3" }, "name": { "type": "string", "description": "The name of the campaign.", "example": "September collections" }, "description": { "type": "string", "description": "Campaign description" }, "status": { "type": "string", "description": "Campaign status", "enum": [ "DRAFT", "SCHEDULED", "ACTIVE", "PAUSED", "COMPLETED", "STOPPED" ] }, "agentId": { "type": "string", "description": "Agent ID" }, "agent": { "description": "Agent details", "allOf": [ { "$ref": "#/components/schemas/AgentResponseDto" } ] }, "type": { "type": "string", "description": "Audience source type", "enum": [ "static" ] }, "tags": { "description": "Tags for filtering", "type": "array", "items": { "type": "string" } }, "voiceId": { "type": "string", "description": "Voice ID override for this campaign" }, "telephonyProviderId": { "type": "string", "description": "Telephony provider used to dial this campaign" }, "campaignPrompt": { "type": "string", "description": "Extra instructions layered on top of the agent\u2019s base behavior" }, "guardrails": { "description": "Call guardrails", "allOf": [ { "$ref": "#/components/schemas/CampaignGuardrailsDto" } ] }, "schedule": { "description": "Schedule configuration", "allOf": [ { "$ref": "#/components/schemas/CampaignScheduleDto" } ] }, "pacing": { "description": "Pacing & retry configuration", "allOf": [ { "$ref": "#/components/schemas/CampaignPacingDto" } ] }, "template": { "type": "string", "description": "Wizard template this campaign started from" }, "nextRunOn": { "format": "date-time", "type": "string", "description": "Next scheduled run (display only; engine deferred)" }, "lastRunOn": { "format": "date-time", "type": "string", "description": "Last time the campaign was launched" }, "contactCount": { "type": "number", "description": "Number of imported contacts" }, "completedCallCount": { "type": "number", "description": "Contacts whose dialing is over (completed, no-answer, failed or excluded)" }, "outcomes": { "description": "Possible call outcomes (outcomes); populated on single-campaign reads", "type": "array", "items": { "$ref": "#/components/schemas/CampaignOutcomeResponseDto" } }, "sourceFile": { "description": "Most recently uploaded contacts file and its column mapping, if contacts were imported from a file; populated on single-campaign reads", "allOf": [ { "$ref": "#/components/schemas/CampaignSourceFileResponseDto" } ] }, "createdBy": { "type": "string", "description": "Who created the campaign, as stored: a user id, or the name of the system process that did it. Absent for campaigns that predate creator attribution." }, "createdOn": { "format": "date-time", "type": "string", "description": "Creation date" }, "updatedOn": { "format": "date-time", "type": "string", "description": "Last update date" } }, "required": [ "id", "entityKey", "name", "status", "agentId", "type", "tags", "createdOn", "updatedOn" ] }, "CampaignsListResponseDto": { "type": "object", "properties": { "page": { "type": "number", "description": "The page you got.", "example": 1 }, "pageSize": { "type": "number", "description": "The number of items in each page.", "example": 50 }, "total": { "type": "number", "description": "The total number of campaigns.", "example": 12 }, "results": { "description": "The campaigns in this page.", "type": "array", "items": { "$ref": "#/components/schemas/CampaignResponseDto" } } }, "required": [ "page", "pageSize", "total", "results" ] }, "ProviderErrorDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Vendor-neutral failure code", "example": "NO_ROUTE_DESTINATION" }, "message": { "type": "string", "description": "English fallback copy for the code; null when none is defined", "nullable": true, "example": "No route to this destination \u2014 check the number or carrier configuration" } }, "required": [ "code" ] }, "CustomerResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The customer `id`.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "externalId": { "type": "string", "description": "The identifier of the customer in your own system.", "example": "EXT-001" }, "email": { "type": "string", "description": "The email address.", "example": "john.doe@example.com" }, "firstName": { "type": "string", "description": "The first name.", "example": "John" }, "lastName": { "type": "string", "description": "The last name.", "example": "Doe" }, "identificationNumber": { "type": "string", "description": "The identification number of the customer.", "example": "ID-12345" }, "phoneNumber": { "type": "string", "description": "The phone number.", "example": "+1234567890" }, "createdOn": { "format": "date-time", "type": "string", "description": "When the customer was created." }, "updatedOn": { "format": "date-time", "type": "string", "description": "When the customer was last changed." }, "metadata": { "type": "object", "description": "Extra facts about the customer, as text values.", "example": { "tier": "premium", "source": "web" }, "additionalProperties": { "type": "string" } } }, "required": [ "id", "email", "firstName", "lastName", "createdOn", "updatedOn", "metadata" ] }, "SessionEmployeeResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Employee ID" }, "firstName": { "type": "string", "description": "Employee first name" }, "lastName": { "type": "string", "description": "Employee last name" } }, "required": [ "id", "firstName", "lastName" ] }, "SessionOutcomeResponseDto": { "type": "object", "properties": { "outcomeId": { "type": "object", "description": "Catalog outcome the call is recorded with; null when none, or when the catalog row was retired", "nullable": true }, "outcomeCode": { "type": "object", "description": "Outcome code snapshotted when the outcome was recorded" }, "outcomeLabel": { "type": "object", "description": "Human-readable label from the organization's catalog; falls back to the code" }, "categoryName": { "type": "object", "description": "Category the outcome is grouped under" }, "source": { "type": "string", "description": "Who determined the outcome", "enum": [ "ai_agent", "human", "system" ] }, "systemKey": { "type": "string", "description": "For a system-assigned outcome, the platform slot the call ended on (why it was assigned); null otherwise", "enum": [ "hangup", "no_answer", "unreachable", "voicemail", "failed" ], "nullable": true }, "followUpAt": { "type": "object", "description": "When the customer agreed to be contacted again" }, "notes": { "type": "object", "description": "Free-text notes attached to the outcome", "nullable": true }, "data": { "type": "object", "description": "Scenario-specific values captured by the agent, opaque to the platform" }, "updatedOn": { "format": "date-time", "type": "string", "description": "When the outcome was last recorded or corrected" } }, "required": [ "source", "data" ] }, "SessionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Session ID" }, "entityKey": { "type": "string", "description": "The short key of the call session, as shown in the web app. On the public API, use `id`.", "example": "CAL-A1B2C3" }, "externalId": { "type": "string", "description": "External call ID" }, "conversationId": { "type": "string", "description": "Linked conversation ID" }, "agentId": { "type": "object", "description": "Agent ID \u2014 null on human-mode calls, which carry an employee instead", "nullable": true }, "employeeId": { "type": "object", "description": "Employee ID. Set on human-mode calls placed by an operator, null otherwise.", "nullable": true }, "mode": { "type": "string", "description": "Who talked to the customer: \"agent\" (the AI) or \"human\" (an operator speaking from the browser)", "enum": [ "agent", "human" ] }, "customerId": { "type": "string", "description": "Customer identifier" }, "customerName": { "type": "string", "description": "The imported contact's name, resolved for campaign session listings" }, "departmentIds": { "description": "Department IDs touched during the call", "type": "array", "items": { "type": "string" } }, "createdOn": { "format": "date-time", "type": "string", "description": "Creation date" }, "updatedOn": { "format": "date-time", "type": "string", "description": "Last update date" }, "startedOn": { "format": "date-time", "type": "string", "description": "Call start time" }, "endedOn": { "format": "date-time", "type": "string", "description": "Call end time" }, "phoneNumber": { "type": "string", "description": "Dialed phone number" }, "duration": { "type": "number", "description": "Call duration in seconds" }, "status": { "type": "string", "description": "Call status", "enum": [ "INITIATED", "RINGING", "IN_PROGRESS", "COMPLETED", "FAILED", "NO_ANSWER" ] }, "endReason": { "type": "string", "description": "Reason the call ended", "enum": [ "CLIENT_NAVIGATED_AWAY", "AGENT_ENDED", "CLIENT_ENDED", "TIMEOUT", "ERROR", "VOICEMAIL_DETECTED", "TRANSFERRED", "CALL_REJECTED" ] }, "providerError": { "description": "Why the call failed. Absent unless the call failed with a cause the platform can vouch for \u2014 `endReason` says the call errored, this says what went wrong.", "allOf": [ { "$ref": "#/components/schemas/ProviderErrorDto" } ] }, "audioUrl": { "type": "string", "description": "Audio recording URL" }, "campaignId": { "type": "string", "description": "Campaign ID" }, "direction": { "type": "string", "description": "Call direction", "enum": [ "inbound", "outbound", "demo" ] }, "customer": { "description": "Resolved customer (only present when requested via `?include=customer`)", "allOf": [ { "$ref": "#/components/schemas/CustomerResponseDto" } ] }, "agent": { "description": "Resolved agent (only present when requested via `?include=agent`)", "allOf": [ { "$ref": "#/components/schemas/AgentResponseDto" } ] }, "employee": { "description": "Resolved employee who placed a human-mode call (only present when requested via `?include=employee`)", "allOf": [ { "$ref": "#/components/schemas/SessionEmployeeResponseDto" } ] }, "campaign": { "description": "Resolved campaign (only present when requested via `?include=campaign`)", "allOf": [ { "$ref": "#/components/schemas/CampaignResponseDto" } ] }, "outcome": { "description": "The call's recorded business outcome (only present when requested via `?include=outcome`); null when requested but the call has none", "allOf": [ { "$ref": "#/components/schemas/SessionOutcomeResponseDto" } ] } }, "required": [ "id", "entityKey", "departmentIds", "createdOn", "updatedOn", "status", "direction" ] }, "SessionsListResponseDto": { "type": "object", "properties": { "page": { "type": "number", "description": "The page you got.", "example": 1 }, "pageSize": { "type": "number", "description": "The number of items in each page.", "example": 50 }, "total": { "type": "number", "description": "The total number of sessions.", "example": 100 }, "results": { "description": "The sessions in this page.", "type": "array", "items": { "$ref": "#/components/schemas/SessionResponseDto" } } }, "required": [ "page", "pageSize", "total", "results" ] }, "DiscountedAmountRequestDto": { "type": "object", "properties": { "totalAmount": { "type": "number", "description": "The amount before any discount.", "example": 100, "minimum": 0 }, "discounts": { "description": "The discounts to apply, as percentages from 0 to 100. Required when you do not send `minDiscount` and `maxDiscount`. Ignored when you send the pair.", "example": [ 10, 15, 20 ], "type": "array", "items": { "type": "number" } }, "minDiscount": { "type": "number", "description": "The smallest discount of a range, as a percentage. Send it together with `maxDiscount`. The pair wins over `discounts`.", "example": 10, "minimum": 0, "maximum": 100 }, "maxDiscount": { "type": "number", "description": "The largest discount of a range, as a percentage. Send it together with `minDiscount`. The pair wins over `discounts`.", "example": 40, "minimum": 0, "maximum": 100 } }, "required": [ "totalAmount" ] }, "DiscountedAmountResponseDto": { "type": "object", "properties": { "discount": { "type": "number", "description": "The discount applied, as a percentage.", "example": 15 }, "discountedAmount": { "type": "number", "description": "The amount after the discount, rounded to 2 decimals.", "example": 85 } }, "required": [ "discount", "discountedAmount" ] }, "PaymentDatesResponseDto": { "type": "object", "properties": { "minDate": { "type": "string", "description": "The earliest allowed payment date, as `YYYY-MM-DD`. This is today.", "example": "2026-07-02" }, "maxDate": { "type": "string", "description": "The latest allowed payment date, as `YYYY-MM-DD`. Your payment rules set how far ahead it is.", "example": "2026-08-31" }, "today": { "type": "string", "description": "Today, as `YYYY-MM-DD`, in the organization time zone.", "example": "2026-07-02" }, "timezone": { "type": "string", "description": "The IANA time zone the dates are in.", "example": "America/Argentina/Buenos_Aires" } }, "required": [ "minDate", "maxDate", "today", "timezone" ] }, "CreateQuestionDto": { "type": "object", "properties": { "title": { "type": "string", "description": "The question, as Drellia must answer it.", "example": "Did the employee greet the customer by name?", "minLength": 2, "maxLength": 255 }, "description": { "type": "string", "description": "More detail on how to answer the question.", "example": "Any use of the first name or the last name counts.", "maxLength": 1000 }, "questionnaireId": { "type": "string", "description": "The `id` of the questionnaire to add the question to.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "allowedAnswers": { "description": "The possible answers, for an `options` question.", "example": [ "yes", "no", "not applicable" ], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "description": "The kind of answer. `boolean`: yes or no. `options`: one of `allowedAnswers`. `text`: free text.", "enum": [ "boolean", "options", "text" ], "example": "options" }, "alertTypeId": { "type": "string", "description": "The `id` of the alert type to raise when the answer is not compliant.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "compliantAnswer": { "type": "string", "description": "The answer that means the employee did the right thing.", "example": "yes", "maxLength": 255 }, "compliantAnswers": { "description": "All the answers that mean the employee did the right thing. When you send both, this list wins over `compliantAnswer`.", "example": [ "yes", "not applicable" ], "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "description": "Extra data of your own. Drellia stores it and returns it as is.", "additionalProperties": true } }, "required": [ "title", "questionnaireId", "type" ] }, "QuestionDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The question `id`.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "title": { "type": "string", "description": "The question, as Drellia answers it.", "example": "Did the employee greet the customer by name?" }, "description": { "type": "string", "description": "More detail on how to answer the question.", "example": "Any use of the first name or the last name counts." }, "questionnaireId": { "type": "string", "description": "The `id` of the questionnaire the question is in.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "allowedAnswers": { "description": "The possible answers, for an `options` question.", "example": [ "yes", "no", "not applicable" ], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "description": "The kind of answer. `boolean`: yes or no. `options`: one of `allowedAnswers`. `text`: free text.", "enum": [ "boolean", "options", "text" ], "example": "options" }, "alertTypeId": { "type": "string", "description": "The `id` of the alert type raised when the answer is not compliant.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "compliantAnswer": { "type": "string", "description": "The answer that means the employee did the right thing.", "example": "yes" }, "compliantAnswers": { "description": "All the answers that mean the employee did the right thing. When you send both, this list wins over `compliantAnswer`.", "example": [ "yes", "not applicable" ], "type": "array", "items": { "type": "string" } }, "createdOn": { "format": "date-time", "type": "string", "description": "When the question was created." }, "updatedOn": { "format": "date-time", "type": "string", "description": "When the question was last changed." }, "answerCount": { "type": "number", "description": "The number of answers recorded for this question.", "example": 120 }, "questionnaireName": { "type": "string", "description": "The name of the questionnaire the question is in.", "example": "Customer service quality" }, "thumbsUpCount": { "type": "number", "description": "The number of times a reviewer marked an answer as correct.", "example": 12 }, "thumbsDownCount": { "type": "number", "description": "The number of times a reviewer marked an answer as wrong.", "example": 3 }, "feedbackBalance": { "type": "number", "description": "`thumbsUpCount` minus `thumbsDownCount`. A negative value means more wrong answers.", "example": 9 }, "needsFeedbackReview": { "type": "boolean", "description": "Whether the question needs a review, because of the feedback it got.", "example": false } }, "required": [ "id", "title", "questionnaireId", "type", "createdOn", "updatedOn" ] }, "QuestionResponseDto": { "type": "object", "properties": { "page": { "type": "number", "description": "The page you got.", "example": 1 }, "pageSize": { "type": "number", "description": "The number of items in each page.", "example": 50 }, "total": { "type": "number", "description": "The total number of questions.", "example": 45 }, "results": { "description": "The questions in this page.", "type": "array", "items": { "$ref": "#/components/schemas/QuestionDto" } } }, "required": [ "page", "pageSize", "total", "results" ] }, "UpdateQuestionDto": { "type": "object", "properties": { "title": { "type": "string", "description": "The question, as Drellia must answer it.", "example": "Did the employee greet the customer by name?", "minLength": 2, "maxLength": 255 }, "description": { "type": "string", "description": "More detail on how to answer the question.", "example": "Any use of the first name or the last name counts.", "maxLength": 1000 }, "allowedAnswers": { "description": "The possible answers, for an `options` question.", "example": [ "yes", "no", "not applicable" ], "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "description": "The kind of answer. `boolean`: yes or no. `options`: one of `allowedAnswers`. `text`: free text.", "enum": [ "boolean", "options", "text" ], "example": "options" }, "alertTypeId": { "type": "string", "description": "The `id` of the alert type to raise when the answer is not compliant.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "compliantAnswer": { "type": "string", "description": "The answer that means the employee did the right thing.", "example": "yes", "maxLength": 255 }, "compliantAnswers": { "description": "All the answers that mean the employee did the right thing. When you send both, this list wins over `compliantAnswer`.", "example": [ "yes", "not applicable" ], "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "description": "Extra data of your own. Drellia stores it and returns it as is.", "additionalProperties": true } } }, "QuestionStatsResponseDto": { "type": "object", "properties": { "totalAnswers": { "type": "number", "description": "The number of answers recorded for this question.", "example": 120 }, "uniqueEmployees": { "type": "number", "description": "The number of different employees with an answer.", "example": 25 }, "questionnaireName": { "type": "string", "description": "The name of the questionnaire the question is in.", "example": "Customer service quality" }, "alertLevel": { "type": "string", "description": "The level of the linked alert type, when there is one.", "example": "high" } }, "required": [ "totalAnswers", "uniqueEmployees", "questionnaireName" ] }, "CreateEmployeeDto": { "type": "object", "properties": { "firstName": { "type": "string", "description": "The first name.", "example": "John", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "description": "The last name.", "example": "Doe", "minLength": 1, "maxLength": 100 }, "externalId": { "type": "string", "description": "The identifier of the employee in your own system.", "example": "EMP-001", "minLength": 1, "maxLength": 100 }, "skills": { "description": "The skills of the employee.", "example": [ "sales", "support" ], "type": "array", "items": { "type": "string" } }, "departmentId": { "type": "string", "description": "The `id` of the department to put the employee in.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "userId": { "type": "string", "description": "The `id` of the Drellia user to link to this employee.", "example": "550e8400-e29b-41d4-a716-446655440000" } }, "required": [ "firstName", "lastName" ] }, "EmployeeDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The employee `id`.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "entityKey": { "type": "string", "description": "The short key of the employee. `id` stays the identifier to use.", "example": "EMP-A1B2C3" }, "externalId": { "type": "string", "description": "The identifier of the employee in your own system.", "example": "EMP-001" }, "firstName": { "type": "string", "description": "The first name.", "example": "John" }, "lastName": { "type": "string", "description": "The last name.", "example": "Doe" }, "skills": { "description": "The skills of the employee.", "example": [ "sales", "support" ], "type": "array", "items": { "type": "string" } }, "createdOn": { "format": "date-time", "type": "string", "description": "When the employee was created." }, "updatedOn": { "format": "date-time", "type": "string", "description": "When the employee was last changed." }, "deletedOn": { "type": "object", "description": "When the employee was deleted. `null` when the employee is active.", "nullable": true }, "timezone": { "type": "object", "description": "The IANA time zone of the employee, when it is not the organization time zone.", "example": "Europe/London", "nullable": true }, "departmentId": { "type": "string", "description": "The `id` of the primary department.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "departments": { "description": "The `id` of each department the employee is in.", "type": "array", "items": { "type": "string" } }, "userId": { "type": "object", "description": "The `id` of the Drellia user linked to this employee. `null` when there is none.", "nullable": true } }, "required": [ "id", "firstName", "lastName", "createdOn", "updatedOn" ] }, "EmployeeResponseDto": { "type": "object", "properties": { "page": { "type": "number", "description": "The page you got.", "example": 1 }, "pageSize": { "type": "number", "description": "The number of items in each page.", "example": 50 }, "total": { "type": "number", "description": "The total number of employees.", "example": 42 }, "results": { "description": "The employees in this page.", "type": "array", "items": { "$ref": "#/components/schemas/EmployeeDto" } } }, "required": [ "page", "pageSize", "total", "results" ] }, "UpdateEmployeeDto": { "type": "object", "properties": { "firstName": { "type": "string", "description": "The first name.", "example": "John", "minLength": 1, "maxLength": 100 }, "lastName": { "type": "string", "description": "The last name.", "example": "Doe", "minLength": 1, "maxLength": 100 }, "skills": { "description": "The skills of the employee. The list you send replaces the old list.", "example": [ "sales", "support" ], "type": "array", "items": { "type": "string" } }, "departmentId": { "type": "string", "description": "The `id` of the primary department.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "timezone": { "type": "string", "description": "The IANA time zone of the employee.", "example": "Europe/London" }, "userId": { "type": "string", "description": "The `id` of the Drellia user to link to this employee. Send `null` to unlink.", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true } } }, "EmployeeStatsResponseDto": { "type": "object", "properties": { "totalConversations": { "type": "number", "description": "The number of conversations of the employee.", "example": 150 }, "totalAnswers": { "type": "number", "description": "The number of answers recorded for the employee.", "example": 500 }, "teamsCount": { "type": "number", "description": "The number of teams the employee is in.", "example": 3 }, "providersCount": { "type": "number", "description": "The number of providers the employee uses.", "example": 2 } }, "required": [ "totalConversations", "totalAnswers", "teamsCount", "providersCount" ] }, "CreateDepartmentDto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the department.", "example": "Billing" }, "description": { "type": "string", "description": "A short description of the department.", "example": "Invoices, refunds, and payment failures" }, "evaluateTransfer": { "type": "boolean", "description": "Whether Drellia evaluates transfers to this department. Default: `false`.", "example": true, "default": false }, "transferContext": { "type": "string", "description": "What this department handles, in free text. Drellia reads it to judge whether a transfer to this department was correct.", "example": "Billing handles invoices and refunds. Technical issues go to Support." }, "skills": { "description": "The skills and responsibilities of the department.", "example": [ "invoices", "refunds", "payment failures" ], "type": "array", "items": { "type": "string" } }, "color": { "type": "string", "description": "The color of the department in the web app: a hex color, for example `#FF5733`, or a color name, for example `indigo`. Drellia picks a color when you omit it.", "example": "indigo" }, "icon": { "type": "string", "description": "The name of the icon of the department in the web app.", "example": "users" } }, "required": [ "name", "icon" ] }, "DepartmentResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The department `id`.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "entityKey": { "type": "string", "description": "The short key of the department. Department paths accept it in place of `id`.", "example": "DEP-A1B2C3" }, "name": { "type": "string", "description": "The name of the department.", "example": "Billing" }, "description": { "type": "string", "description": "A short description of the department.", "example": "Invoices, refunds, and payment failures" }, "evaluateTransfer": { "type": "boolean", "description": "Whether Drellia evaluates transfers to this department.", "example": false }, "transferContext": { "type": "object", "description": "What this department handles, in free text. Drellia reads it to judge whether a transfer to this department was correct.", "example": "Billing handles invoices and refunds. Technical issues go to Support.", "nullable": true }, "skills": { "description": "The skills and responsibilities of the department.", "example": [ "invoices", "refunds", "payment failures" ], "type": "array", "items": { "type": "string" } }, "color": { "type": "string", "description": "The color of the department in the web app.", "example": "#FF5733" }, "icon": { "type": "string", "description": "The icon of the department in the web app.", "example": "users" }, "createdAt": { "format": "date-time", "type": "string", "description": "When the department was created. This resource uses `createdAt`; most others use `createdOn`.", "example": "2023-01-01T00:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the department was last changed. This resource uses `updatedAt`; most others use `updatedOn`.", "example": "2023-01-01T00:00:00Z" } }, "required": [ "id", "entityKey", "name", "description", "evaluateTransfer", "skills", "color", "icon", "createdAt", "updatedAt" ] }, "DepartmentsListResponseDto": { "type": "object", "properties": { "page": { "type": "number", "description": "The page you got.", "example": 1 }, "pageSize": { "type": "number", "description": "The number of items in each page.", "example": 50 }, "total": { "type": "number", "description": "The total number of departments.", "example": 12 }, "results": { "description": "The departments in this page.", "type": "array", "items": { "$ref": "#/components/schemas/DepartmentResponseDto" } } }, "required": [ "page", "pageSize", "total", "results" ] }, "UpdateDepartmentDto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the department.", "example": "Billing" }, "description": { "type": "string", "description": "A short description of the department.", "example": "Invoices, refunds, and payment failures" }, "evaluateTransfer": { "type": "boolean", "description": "Whether Drellia evaluates transfers to this department.", "example": true }, "transferContext": { "type": "string", "description": "What this department handles, in free text. Drellia reads it to judge whether a transfer to this department was correct.", "example": "Billing handles invoices and refunds. Technical issues go to Support." }, "skills": { "description": "The skills and responsibilities of the department.", "example": [ "invoices", "refunds", "payment failures" ], "type": "array", "items": { "type": "string" } }, "color": { "type": "string", "description": "The color of the department in the web app: a hex color, for example `#FF5733`, or a color name, for example `indigo`.", "example": "blue" }, "icon": { "type": "string", "description": "The name of the icon of the department in the web app.", "example": "users" } } }, "CreateQuestionnaireDto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the questionnaire.", "example": "Customer service quality", "minLength": 2, "maxLength": 255 }, "description": { "type": "string", "description": "What the questionnaire measures.", "example": "Greeting, identification, and closing of support calls" }, "isActive": { "type": "boolean", "description": "Whether the questionnaire is active. Default: `true`.", "default": true }, "metadata": { "type": "object", "description": "Extra data of your own. Drellia stores it and returns it as is.", "additionalProperties": true }, "status": { "type": "string", "description": "The status. `draft`: not in use. `active`: Drellia evaluates conversations with it. `archived`: no longer in use. The public API always creates the questionnaire as `draft`.", "enum": [ "draft", "active", "archived" ], "example": "draft" }, "departmentId": { "type": "string", "description": "The `id` of the department the questionnaire applies to.", "example": "550e8400-e29b-41d4-a716-446655440000" } }, "required": [ "name", "status" ] }, "QuestionnaireResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The questionnaire `id`.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "entityKey": { "type": "string", "description": "The short key of the questionnaire. `id` stays the identifier to use.", "example": "QST-A1B2C3" }, "name": { "type": "string", "description": "The name of the questionnaire.", "example": "Customer service quality" }, "description": { "type": "string", "description": "What the questionnaire measures.", "example": "Greeting, identification, and closing of support calls" }, "createdOn": { "format": "date-time", "type": "string", "description": "When the questionnaire was created." }, "updatedOn": { "format": "date-time", "type": "string", "description": "When the questionnaire was last changed." }, "questionCount": { "type": "number", "description": "The number of questions in the questionnaire.", "example": 8 }, "status": { "type": "string", "description": "The status. `draft`: not in use. `active`: Drellia evaluates conversations with it. `archived`: no longer in use.", "enum": [ "draft", "active", "archived" ], "example": "active" }, "departmentId": { "type": "string", "description": "The `id` of the department the questionnaire applies to.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "department": { "type": "object", "description": "The department the questionnaire applies to.", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "Billing" }, "description": { "type": "string", "example": "Invoices, refunds, and payment failures" }, "color": { "type": "string", "example": "#FF5733" }, "icon": { "type": "string", "example": "users" } } } }, "required": [ "id", "entityKey", "name", "createdOn", "updatedOn", "status" ] }, "QuestionnairesListResponseDto": { "type": "object", "properties": { "page": { "type": "number", "description": "The page you got.", "example": 1 }, "pageSize": { "type": "number", "description": "The number of items in each page.", "example": 50 }, "total": { "type": "number", "description": "The total number of questionnaires.", "example": 6 }, "count": { "type": "number", "description": "Deprecated. The same value as `total`.", "deprecated": true, "example": 6 }, "results": { "description": "The questionnaires in this page.", "type": "array", "items": { "$ref": "#/components/schemas/QuestionnaireResponseDto" } } }, "required": [ "page", "pageSize", "total", "results" ] }, "AlertTypeDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The alert type `id`.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "level": { "type": "string", "description": "How serious the alert is.", "enum": [ "low", "medium", "high" ], "example": "high" }, "category": { "type": "string", "description": "The category of the alert.", "example": "Compliance" }, "description": { "type": "string", "description": "When Drellia raises this alert for a conversation, in free text.", "example": "The employee shares the customer data with a third party.", "maxLength": 1000 }, "version": { "type": "number", "description": "The version of the criteria.", "example": 1 } }, "required": [ "id", "level", "category", "version" ] }, "QuestionnaireAlertDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The `id` of the link between the questionnaire and the alert type.", "example": "6f1c2d3e-4b5a-4c6d-8e7f-90a1b2c3d4e5" }, "questionnaireId": { "type": "string", "description": "The questionnaire `id`.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "alert": { "description": "The selected alert type.", "allOf": [ { "$ref": "#/components/schemas/AlertTypeDto" } ] } }, "required": [ "id", "questionnaireId", "alert" ] }, "SetQuestionnaireAlertsDto": { "type": "object", "properties": { "alertIds": { "description": "The `id` of each alert type to select. Maximum 10, with no duplicates. An empty list removes every alert.", "example": [ "550e8400-e29b-41d4-a716-446655440000" ], "maxItems": 10, "type": "array", "items": { "type": "string" } } }, "required": [ "alertIds" ] }, "UpdateQuestionnaireDto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the questionnaire.", "example": "Customer service quality", "minLength": 2, "maxLength": 255 }, "description": { "type": "string", "description": "What the questionnaire measures.", "example": "Greeting, identification, and closing of support calls", "maxLength": 1000 }, "isActive": { "type": "boolean", "description": "Whether the questionnaire is active." }, "metadata": { "type": "object", "description": "Extra data of your own. Drellia stores it and returns it as is.", "additionalProperties": true }, "status": { "type": "string", "description": "The status. `draft`: not in use. `active`: Drellia evaluates conversations with it. `archived`: no longer in use.", "enum": [ "draft", "active", "archived" ], "example": "active" }, "departmentId": { "type": "string", "description": "The `id` of the department the questionnaire applies to.", "example": "550e8400-e29b-41d4-a716-446655440000" } } }, "CreateCustomerDto": { "type": "object", "properties": { "identificationNumber": { "type": "string", "description": "The identification number of the customer, for example a national ID.", "example": "ID-12345", "minLength": 2, "maxLength": 255 }, "firstName": { "type": "string", "description": "The first name. A customer can have a phone number only, with no name.", "example": "John", "maxLength": 255 }, "lastName": { "type": "string", "description": "The last name.", "example": "Doe", "maxLength": 255 }, "externalId": { "type": "string", "description": "The identifier of the customer in your own system.", "example": "EXT-001", "maxLength": 255 }, "phoneNumber": { "type": "string", "description": "The phone number, with the country code.", "example": "+1234567890", "minLength": 2, "maxLength": 255 }, "email": { "type": "string", "description": "The email address. Drellia stores it in lower case.", "example": "john.doe@example.com" }, "metadata": { "type": "object", "description": "Extra facts about the customer, as text values. The voice agents can use them during a call. These keys are not allowed: `first_name`, `last_name`, `phone_number`, `email`, `external_id`, `id`. Use the customer fields for those.", "example": { "tier": "premium", "source": "web" }, "additionalProperties": { "type": "string" } } }, "required": [ "identificationNumber" ] }, "CustomersListResponseDto": { "type": "object", "properties": { "page": { "type": "number", "description": "The page you got.", "example": 1 }, "pageSize": { "type": "number", "description": "The number of items in each page.", "example": 50 }, "total": { "type": "number", "description": "The total number of customers.", "example": 100 }, "results": { "description": "The customers in this page.", "type": "array", "items": { "$ref": "#/components/schemas/CustomerResponseDto" } } }, "required": [ "page", "pageSize", "total", "results" ] }, "UpdateCustomerDto": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address. Send an empty string to clear it.", "example": "john.doe@example.com" }, "firstName": { "type": "string", "description": "The first name. Send an empty string to clear it.", "example": "John", "maxLength": 255 }, "identificationNumber": { "type": "string", "description": "The identification number of the customer.", "example": "ID-12345", "minLength": 2, "maxLength": 255 }, "phoneNumber": { "type": "string", "description": "The phone number, with the country code. Send an empty string to clear it.", "example": "+1234567890", "maxLength": 255 }, "lastName": { "type": "string", "description": "The last name. Send an empty string to clear it.", "example": "Doe", "maxLength": 255 }, "isActive": { "type": "boolean", "description": "Whether the customer is active.", "example": true }, "metadata": { "type": "object", "description": "Extra facts about the customer, as text values. The voice agents can use them during a call. These keys are not allowed: `first_name`, `last_name`, `phone_number`, `email`, `external_id`, `id`. Use the customer fields for those.", "example": { "tier": "premium", "source": "web" }, "additionalProperties": { "type": "string" } } } }, "CreateConversationDto": { "type": "object", "properties": { "providerId": { "type": "string", "description": "The `id` of the provider the conversation came through. See List providers.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "caseId": { "type": "string", "description": "The `id` of the case this conversation belongs to, when you track cases.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "employeeId": { "type": "string", "description": "The `id` of the employee in the conversation. Required when `agentId` is not sent. The public API requires it on every request.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "agentId": { "type": "string", "description": "The `id` of the voice agent in the conversation, for a call handled by an agent. Required when `employeeId` is not sent.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "customerId": { "type": "string", "description": "The `id` of the customer in the conversation.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "originalDateTime": { "type": "number", "description": "When the conversation happened, as a Unix time in milliseconds. The value must be between the years 2000 and 2100.", "example": 1701792000000, "minimum": 946684800000, "maximum": 4102444800000 } }, "required": [ "providerId", "customerId" ] }, "ConversationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The conversation `id`.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "entityKey": { "type": "string", "description": "The short key of the conversation. `id` stays the identifier to use.", "example": "CNV-A1B2C3" }, "organizationId": { "type": "string", "description": "The `id` of your organization.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "providerId": { "type": "string", "description": "The `id` of the provider the conversation came through.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "caseId": { "type": "string", "description": "The `id` of the case.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "employeeId": { "type": "string", "description": "The `id` of the employee in the conversation.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "customerId": { "type": "string", "description": "The `id` of the customer in the conversation.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "createdOn": { "format": "date-time", "type": "string", "description": "When the conversation was created in Drellia." }, "updatedOn": { "format": "date-time", "type": "string", "description": "When the conversation was last changed." }, "originalDateTime": { "type": "number", "description": "When the conversation happened, as a Unix time in milliseconds.", "example": 1701792000000 }, "status": { "type": "string", "description": "The processing status. `PENDING`: not evaluated yet. `COMPLETED`: evaluated. `PARTIAL_SUCCESS`: some evaluations failed. `FAILED`: the evaluation failed. `ARCHIVED`: closed.", "enum": [ "PENDING", "COMPLETED", "PARTIAL_SUCCESS", "FAILED", "ARCHIVED" ], "example": "PENDING" } }, "required": [ "id", "createdOn", "updatedOn", "status" ] }, "ConversationsListResponseDto": { "type": "object", "properties": { "page": { "type": "number", "description": "The page you got.", "example": 1 }, "pageSize": { "type": "number", "description": "The number of items in each page.", "example": 50 }, "total": { "type": "number", "description": "The total number of conversations.", "example": 120 }, "results": { "description": "The conversations in this page.", "type": "array", "items": { "$ref": "#/components/schemas/ConversationResponseDto" } } }, "required": [ "page", "pageSize", "total", "results" ] }, "UpdateConversationDto": { "type": "object", "properties": { "providerId": { "type": "string", "description": "The `id` of the provider the conversation came through.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "caseId": { "type": "string", "description": "The `id` of the case this conversation belongs to.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "employeeId": { "type": "string", "description": "The `id` of the employee in the conversation.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "customerId": { "type": "string", "description": "The `id` of the customer in the conversation.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "filePath": { "type": "string", "description": "The storage key of the audio recording. Drellia sets it when you use Get an upload URL. You do not normally send it.", "example": "org-123/uploads/audio/emp-456/conv-789.mp3" }, "originalDateTime": { "type": "number", "description": "When the conversation happened, as a Unix time in milliseconds. The value must be between the years 2000 and 2100.", "example": 1701792000000, "minimum": 946684800000, "maximum": 4102444800000 }, "status": { "type": "string", "description": "The processing status. Set `ARCHIVED` to close the conversation. Drellia sets the other values itself.", "enum": [ "PENDING", "COMPLETED", "PARTIAL_SUCCESS", "FAILED", "ARCHIVED" ], "example": "ARCHIVED" } } }, "FileUploadUrlResponseDto": { "type": "object", "properties": { "uploadUrl": { "type": "string", "description": "The pre-signed URL. Send the file to it with an HTTP PUT.", "example": "https://uploads.example.com/..." }, "s3Key": { "type": "string", "description": "The storage key of the file.", "example": "org-123/uploads/audio/emp-456/conv-789.mp3" }, "fileUrl": { "type": "string", "description": "The URL of the file after the upload.", "example": "https://files.example.com/..." } }, "required": [ "uploadUrl", "s3Key", "fileUrl" ] }, "CreateConversationMessageRequest": { "type": "object", "properties": { "content": { "type": "string", "description": "The text of the message.", "example": "Hello, how are you today?" }, "senderRole": { "type": "string", "description": "Who sent the message: `customer` or `employee`.", "example": "customer" }, "senderId": { "type": "string", "description": "The Drellia `id` of the sender: the customer `id` or the employee `id`.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "originalDateTime": { "type": "number", "description": "When the message was sent, as a Unix time in milliseconds.", "example": 1701792000000 } }, "required": [ "content", "senderRole", "originalDateTime" ] }, "CreateConversationEventRequest": { "type": "object", "properties": { "eventType": { "type": "string", "description": "What happened. `transfer.requested`: someone asked for a transfer. `transfer.completed`: the transfer was made. `transfer.failed`: the transfer did not go through. `transfer.cancelled`: the transfer was cancelled.", "enum": [ "transfer.requested", "transfer.completed", "transfer.failed", "transfer.cancelled" ], "example": "transfer.completed" }, "originalDateTime": { "type": "number", "description": "When the event happened, as a Unix time in milliseconds.", "example": 1760000005000 }, "triggeredByRole": { "type": "string", "description": "The role of the person who caused the event, for example `employee`.", "example": "employee" }, "triggeredById": { "type": "string", "description": "The Drellia `id` of the person who caused the event, when you know it.", "example": "11111111-1111-1111-1111-111111111111" }, "payload": { "type": "object", "description": "Data specific to the event type. A `transfer.completed`, `transfer.failed`, or `transfer.cancelled` event needs `toDepartmentId` (a department `id`). `fromDepartmentId` is optional.", "additionalProperties": true, "example": { "toDepartmentId": "22222222-2222-2222-2222-222222222222", "fromDepartmentId": "33333333-3333-3333-3333-333333333333" } } }, "required": [ "eventType", "originalDateTime", "payload" ] }, "CreateConversationTimelineRequestDto": { "type": "object", "properties": { "messages": { "description": "The messages of the conversation, in any order.", "type": "array", "items": { "$ref": "#/components/schemas/CreateConversationMessageRequest" } }, "events": { "description": "The events of the conversation, for example transfers.", "type": "array", "items": { "$ref": "#/components/schemas/CreateConversationEventRequest" } } }, "required": [ "messages" ] }, "ConversationTimelineOperationResultDto": { "type": "object", "properties": { "created": { "type": "number", "description": "How many items were saved.", "example": 1 }, "failed": { "type": "number", "description": "How many items were not saved.", "example": 0 }, "errors": { "description": "One line for each item that was not saved, with the reason.", "example": [], "type": "array", "items": { "type": "string" } } }, "required": [ "created", "failed", "errors" ] }, "CreateConversationTimelineResponseDto": { "type": "object", "properties": { "messages": { "description": "The result for the messages.", "allOf": [ { "$ref": "#/components/schemas/ConversationTimelineOperationResultDto" } ] }, "events": { "description": "The result for the events.", "allOf": [ { "$ref": "#/components/schemas/ConversationTimelineOperationResultDto" } ] } }, "required": [ "messages", "events" ] }, "ConversationTimelineMessageDto": { "type": "object", "properties": { "messageId": { "type": "string", "description": "The message `id`.", "example": "msg-001" }, "conversationId": { "type": "string", "description": "The `id` of the conversation the message belongs to.", "example": "11111111-1111-1111-1111-111111111111" }, "content": { "type": "string", "description": "The text of the message.", "example": "Hello" }, "senderRole": { "type": "string", "description": "Who sent the message: `customer` or `employee`.", "example": "customer" }, "senderId": { "type": "string", "description": "The `id` of the sender, when you sent it.", "example": "22222222-2222-2222-2222-222222222222" }, "timestamp": { "type": "number", "description": "Deprecated. The same value as `originalDateTime`.", "deprecated": true, "example": 1760000000000 }, "originalDateTime": { "type": "number", "description": "When the message was sent, as a Unix time in milliseconds.", "example": 1760000000000 }, "organizationId": { "type": "string", "description": "The `id` of your organization.", "example": "33333333-3333-3333-3333-333333333333" }, "createdAt": { "type": "number", "description": "When Drellia stored the message, as a Unix time in milliseconds.", "example": 1760000001000 } }, "required": [ "messageId", "conversationId", "content", "senderRole", "timestamp", "originalDateTime" ] }, "ConversationEventDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The event `id`.", "example": "evt-001" }, "conversationId": { "type": "string", "description": "The `id` of the conversation the event belongs to.", "example": "11111111-1111-1111-1111-111111111111" }, "eventType": { "type": "string", "description": "What happened.", "enum": [ "transfer.requested", "transfer.completed", "transfer.failed", "transfer.cancelled" ], "example": "transfer.completed" }, "eventVersion": { "type": "number", "description": "The version of the event schema.", "example": 1 }, "originalDateTime": { "type": "number", "description": "When the event happened, as a Unix time in milliseconds.", "example": 1760000005000 }, "triggeredByRole": { "type": "string", "description": "The role of the person who caused the event.", "example": "employee" }, "triggeredById": { "type": "string", "description": "The Drellia `id` of the person who caused the event.", "example": "11111111-1111-1111-1111-111111111111" }, "payload": { "type": "object", "description": "Data specific to the event type.", "additionalProperties": true }, "transferCorrelationId": { "type": "string", "description": "An `id` Drellia gives to all the events of one transfer.", "example": "44444444-4444-4444-8444-444444444444" } }, "required": [ "id", "conversationId", "eventType", "eventVersion", "originalDateTime", "payload" ] }, "ConversationTimelineResultsDto": { "type": "object", "properties": { "messages": { "description": "The messages, in order of `originalDateTime`.", "type": "array", "items": { "$ref": "#/components/schemas/ConversationTimelineMessageDto" } }, "events": { "description": "The events, in order of `originalDateTime`.", "type": "array", "items": { "$ref": "#/components/schemas/ConversationEventDto" } } }, "required": [ "messages", "events" ] }, "ConversationTimelineResponseDto": { "type": "object", "properties": { "results": { "description": "The messages and the events.", "allOf": [ { "$ref": "#/components/schemas/ConversationTimelineResultsDto" } ] } }, "required": [ "results" ] }, "StoreInteractionContextDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The `id` of the interaction, a UUID v4 you choose. Use the same value in the path.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "externalId": { "type": "string", "description": "The identifier of the interaction in your own system. Unique in your organization. Printable ASCII only, with no spaces. Use it to find the context again with Find by external ID.", "example": "crm-case-48213", "maxLength": 256 }, "data": { "type": "object", "additionalProperties": true, "description": "The data of the interaction, as key and value pairs. The keys must be the context fields configured for your organization.", "example": { "customerName": "Maria Lopez", "amountDue": "1248.60", "dueDate": "2026-10-01" } } }, "required": [ "id", "data" ] }, "InteractionContextResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The `id` of the interaction.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "organizationId": { "type": "string", "description": "The `id` of your organization.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "externalId": { "type": "string", "description": "The identifier of the interaction in your own system.", "example": "crm-case-48213" }, "data": { "type": "object", "additionalProperties": true, "description": "The data of the interaction, as you stored it.", "example": { "customerName": "Maria Lopez", "amountDue": "1248.60", "dueDate": "2026-10-01" } }, "createdOn": { "type": "string", "description": "When the context was first stored.", "example": "2026-09-22T10:15:30.000Z" }, "updatedOn": { "type": "string", "description": "When the context was last replaced.", "example": "2026-09-22T10:15:30.000Z" } }, "required": [ "id", "organizationId", "data", "createdOn", "updatedOn" ] }, "ProviderResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The provider `id`.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "The name of the provider.", "example": "Twilio" }, "channel": { "type": "string", "description": "The channel the provider serves, for example `voice` or `chat`.", "example": "voice" }, "createdAt": { "format": "date-time", "type": "string", "description": "When the provider was created. This resource uses `createdAt`; most others use `createdOn`." }, "updatedAt": { "format": "date-time", "type": "string", "description": "When the provider was last changed. This resource uses `updatedAt`; most others use `updatedOn`." } }, "required": [ "id", "name", "channel", "createdAt", "updatedAt" ] }, "ProvidersListResponseDto": { "type": "object", "properties": { "results": { "description": "The providers of your organization.", "type": "array", "items": { "$ref": "#/components/schemas/ProviderResponseDto" } } }, "required": [ "results" ] }, "SendEmailRequestDto": { "type": "object", "properties": { "subject": { "type": "string", "description": "The subject line, one line of plain text. It is also the headline of the email.", "example": "Customer wants to pay", "maxLength": 200 }, "body": { "type": "string", "description": "What happened and what your team must do, as plain text. No HTML and no Markdown.", "example": "Maria Lopez agreed to pay today; please follow up.", "maxLength": 10000 }, "customerName": { "type": "string", "description": "The name of the customer, when known.", "example": "Maria Lopez", "maxLength": 200 }, "customerId": { "type": "string", "description": "The customer or account identifier in your system, when known.", "example": "AC-40182", "maxLength": 64 }, "paymentAmount": { "type": "string", "description": "The amount the customer said they will pay, with the currency symbol. When you send it, the email shows a payment panel.", "example": "\u20ac1,248.60", "maxLength": 40 }, "paymentDueDate": { "type": "string", "description": "When the customer said they will pay, as free text.", "example": "March 21, 2025", "maxLength": 100 }, "paymentMethod": { "type": "string", "description": "How the customer said they will pay, as free text.", "example": "Bank transfer, single payment", "maxLength": 200 }, "customerQuote": { "type": "string", "description": "A short quote of what the customer said, when it helps your team.", "example": "I can send the transfer on the 21st once I'm paid.", "maxLength": 500 }, "locale": { "type": "string", "description": "The language of the email. Default: the language of your organization (`es`).", "example": "es", "enum": [ "en", "es" ] } }, "required": [ "subject", "body" ] }, "SendEmailResponseDto": { "type": "object", "properties": { "messageId": { "type": "string", "description": "The message `id` from the email provider. Can be empty.", "example": "<20260811100000.abcdef@mail.drellia.com>" }, "recipientCount": { "type": "number", "description": "The number of recipients the email went to.", "example": 2 } }, "required": [ "messageId", "recipientCount" ] }, "VerifyIdentityRequestDto": { "type": "object", "properties": { "fieldType": { "type": "string", "description": "The kind of value to verify. Each kind has its own comparison rules. Only `customer_identification_number` is available now.", "enum": [ "customer_identification_number" ], "example": "customer_identification_number" }, "providedValue": { "type": "string", "description": "The value as the caller said it, exactly as it is in the transcript. Spaces, separators, letters, and spelled words such as \"Q de Queso\" are all accepted.", "example": "12 34 56 78 Q de Queso", "maxLength": 200 }, "expectedValue": { "type": "string", "description": "The value on file, for example the identification number of the customer. Configure it as a dynamic variable in your agent platform. Do not let the model fill it. The response never contains it.", "example": "12345678Q", "maxLength": 200 } }, "required": [ "fieldType", "providedValue", "expectedValue" ] }, "VerifyIdentityResponseDto": { "type": "object", "properties": { "match": { "type": "boolean", "description": "Whether the two values match under the rules of `fieldType`. For `customer_identification_number`, only the digits are compared. Letters and separators are ignored on both sides.", "example": true }, "reason": { "type": "string", "description": "Why the values do not match. Only present when `match` is false. `invalid_format`: the provided value has nothing to compare. `mismatch`: the values are different.", "enum": [ "invalid_format", "mismatch" ], "example": "mismatch" } }, "required": [ "match" ] }, "WorkingHoursResponseDto": { "type": "object", "properties": { "employeeId": { "type": "string", "nullable": true, "description": "The employee `id` when this is an employee override. `null` for the organization schedule." }, "days": { "description": "The 7 days of the week, one entry each.", "type": "array", "items": { "$ref": "#/components/schemas/WorkingHoursDayDto" } }, "resolvedFrom": { "type": "string", "enum": [ "organization", "employee" ], "description": "Only on Get the effective working hours: which schedule you got. `employee`: the employee override. `organization`: the organization schedule.", "example": "organization" } }, "required": [ "days" ] }, "SetWorkingHoursDto": { "type": "object", "properties": { "days": { "description": "The full week: exactly 7 entries, one for each `dayOfWeek` from 0 (Sunday) to 6 (Saturday), with no duplicates. Send `isEnabled: false` for a day off.", "minItems": 7, "maxItems": 7, "type": "array", "items": { "$ref": "#/components/schemas/WorkingHoursDayDto" } } }, "required": [ "days" ] } } }, "x-tagGroups": [ { "name": "Audit", "tags": [ "Conversations", "Questionnaires", "Questions" ] }, { "name": "Voice Agents", "tags": [ "Agents", "Campaigns", "Agent Tools", "Interaction Context" ] }, { "name": "Organization data", "tags": [ "Customers", "Employees", "Departments", "Working Hours", "Providers" ] }, { "name": "Platform", "tags": [ "Health" ] } ] }