{ "openapi": "3.0.1", "info": { "title": "LiveSwitch Public API", "version": "v1" }, "servers": [ { "url": "https://public-api.production.liveswitch.com/", "description": "Contact / Concierge Public API" } ], "paths": { "/v1/accounts": { "get": { "tags": [ "Accounts" ], "summary": "Retrieves a list of accounts", "description": "**Required scope:** `accounts`", "parameters": [ { "name": "page", "in": "query", "description": "The page number to retrieve, from 1 to int.MaxValue, default 1", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of records to return per page, from 1 to 100, default 10", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "where", "in": "query", "description": "Custom querying. Extended documentation forthcoming. Contact support@liveswitch.com with questions.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Custom ordering. By default records are always returned by date, most recent first.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountGetDto" } } } } } }, "security": [ { "oauth2": [ "accounts" ] } ] } }, "/v1/accounts/{userId}": { "get": { "tags": [ "Accounts" ], "summary": "Gets an account by user ID", "description": "**Required scope:** `accounts`", "parameters": [ { "name": "userId", "in": "path", "description": "The user ID of the account", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountGetDto" } } } } }, "security": [ { "oauth2": [ "accounts" ] } ] } }, "/v1/attribute-groups": { "get": { "tags": [ "AttributeGroups" ], "summary": "Gets a list of attribute groups", "description": "**Required scope:** `attributes`", "parameters": [ { "name": "page", "in": "query", "description": "The page number to retrieve, from 1 to int.MaxValue, default 1", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of records to return per page, from 1 to 100, default 10", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "where", "in": "query", "description": "Custom querying. Extended documentation forthcoming. Contact support@liveswitch.com with questions.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Custom ordering. By default records are always returned by date, most recent first.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeGroupDto" } } } } } }, "security": [ { "oauth2": [ "attributes" ] } ] }, "post": { "tags": [ "AttributeGroups" ], "summary": "Creates an attribute group", "description": "**Required scope:** `attributes.write`", "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeGroupRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeGroupDto" } } } } }, "security": [ { "oauth2": [ "attributes.write" ] } ] } }, "/v1/attribute-groups/app/{appId}": { "get": { "tags": [ "AttributeGroups" ], "description": "**Required scope:** `attributes`", "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeGroupDto" } } } } } }, "deprecated": true, "security": [ { "oauth2": [ "attributes" ] } ] } }, "/v1/attribute-groups/{id}": { "get": { "tags": [ "AttributeGroups" ], "summary": "Gets an attribute group by id", "description": "**Required scope:** `attributes`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeGroupDto" } } } } }, "security": [ { "oauth2": [ "attributes" ] } ] }, "put": { "tags": [ "AttributeGroups" ], "summary": "Updates an attribute group", "description": "**Required scope:** `attributes.write`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeGroupRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeGroupDto" } } } } }, "security": [ { "oauth2": [ "attributes.write" ] } ] }, "delete": { "tags": [ "AttributeGroups" ], "summary": "Deletes an attribute group", "description": "**Required scope:** `attributes.write`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResult" } } } } }, "security": [ { "oauth2": [ "attributes.write" ] } ] } }, "/v1/attribute-groups/by-name/{name}": { "get": { "tags": [ "AttributeGroups" ], "summary": "Gets an attribute group by name", "description": "**Required scope:** `attributes`", "parameters": [ { "name": "name", "in": "path", "description": "The code name of the attribute group (e.g., \"hcp_app\")", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeGroupDto" } } } } }, "security": [ { "oauth2": [ "attributes" ] } ] } }, "/v1/attributes": { "get": { "tags": [ "Attributes" ], "summary": "Gets a list of attributes", "description": "**Required scope:** `attributes`", "parameters": [ { "name": "page", "in": "query", "description": "The page number to retrieve, from 1 to int.MaxValue, default 1", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of records to return per page, from 1 to 100, default 10", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "where", "in": "query", "description": "Custom querying. Extended documentation forthcoming. Contact support@liveswitch.com with questions.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Custom ordering. By default records are always returned by date, most recent first.", "schema": { "type": "string" } }, { "name": "attributeGroupName", "in": "query", "description": "Optional attribute group name to filter by", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeDto" } } } } } }, "security": [ { "oauth2": [ "attributes" ] } ] }, "post": { "tags": [ "Attributes" ], "summary": "Creates an attribute", "description": "**Required scope:** `attributes.write`", "requestBody": { "description": "The attribute to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeDto" } } } } }, "security": [ { "oauth2": [ "attributes.write" ] } ] } }, "/v1/attributes/app/{appId}": { "get": { "tags": [ "Attributes" ], "summary": "Gets all the attributes for a specific app", "description": "**Required scope:** `attributes`", "parameters": [ { "name": "appId", "in": "path", "description": "The App ID to filter by", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeDto" } } } } } }, "deprecated": true, "security": [ { "oauth2": [ "attributes" ] } ] } }, "/v1/attributes/{id}": { "get": { "tags": [ "Attributes" ], "summary": "Gets a single attribute by id", "description": "**Required scope:** `attributes`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeDto" } } } } }, "security": [ { "oauth2": [ "attributes" ] } ] }, "put": { "tags": [ "Attributes" ], "summary": "Updates an attribute", "description": "**Required scope:** `attributes.write`", "parameters": [ { "name": "id", "in": "path", "description": "The id of the attribute to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "The attribute data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeUpdateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeDto" } } } } }, "security": [ { "oauth2": [ "attributes.write" ] } ] }, "delete": { "tags": [ "Attributes" ], "summary": "Deletes an attribute by id", "description": "**Required scope:** `attributes.write`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResult" } } } } }, "security": [ { "oauth2": [ "attributes.write" ] } ] } }, "/v1/contacts": { "get": { "tags": [ "Contacts" ], "summary": "Gets a list of contacts", "description": "**Required scope:** `contacts`", "parameters": [ { "name": "page", "in": "query", "description": "The page number to retrieve, from 1 to int.MaxValue, default 1", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of records to return per page, from 1 to 100, default 10", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "where", "in": "query", "description": "Custom querying. Extended documentation forthcoming. Contact support@liveswitch.com with questions.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Custom ordering. By default records are always returned by date, most recent first.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContactListDto" } } } } } }, "security": [ { "oauth2": [ "contacts" ] } ] }, "post": { "tags": [ "Contacts" ], "summary": "Creates a new contact", "description": "**Required scope:** `contacts.write`", "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDto" } } } } }, "security": [ { "oauth2": [ "contacts.write" ] } ] } }, "/v1/contacts/{id}": { "get": { "tags": [ "Contacts" ], "summary": "Gets a contact by id.", "description": "**Required scope:** `contacts`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDto" } } } } }, "security": [ { "oauth2": [ "contacts" ] } ] }, "delete": { "tags": [ "Contacts" ], "summary": "Deletes a contact.", "description": "**Required scope:** `contacts`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDto" } } } } }, "security": [ { "oauth2": [ "contacts" ] } ] }, "put": { "tags": [ "Contacts" ], "summary": "Updates a contact, given its ID. Supports partial updates.", "description": "**Required scope:** `contacts.write`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDto" } } } } }, "security": [ { "oauth2": [ "contacts.write" ] } ] } }, "/v1/contacts/by-phone/{phone}": { "get": { "tags": [ "Contacts" ], "summary": "Gets a contact by phone. Make sure you use the same format you used to create the initial contact. While\r\nwe make every effort to avoid duplication and consistent lookups, if poor data is stored in the first place,\r\nthis lookup will be poor as well.", "description": "**Required scope:** `contacts`", "parameters": [ { "name": "phone", "in": "path", "description": "", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDto" } } } } }, "security": [ { "oauth2": [ "contacts" ] } ] } }, "/v1/conversations": { "post": { "tags": [ "Conversations" ], "summary": "Creates a conversation.", "description": "**Required scope:** `conversations.write`", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationCreateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationDto" } } } } }, "security": [ { "oauth2": [ "conversations.write" ] } ] }, "get": { "tags": [ "Conversations" ], "summary": "Retrieves a list of conversations.", "description": "**Required scope:** `conversations`", "parameters": [ { "name": "page", "in": "query", "description": "The page number to retrieve, from 1 to int.MaxValue, default 1", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of records to return per page, from 1 to 100, default 10", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "where", "in": "query", "description": "Custom querying. Extended documentation forthcoming. Contact support@liveswitch.com with questions.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Custom ordering. By default records are always returned by date, most recent first.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationListDto" } } } } } }, "security": [ { "oauth2": [ "conversations" ] } ] } }, "/v1/conversations/{id}": { "get": { "tags": [ "Conversations" ], "summary": "Gets a conversation by ID.", "description": "**Required scope:** `conversations`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationDto" } } } } }, "security": [ { "oauth2": [ "conversations" ] } ] }, "put": { "tags": [ "Conversations" ], "summary": "Updates a conversation.", "description": "**Required scope:** `conversations.write`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationUpdateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationDto" } } } } }, "security": [ { "oauth2": [ "conversations.write" ] } ] } }, "/v1/conversations/{id}/upload-urls/images": { "post": { "tags": [ "Conversations" ], "summary": "Creates presigned URLs for uploading images to a conversation.\r\nSupports png, jpg, jpeg, webp. Maximum 20 files per request.", "description": "**Required scope:** `conversations.write`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileMetadataDto" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseDto" } } } } }, "security": [ { "oauth2": [ "conversations.write" ] } ] } }, "/v1/conversations/{id}/upload-urls/documents": { "post": { "tags": [ "Conversations" ], "summary": "Creates presigned URLs for uploading documents to a conversation.\r\nSupports pdf. Maximum 20 files per request.", "description": "**Required scope:** `conversations.write`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileMetadataDto" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseDto" } } } } }, "security": [ { "oauth2": [ "conversations.write" ] } ] } }, "/v1/conversations/{id}/upload-urls/videos": { "post": { "tags": [ "Conversations" ], "summary": "Creates presigned URLs for uploading videos to a conversation.\r\nSupports mp4, mov. Maximum 20 files per request.", "description": "**Required scope:** `conversations.write`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FileMetadataDto" } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseDto" } } } } }, "security": [ { "oauth2": [ "conversations.write" ] } ] } }, "/v1/conversations/{conversationId}/sparks": { "post": { "tags": [ "Conversations" ], "summary": "Creates a Spark on a conversation. If media is not yet available, the Spark queues\r\nand starts automatically when media arrives. Status is always `\"queued\"`.", "description": "**Required scope:** `sparks.write`", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSparkRequestDto" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSparkResponseDto" } } } } }, "security": [ { "oauth2": [ "sparks.write" ] } ] }, "get": { "tags": [ "Conversations" ], "summary": "Lists all Spark runs for a conversation, sorted by creation date descending.", "description": "**Required scope:** `sparks`", "parameters": [ { "name": "conversationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SparkListResponseDto" } } } } }, "security": [ { "oauth2": [ "sparks" ] } ] } }, "/v1/documents/{id}": { "get": { "tags": [ "Documents" ], "summary": "Gets a document by id.", "description": "**Required scope:** `profile`", "parameters": [ { "name": "id", "in": "path", "description": "The id of the document you want to get.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } } }, "security": [ { "oauth2": [ "profile" ] } ] } }, "/v1/documents/project/{projectId}": { "get": { "tags": [ "Documents" ], "summary": "Gets documents by project id.", "description": "**Required scope:** `profile`", "parameters": [ { "name": "projectId", "in": "path", "description": "The id of the project you want to get a list of documents for.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } } }, "security": [ { "oauth2": [ "profile" ] } ] } }, "/v1/documents/project/snapshots/{projectId}": { "get": { "tags": [ "Documents" ], "summary": "Gets snapshots by project id.", "description": "**Required scope:** `profile`", "parameters": [ { "name": "projectId", "in": "path", "description": "The id of the project you want to get a list of documents for.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } } }, "security": [ { "oauth2": [ "profile" ] } ] } }, "/v1/documents/project/files/{projectId}": { "get": { "tags": [ "Documents" ], "summary": "Gets files by project id.", "description": "**Required scope:** `profile`", "parameters": [ { "name": "projectId", "in": "path", "description": "The id of the project you want to get a list of documents for.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } } }, "security": [ { "oauth2": [ "profile" ] } ] } }, "/v1/documents/conversation/{conversationId}": { "get": { "tags": [ "Documents" ], "summary": "Gets documents by conversation id.", "description": "**Required scope:** `profile`", "parameters": [ { "name": "conversationId", "in": "path", "description": "The id of the project you want to get a list of documents for.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } } }, "security": [ { "oauth2": [ "profile" ] } ] } }, "/v1/documents/conversation/snapshots/{conversationId}": { "get": { "tags": [ "Documents" ], "summary": "Gets snapshots by conversation id.", "description": "**Required scope:** `profile`", "parameters": [ { "name": "conversationId", "in": "path", "description": "The id of the conversation you want to get a list of documents for.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } } }, "security": [ { "oauth2": [ "profile" ] } ] } }, "/v1/documents/conversation/files/{conversationId}": { "get": { "tags": [ "Documents" ], "summary": "Gets files by conversation id.", "description": "**Required scope:** `profile`", "parameters": [ { "name": "conversationId", "in": "path", "description": "The id of the conversation you want to get a list of documents for.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } } }, "security": [ { "oauth2": [ "profile" ] } ] } }, "/v1/entity-attributes/{entityType}": { "get": { "tags": [ "EntityAttributes" ], "summary": "Gets all the EntityAttributes for a given EntityType.", "description": "You likely want the by-entity, which allows you to\r\nget all the EntityAttributes for a specific EntityType AND Entity - so you can get, for example, all the\r\nEntityAttributes on Conversation 1.\n\n**Required scope:** `attributes`", "parameters": [ { "name": "entityType", "in": "path", "description": "", "required": true, "schema": { "$ref": "#/components/schemas/EntityType" } }, { "name": "page", "in": "query", "description": "The page number to retrieve, from 1 to int.MaxValue, default 1", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of records to return per page, from 1 to 100, default 10", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "where", "in": "query", "description": "Custom querying. Extended documentation forthcoming. Contact support@liveswitch.com with questions.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Custom ordering. By default records are always returned by date, most recent first.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityAttributeDto" } } } } } }, "security": [ { "oauth2": [ "attributes" ] } ] }, "post": { "tags": [ "EntityAttributes" ], "summary": "Create an EntityAttribute for a given Entity.", "description": "You can identify the attribute using either:\r\n- attributeId (the GUID of the attribute), OR\r\n- both attributeGroupName and attributeName together\n\n**Required scope:** `attributes.write`", "parameters": [ { "name": "entityType", "in": "path", "description": "", "required": true, "schema": { "$ref": "#/components/schemas/EntityType" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityAttributeRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityAttributeDto" } } } } }, "security": [ { "oauth2": [ "attributes.write" ] } ] } }, "/v1/entity-attributes/{entityType}/by-entity/{entityId}": { "get": { "tags": [ "EntityAttributes" ], "summary": "Allows you to get all the EntityAttributes for a specific EntityType AND Entity Instance.", "description": "Allows you to easily get, for example, all the EntityAttributes on Conversation A.\r\nYou can optionally filter by attributeGroupName and/or attributeName.\n\n**Required scope:** `attributes`", "parameters": [ { "name": "entityType", "in": "path", "description": "", "required": true, "schema": { "$ref": "#/components/schemas/EntityType" } }, { "name": "entityId", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "attributeGroupName", "in": "query", "description": "Optional filter by attribute group name", "schema": { "type": "string" } }, { "name": "attributeName", "in": "query", "description": "Optional filter by attribute name", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "The page number to retrieve, from 1 to int.MaxValue, default 1", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of records to return per page, from 1 to 100, default 10", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "where", "in": "query", "description": "Custom querying. Extended documentation forthcoming. Contact support@liveswitch.com with questions.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Custom ordering. By default records are always returned by date, most recent first.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityAttributeDto" } } } } } }, "security": [ { "oauth2": [ "attributes" ] } ] } }, "/v1/entity-attributes/{entityType}/{id}": { "get": { "tags": [ "EntityAttributes" ], "summary": "Reads a specific EntityAttribute for a given Entity Type by ID", "description": "**Required scope:** `attributes`", "parameters": [ { "name": "entityType", "in": "path", "description": "", "required": true, "schema": { "$ref": "#/components/schemas/EntityType" } }, { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityAttributeDto" } } } } }, "security": [ { "oauth2": [ "attributes" ] } ] }, "put": { "tags": [ "EntityAttributes" ], "summary": "Updates a given EntityAttribute", "description": "**Required scope:** `attributes.write`", "parameters": [ { "name": "entityType", "in": "path", "description": "", "required": true, "schema": { "$ref": "#/components/schemas/EntityType" } }, { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityAttributeUpdateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityAttributeDto" } } } } }, "security": [ { "oauth2": [ "attributes.write" ] } ] }, "delete": { "tags": [ "EntityAttributes" ], "summary": "Deletes an EntityAttribute", "description": "**Required scope:** `attributes.write`", "parameters": [ { "name": "entityType", "in": "path", "description": "", "required": true, "schema": { "$ref": "#/components/schemas/EntityType" } }, { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResult" } } } } }, "security": [ { "oauth2": [ "attributes.write" ] } ] } }, "/v1/forms/{id}": { "get": { "tags": [ "Forms" ], "summary": "Gets a form by id.", "description": "**Required scope:** `forms`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormDto" } } } } }, "security": [ { "oauth2": [ "forms" ] } ] } }, "/v1/forms/submissions/{id}": { "get": { "tags": [ "Forms" ], "summary": "Gets a form submission by id.", "description": "**Required scope:** `forms`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormSubmissionResponseDto" } } } } }, "security": [ { "oauth2": [ "forms" ] } ] } }, "/v1/guided-instructions": { "get": { "tags": [ "GuidedInstructions" ], "description": "**Required scope:** `guided-instructions`", "parameters": [ { "name": "page", "in": "query", "description": "The page number to retrieve, from 1 to int.MaxValue, default 1", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of records to return per page, from 1 to 100, default 10", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "where", "in": "query", "description": "Custom querying. Extended documentation forthcoming. Contact support@liveswitch.com with questions.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Custom ordering. By default records are always returned by date, most recent first.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Represents the type of Conversation", "schema": { "$ref": "#/components/schemas/ConversationType" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GuidedInstructionDto" } } } } } }, "security": [ { "oauth2": [ "guided-instructions" ] } ] } }, "/v1/me": { "get": { "tags": [ "Me" ], "summary": "Gets the current user based on the access token.", "description": "**Required scope:** `me`", "responses": { "200": { "description": "Returns the current user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeDto" } } } }, "403": { "description": "Occurs if the \"me\" scope is not included in the access token." }, "401": { "description": "Occurs if the user token is expired or invalid." } }, "security": [ { "oauth2": [ "me" ] } ] } }, "/v1/organizations/settings": { "get": { "tags": [ "Organizations" ], "summary": "Gets your currently logged in organization settings.", "description": "**Required scope:** `organizations`", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSettingsDto" } } } } }, "security": [ { "oauth2": [ "organizations" ] } ] } }, "/v1/organizations/sms-enabled": { "patch": { "tags": [ "Organizations" ], "summary": "Updates the SMS enabled setting for your currently logged in organization.", "description": "**Required scope:** `organizations.write`", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationSmsSettingsDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSettingsDto" } } } } }, "security": [ { "oauth2": [ "organizations.write" ] } ] } }, "/v1/projects": { "post": { "tags": [ "Projects" ], "summary": "Creates a project", "description": "**Required scope:** `projects.write`", "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } } }, "security": [ { "oauth2": [ "projects.write" ] } ] }, "get": { "tags": [ "Projects" ], "summary": "Retrieves a list of projects", "description": "**Required scope:** `projects`", "parameters": [ { "name": "page", "in": "query", "description": "The page number to retrieve, from 1 to int.MaxValue, default 1", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of records to return per page, from 1 to 100, default 10", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "where", "in": "query", "description": "Custom querying. Extended documentation forthcoming. Contact support@liveswitch.com with questions.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Custom ordering. By default records are always returned by date, most recent first.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Optional filter by project status (NotStarted, InProgress, Completed)", "schema": { "$ref": "#/components/schemas/ProjectStatus" } }, { "name": "externalId", "in": "query", "description": "Optional filter by external ID. Returns single project if found.", "schema": { "type": "string" } }, { "name": "contactId", "in": "query", "description": "Optional filter by contact ID. Must be a valid GUID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectListDto" } } } } } }, "security": [ { "oauth2": [ "projects" ] } ] } }, "/v1/projects/{id}": { "get": { "tags": [ "Projects" ], "summary": "Gets a project by id", "description": "**Required scope:** `projects`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } } }, "security": [ { "oauth2": [ "projects" ] } ] }, "put": { "tags": [ "Projects" ], "summary": "Updates a project. Supports partial updates.", "description": "**Required scope:** `projects.write`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectUpdateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } } }, "security": [ { "oauth2": [ "projects.write" ] } ] } }, "/v1/projects/{id}/upload-urls/images": { "post": { "tags": [ "Projects" ], "summary": "Creates presigned URLs for uploading images to a project. Creates a new conversation for the upload session. Supports png, jpg, jpeg, webp. Maximum 20 files per request.", "description": "**Required scope:** `projects.write`", "parameters": [ { "name": "id", "in": "path", "description": "The id of the project to upload images to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Request containing file metadata and optional conversation settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectFileUploadRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseDto" } } } } }, "security": [ { "oauth2": [ "projects.write" ] } ] } }, "/v1/projects/{id}/upload-urls/documents": { "post": { "tags": [ "Projects" ], "summary": "Creates presigned URLs for uploading documents to a project. Creates a new conversation for the upload session. Supports pdf. Maximum 20 files per request.", "description": "**Required scope:** `projects.write`", "parameters": [ { "name": "id", "in": "path", "description": "The id of the project to upload documents to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Request containing file metadata and optional conversation settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectFileUploadRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseDto" } } } } }, "security": [ { "oauth2": [ "projects.write" ] } ] } }, "/v1/projects/{id}/upload-urls/videos": { "post": { "tags": [ "Projects" ], "summary": "Creates presigned URLs for uploading videos to a project. Creates a new conversation for the upload session. Supports mp4, mov. Maximum 20 files per request.", "description": "**Required scope:** `projects.write`", "parameters": [ { "name": "id", "in": "path", "description": "The id of the project to upload videos to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "Request containing file metadata and optional conversation settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectFileUploadRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileUploadResponseDto" } } } } }, "security": [ { "oauth2": [ "projects.write" ] } ] } }, "/v1/projects/{projectId}/sparks": { "post": { "tags": [ "Projects" ], "summary": "Creates a Spark on a project. If project media is not yet available, the Spark queues\r\nand starts automatically when media arrives. Status is always `\"queued\"`.", "description": "**Required scope:** `sparks.write`", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSparkRequestDto" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSparkResponseDto" } } } } }, "security": [ { "oauth2": [ "sparks.write" ] } ] }, "get": { "tags": [ "Projects" ], "summary": "Lists all Spark runs for a project, sorted by creation date descending.", "description": "**Required scope:** `sparks`", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SparkListResponseDto" } } } } }, "security": [ { "oauth2": [ "sparks" ] } ] } }, "/v1/recordings/{id}": { "get": { "tags": [ "Recordings" ], "summary": "Gets a recording by id.", "description": "**Required scope:** `recordings`", "parameters": [ { "name": "id", "in": "path", "description": "The id of the recording you want to get.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordingDto" } } } } }, "security": [ { "oauth2": [ "recordings" ] } ] } }, "/v1/recordings/project/{projectId}": { "get": { "tags": [ "Recordings" ], "summary": "Gets recordings by project id.", "description": "**Required scope:** `recordings`", "parameters": [ { "name": "projectId", "in": "path", "description": "The id of the project you want to get a list of recordings for.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecordingDto" } } } } } }, "security": [ { "oauth2": [ "recordings" ] } ] } }, "/v1/recordings/conversation/{conversationId}": { "get": { "tags": [ "Recordings" ], "summary": "Gets recordings by conversation id.", "description": "**Required scope:** `recordings`", "parameters": [ { "name": "conversationId", "in": "path", "description": "The id of the conversation you want to get a list of recordings for.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecordingDto" } } } } } }, "security": [ { "oauth2": [ "recordings" ] } ] } }, "/v1/sparks/{id}": { "get": { "tags": [ "Sparks" ], "summary": "Gets a Spark run by its ID.", "description": "**Required scope:** `sparks`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SparkDto" } } } } }, "security": [ { "oauth2": [ "sparks" ] } ] }, "delete": { "tags": [ "Sparks" ], "summary": "Deletes a Spark run through contact-api so queued schedules and Scribe analyses are cleaned up together.", "description": "**Required scope:** `sparks.write`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSparkResponseDto" } } } } }, "security": [ { "oauth2": [ "sparks.write" ] } ] } }, "/v1/sparks/{id}/share": { "post": { "tags": [ "Sparks" ], "summary": "Enables public sharing for a Spark report. Anyone with the returned URL can view the\r\nreport without authentication (read-only). Sharing can be enabled at any status — a\r\nqueued or running Spark's URL renders once the report completes. Re-sharing returns\r\nthe same URL. Sharing cannot currently be revoked via the API.", "description": "**Required scope:** `sparks.write`", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareSparkResponseDto" } } } } }, "security": [ { "oauth2": [ "sparks.write" ] } ] } }, "/v1/spark-templates": { "get": { "tags": [ "SparkTemplates" ], "summary": "Lists installed Spark templates for the organization. Pass `installed=true` to filter to only\r\ninstalled Spark templates. Uses cursor pagination: pass query's `cursor` from the\r\nprevious response body's `nextCursor` field (or omit for the first page).", "description": "**Required scope:** `spark-templates`", "parameters": [ { "name": "installed", "in": "query", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SparkTemplatesResponseDto" } } } } }, "security": [ { "oauth2": [ "spark-templates" ] } ] } }, "/v1/spark-templates/{sparkTemplateId}/validate-inputs": { "post": { "tags": [ "SparkTemplates" ], "summary": "Validates the inputs for running a Spark template: the task inputs, and that the platforms its tasks need are\r\nconnected. Nothing is run. On success, send the returned `validationToken` when running the Spark (POST\r\n/v1/conversations/{id}/sparks or /v1/projects/{id}/sparks): it carries these inputs, so the run does not validate\r\nthem again. The token is valid for 24 hours, and only until the Spark template changes.", "description": "**Required scope:** `sparks.write`", "parameters": [ { "name": "sparkTemplateId", "in": "path", "description": "The Spark template id from `GET /v1/spark-templates`.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "The task inputs, exactly as for running a Spark.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateSparkInputsRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateSparkInputsResponseDto" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "oauth2": [ "sparks.write" ] } ] } }, "/v1/spark-templates/{sparkTemplateId}/tasks/{taskCodeName}/inputs/{fieldKey}/options": { "get": { "tags": [ "SparkTemplates" ], "summary": "Looks up the valid answers for one selection input of a Spark template task. Use it for inputs whose\r\n`lookup` is set (answers from a connected platform), and for fixed-list inputs (`options`).\r\nSend the option you pick back in `tasks[].inputs` as `{ \"value\": ..., \"displayLabel\": ... }`.", "description": "**Required scope:** `spark-templates`", "parameters": [ { "name": "sparkTemplateId", "in": "path", "description": "The Spark template id from `GET /v1/spark-templates`.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "taskCodeName", "in": "path", "description": "The task's `codeName`.", "required": true, "schema": { "type": "string" } }, { "name": "fieldKey", "in": "path", "description": "The input's `key`.", "required": true, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "What to search for, when the input's `lookup.searchable` is true (e.g. a name, phone number or email). For a fixed list it filters by label.", "schema": { "type": "string" } }, { "name": "parent", "in": "query", "description": "Values of the inputs listed in `lookup.dependsOn`, as `parent[key]=value` — the `value` you picked for each.", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SparkTaskInputOptionsResponseDto" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "security": [ { "oauth2": [ "spark-templates" ] } ] } }, "/v1/tags": { "post": { "tags": [ "Tags" ], "summary": "Creates a tag", "description": "**Required scope:** `tags.write`", "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagCreateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagDto" } } } } }, "security": [ { "oauth2": [ "tags.write" ] } ] }, "get": { "tags": [ "Tags" ], "summary": "Retrieves a list of tags", "description": "**Required scope:** `tags`", "parameters": [ { "name": "page", "in": "query", "description": "The page number to retrieve, from 1 to int.MaxValue, default 1", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of records to return per page, from 1 to 100, default 10", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "where", "in": "query", "description": "Custom querying. Extended documentation forthcoming. Contact support@liveswitch.com with questions.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Custom ordering. By default records are always returned by date, most recent first.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TagDto" } } } } } }, "security": [ { "oauth2": [ "tags" ] } ] } }, "/v1/tags/{id}": { "put": { "tags": [ "Tags" ], "summary": "Updates a tag. Supports partial updates.", "description": "**Required scope:** `tags.write`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagUpdateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagDto" } } } } }, "security": [ { "oauth2": [ "tags.write" ] } ] } }, "/v1/tokens": { "get": { "tags": [ "Tokens" ], "summary": "Deprecated; see getting started guide. Initiates a login and access token flow.", "description": "Creates a URL to redirect the user to Auth0 for authentication. Optionally auto-redirects the user to the URL.\r\n Note that regardless of the scope, the user still must have permission for the requested action in LiveSwith Contact.\r\n Scopes can limit access to APIs further, but cannot grant MORE access than the user has based on their role.", "parameters": [ { "name": "clientId", "in": "query", "description": "The client ID for your application, from the \"My Developer Apps\" area.", "schema": { "type": "string" } }, { "name": "callbackUrl", "in": "query", "description": "Where to redirect the user after they log in.", "schema": { "type": "string" } }, { "name": "responseType", "in": "query", "description": "The type of auth token to create; read the Getting Started guide for details.", "schema": { "$ref": "#/components/schemas/TokenResponseType" } }, { "name": "scopes", "in": "query", "description": "Possible scopes are: openid profile email offline_access conversations.write contacts.write webhooks.write me applications.write guided-instructions", "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Allows passing additional state to the login flow, and eventually back to your application.", "schema": { "type": "string" } }, { "name": "nonce", "in": "query", "description": "Used for enhanced security on the request.", "schema": { "type": "string" } }, { "name": "redirect", "in": "query", "description": "true to redirect the user via 302, false to return an object with a url parameter instead.", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" } } } }, "302": { "description": "Found" } }, "deprecated": true } }, "/v1/tokens/code": { "post": { "tags": [ "Tokens" ], "summary": "Deprecated; see getting started guide. Converts an auth code to an access token", "description": "This is the flow that regular web apps use to access an API. Use this endpoint to exchange an Authorization Code for a token.", "parameters": [ { "name": "clientId", "in": "query", "description": "Your application's Client ID.", "schema": { "type": "string" } }, { "name": "clientSecret", "in": "query", "description": "Your application's Client Secret.", "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "The Authorization Code received from the initial /token call.", "schema": { "type": "string" } }, { "name": "redirectUri", "in": "query", "description": "This is required only if it was set at the GET /token endpoint. The values from /token must match the value you set at /oauth/token", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns a valid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessTokenDto" } } } }, "400": { "description": "The request is invalid, make sure the parameters are correct" } }, "deprecated": true } }, "/v1/tokens/refresh": { "post": { "tags": [ "Tokens" ], "summary": "Deprecated; see getting started guide. Refreshes an access token", "parameters": [ { "name": "clientId", "in": "query", "description": "", "schema": { "type": "string" } }, { "name": "clientSecret", "in": "query", "description": "", "schema": { "type": "string" } }, { "name": "refreshToken", "in": "query", "description": "", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } }, "deprecated": true } }, "/v1/tokens/logout": { "get": { "tags": [ "Tokens" ], "summary": "Deprecated; see getting started guide. Logs the user out", "description": "Note that this does an immediate redirect, so cannot be used from the \"Try\" button of the developer console.\r\n Instead, just copy the URL from the preview window into your browser URL bar to test.", "parameters": [ { "name": "clientId", "in": "query", "description": "Your application's client ID", "schema": { "type": "string" } }, { "name": "returnTo", "in": "query", "description": "The URL to return the user to after logging out. MUST exist in your list of valid logout URLs.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } }, "deprecated": true } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Gets a list of all webhooks for this organization", "description": "**Required scope:** `webhooks`", "parameters": [ { "name": "page", "in": "query", "description": "The page number to retrieve, from 1 to int.MaxValue, default 1", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of records to return per page, from 1 to 100, default 10", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "where", "in": "query", "description": "Custom querying. Extended documentation forthcoming. Contact support@liveswitch.com with questions.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Custom ordering. By default records are always returned by date, most recent first.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDto" } } } } } }, "security": [ { "oauth2": [ "webhooks" ] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Creates a webhook.", "description": "**Required scope:** `webhooks.write`", "requestBody": { "description": "The entity containing the values to update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDto" } } }, "links": { "unsubscribeOperation": { "operationId": "unsubscribe", "parameters": { "id": "$response.body#/id" }, "description": "Removes the subscription" } } } }, "callbacks": { "Conversations Created": { "https://example.com/v1/new-conversation": { "post": { "summary": "Triggers when a Conversation is created.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Conversations Updated": { "https://example.com/v1/new-updated-conversation": { "post": { "summary": "Triggers when a Conversation is updated.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Conversations Deleted": { "https://example.com/v1/deleted-conversation": { "post": { "summary": "Triggers when a Conversation is deleted.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Contacts Created": { "https://example.com/v1/new-contact": { "post": { "summary": "Triggers when a Contact is created.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Contacts Updated": { "https://example.com/v1/updated-contact": { "post": { "summary": "Triggers when a Contact is updated.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Contacts Deleted": { "https://example.com/v1/updated-contact": { "post": { "summary": "Triggers when a Contact is deleted.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Accounts Created": { "https://example.com/v1/new-account": { "post": { "summary": "Triggers when an Account is created.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Accounts Updated": { "https://example.com/v1/updated-account": { "post": { "summary": "Triggers when an Account is updated, including AccountRole changes.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Accounts Deleted": { "https://example.com/v1/deleted-account": { "post": { "summary": "Triggers when an Account is deleted.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "AppInstallations Created": { "https://example.com/v1/new-app-installation": { "post": { "summary": "Triggers when an App is installed.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInstallationDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "AppInstallations Deleted": { "https://example.com/v1/deleted-app-installation": { "post": { "summary": "Triggers when an App is uninstalled.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppInstallationDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Recordings Created": { "https://example.com/v1/new-recording": { "post": { "summary": "Triggers when a Recording is created.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordingDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Recordings Updated": { "https://example.com/v1/new-updated-recording": { "post": { "summary": "Triggers when a Recording is updated.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordingDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Recordings Deleted": { "https://example.com/v1/deleted-recording": { "post": { "summary": "Triggers when a Recording is deleted.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordingDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Documents Created": { "https://example.com/v1/new-document": { "post": { "summary": "Triggers when a Document is created.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Documents Updated": { "https://example.com/v1/new-updated-document": { "post": { "summary": "Triggers when a Document is updated.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } }, "Documents Deleted": { "https://example.com/v1/deleted-document": { "post": { "summary": "Triggers when a Document is deleted.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDto" } } } }, "responses": { "200": { "description": "Your server implementation should return this HTTP status code if the data was received successfully" }, "400": { "description": "If your server returns an HTTP status code indicating it does not understand the format of the payload the delivery will be treated as a failure. No retries are attempted." }, "500": { "description": "If your server returns an HTTP status code indicating a server-side error the delivery will be treated as a failure. 3 retries are attempted." } } } } } }, "security": [ { "oauth2": [ "webhooks.write" ] } ] } }, "/v1/webhooks/by-app/{appId}": { "get": { "tags": [ "Webhooks" ], "summary": "Gets a list of all webhooks for this organization and the specific app", "description": "**Required scope:** `webhooks`", "parameters": [ { "name": "appId", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "The page number to retrieve, from 1 to int.MaxValue, default 1", "schema": { "maximum": 2147483647, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "pageSize", "in": "query", "description": "The maximum number of records to return per page, from 1 to 100, default 10", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "where", "in": "query", "description": "Custom querying. Extended documentation forthcoming. Contact support@liveswitch.com with questions.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "description": "Custom ordering. By default records are always returned by date, most recent first.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDto" } } } } } }, "security": [ { "oauth2": [ "webhooks" ] } ] } }, "/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Gets a webhook by id.", "description": "**Required scope:** `webhooks`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDto" } } } } }, "security": [ { "oauth2": [ "webhooks" ] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Deletes a webhook", "description": "**Required scope:** `webhooks.write`", "parameters": [ { "name": "id", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } }, "security": [ { "oauth2": [ "webhooks.write" ] } ] }, "put": { "tags": [ "Webhooks" ], "summary": "Updates a webhoook", "description": "**Required scope:** `webhooks.write`", "parameters": [ { "name": "id", "in": "path", "description": "The ID to be updated.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "The entity containing the values to update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdateRequestDto" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDto" } } } } }, "security": [ { "oauth2": [ "webhooks.write" ] } ] } }, "/v1/webhooks/app/{appId}": { "delete": { "tags": [ "Webhooks" ], "summary": "Deletes all webhooks by app id", "description": "**Required scope:** `webhooks.write`", "operationId": "unsubscribe", "parameters": [ { "name": "appId", "in": "path", "description": "", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } }, "security": [ { "oauth2": [ "webhooks.write" ] } ] } } }, "components": { "schemas": { "AccessTokenDto": { "type": "object", "properties": { "access_token": { "type": "string", "nullable": true }, "token_type": { "type": "string", "nullable": true }, "expires_in": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "AccountDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the account membership.", "format": "uuid" }, "userId": { "type": "string", "description": "Identifier of the associated User.", "format": "uuid" }, "organizationId": { "type": "string", "description": "Identifier of the Organization the account belongs to.", "format": "uuid" }, "busy": { "type": "boolean", "description": "Indicates whether the user is currently marked as busy for routing calls." }, "active": { "type": "boolean", "description": "Indicates whether the user is actively receiving conversations." }, "lastCallAssignedDate": { "type": "string", "description": "Date of the last time a call was assigned to this account.", "format": "date-time", "nullable": true }, "lastCallAnsweredDate": { "type": "string", "description": "Date of the last time a call was answered by this account.", "format": "date-time", "nullable": true }, "callOrder": { "type": "integer", "description": "The round-robin order for routing calls.", "format": "int32" }, "createdBy": { "type": "string", "description": "User who originally created the account, if tracked.", "format": "uuid", "nullable": true }, "updatedBy": { "type": "string", "description": "User who last updated the account, if tracked.", "format": "uuid", "nullable": true }, "deletedBy": { "type": "string", "description": "User who deleted the account, if soft-deleted.", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "description": "When the account record was created.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the account record was last updated.", "format": "date-time" }, "deletedAt": { "type": "string", "description": "When the account record was deleted, if applicable.", "format": "date-time", "nullable": true }, "isSubscriptionOwner": { "type": "boolean", "description": "Indicates whether the account owns the organization's subscription.", "nullable": true }, "user": { "$ref": "#/components/schemas/AccountUserDto" } }, "additionalProperties": false, "description": "Represents an Account/user membership inside an Organization.\r\nWebhook notifications for Accounts are also emitted when the Account's roles change." }, "AccountGetDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the account.", "format": "uuid" }, "userId": { "type": "string", "description": "The user ID associated with this account.", "format": "uuid" }, "organizationId": { "type": "string", "description": "The organization ID to which this account belongs.", "format": "uuid" }, "email": { "type": "string", "description": "The email address of the user.", "nullable": true }, "role": { "type": "string", "description": "The name of the role assigned to this account.", "nullable": true }, "roleId": { "type": "string", "description": "The ID of the role assigned to this account.", "format": "uuid", "nullable": true } }, "additionalProperties": false, "description": "Represents an account in the public API response." }, "AccountUserDto": { "required": [ "firstName", "lastName" ], "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the user.", "format": "uuid" }, "firstName": { "minLength": 1, "type": "string", "description": "First name for the user." }, "lastName": { "minLength": 1, "type": "string", "description": "Last name for the user." }, "email": { "type": "string", "description": "Primary email address for the user.", "format": "email", "nullable": true }, "externalKey": { "type": "string", "description": "Optional external key used by third-party systems.", "nullable": true }, "phone": { "type": "string", "description": "Primary phone number formatted as stored inside SupBubble.", "nullable": true }, "enabled": { "type": "boolean", "description": "Indicates whether the user can sign in." }, "timezone": { "type": "string", "description": "Preferred timezone for scheduling purposes.", "nullable": true }, "holidays": { "type": "array", "items": { "type": "string" }, "description": "Optional list of holiday identifiers associated with the user.", "nullable": true }, "notificationSms": { "type": "boolean", "description": "Indicates whether SMS notifications are enabled." }, "notificationEmail": { "type": "boolean", "description": "Indicates whether email notifications are enabled." }, "notificationTeams": { "type": "boolean", "description": "Indicates whether Teams notifications are enabled." }, "notificationSlack": { "type": "boolean", "description": "Indicates whether Slack notifications are enabled." }, "notificationDashboard": { "type": "boolean", "description": "Indicates whether in-app/dashboard notifications are enabled." }, "createdAt": { "type": "string", "description": "When the user was created.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "When the user was last updated.", "format": "date-time" }, "deletedAt": { "type": "string", "description": "When the user was deleted, if they have been removed.", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Minimal representation of the user tied to an account." }, "AppInstallationDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "nullable": true }, "organizationId": { "type": "string", "format": "uuid", "nullable": true }, "appId": { "type": "string", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "AttributeDataType": { "enum": [ "Boolean", "DateTime", "Float", "Integer", "String", "Uuid", "Link" ], "type": "string" }, "AttributeDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the attribute", "format": "uuid", "nullable": true }, "organizationId": { "type": "string", "description": "The organization that the attribute belongs to", "format": "uuid", "nullable": true }, "attributeGroupId": { "type": "string", "description": "The group this attribute is a part of", "format": "uuid", "nullable": true }, "name": { "type": "string", "description": "Unique code name within group", "nullable": true }, "label": { "type": "string", "description": "The label for this attribute, which will be displayed when rendering the Entity Attribute", "nullable": true }, "dataType": { "$ref": "#/components/schemas/AttributeDataType" }, "defaultValue": { "type": "string", "description": "A default value, used if no Entity Attribute exists for a given Entity", "nullable": true }, "format": { "type": "string", "description": "A formatting string, used when rendering the Entity Attribute. This value\r\nchanges function based on the DataType.\r\nno value: '-no value-'\r\nlink: '' + title || 'Link' + '';\r\nboolean: value ? 'Yes' : 'No'\r\ndatetime: moment(value).format(attribute.format || timezones.defaultDateFormat)\r\nfloat: parseFloat(value).toFixed(attribute.format || 2)\r\ninteger: parseInt(value).toFixed(attribute.format || 2)\r\ndefault: value", "nullable": true }, "order": { "type": "integer", "description": "When rendering in the UI within an attribute group, multiple fields are sorted by order.", "format": "int64", "nullable": true }, "createdAt": { "type": "string", "description": "When the entity was created", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "description": "When the entity was updated", "format": "date-time", "nullable": true }, "entityName": { "$ref": "#/components/schemas/AttributeEntityType" }, "attributeGroup": { "$ref": "#/components/schemas/AttributeGroupDto" } }, "additionalProperties": false }, "AttributeEntityType": { "enum": [ "Conversations", "Contacts", "Projects" ], "type": "string" }, "AttributeGroupDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the group", "format": "uuid", "nullable": true }, "organizationId": { "type": "string", "description": "The organization to whom the attributes below", "format": "uuid", "nullable": true }, "name": { "type": "string", "description": "Unique code name (e.g. \"hcp_app\"). Only alphanumeric, underscore, and hyphen allowed.", "nullable": true }, "label": { "type": "string", "description": "Display label for UI (e.g. \"HCP App\")", "nullable": true }, "createdAt": { "type": "string", "description": "When the record was created", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "description": "When the record was updated", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Attribute groups are collections of attributes, with a name, optionally linked to an appId." }, "AttributeGroupRequestDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique code name (e.g. \"hcp_app\" or \"HCP_App\" - both stored as \"hcp_app\").\r\nOnly lowercase alphanumeric, underscore, and hyphen allowed.\r\nCASE-INSENSITIVE: \"HCP_App\" and \"hcp_app\" are treated as the same name.\r\nThe name will be automatically converted to lowercase.", "nullable": true }, "label": { "type": "string", "description": "Display label for UI (e.g. \"HCP App Settings\")", "nullable": true } }, "additionalProperties": false, "description": "Request DTO for creating or updating an attribute group" }, "AttributeRequestDto": { "required": [ "attributeGroupId", "dataType", "entityName", "label", "name" ], "type": "object", "properties": { "attributeGroupId": { "type": "string", "description": "The group this attribute is a part of", "format": "uuid" }, "name": { "minLength": 1, "type": "string", "description": "Unique code name within group (e.g. \"client_id\" or \"Client_ID\" - both stored as \"client_id\").\r\nOnly lowercase alphanumeric, underscore, and hyphen allowed.\r\nCASE-INSENSITIVE: \"Client_ID\" and \"client_id\" are treated as the same name.\r\nThe name will be automatically converted to lowercase." }, "label": { "minLength": 1, "type": "string", "description": "The label for this attribute, which will be displayed when rendering the Entity Attribute" }, "dataType": { "$ref": "#/components/schemas/AttributeDataType" }, "defaultValue": { "type": "string", "description": "A default value, used if no Entity Attribute exists for a given Entity", "nullable": true }, "format": { "type": "string", "description": "A formatting string, used when rendering the Entity Attribute", "nullable": true }, "order": { "type": "integer", "description": "When rendering in the UI within an attribute group, multiple fields are sorted by order.", "format": "int64", "nullable": true }, "entityName": { "$ref": "#/components/schemas/AttributeEntityType" } }, "additionalProperties": false, "description": "Request DTO for creating or updating an attribute" }, "AttributeUpdateRequestDto": { "type": "object", "properties": { "label": { "type": "string", "description": "The label for this attribute, which will be displayed when rendering the Entity Attribute", "nullable": true }, "defaultValue": { "type": "string", "description": "A default value, used if no Entity Attribute exists for a given Entity", "nullable": true }, "format": { "type": "string", "description": "A formatting string, used when rendering the Entity Attribute", "nullable": true }, "order": { "type": "integer", "description": "When rendering in the UI within an attribute group, multiple fields are sorted by order.", "format": "int64", "nullable": true } }, "additionalProperties": false, "description": "Request DTO for updating an attribute\r\nNote: DataType and EntityName cannot be changed after creation" }, "ContactCreateRequestDto": { "type": "object", "properties": { "firstName": { "type": "string", "description": "This is the contact's first name.", "nullable": true, "example": "John" }, "lastName": { "type": "string", "description": "This is the contact's last name.", "nullable": true }, "email": { "type": "string", "description": "This is the contact's email; phone or email is required.", "nullable": true }, "phone": { "type": "string", "description": "This is the contact's phone; phone or email is required.", "nullable": true, "example": "+1 407-982-1111" }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/EntityAttributeValueDto" }, "description": "Optional attributes to set on the contact. Use either attributeId or attributeGroupName+attributeName.", "nullable": true } }, "additionalProperties": false }, "ContactDto": { "type": "object", "properties": { "id": { "type": "string", "description": "This is the contact's system wide unique identifier", "format": "uuid", "nullable": true }, "organizationId": { "type": "string", "description": "The OrganizationId to which the Contact belongs", "format": "uuid", "nullable": true }, "firstName": { "type": "string", "description": "This is the contact's first name, an optional field", "nullable": true }, "lastName": { "type": "string", "description": "This is the contact's last name, an optional field", "nullable": true }, "email": { "type": "string", "description": "This is the contact's email, an optional field", "nullable": true }, "phone": { "type": "string", "description": "This is the contact's phone, an optional field", "nullable": true }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/EntityAttributeResponseDto" }, "description": "Attributes assigned to this contact", "nullable": true } }, "additionalProperties": false }, "ContactListDto": { "type": "object", "properties": { "id": { "type": "string", "description": "This is the contact's system wide unique identifier", "format": "uuid", "nullable": true }, "organizationId": { "type": "string", "description": "The OrganizationId to which the Contact belongs", "format": "uuid", "nullable": true }, "firstName": { "type": "string", "description": "This is the contact's first name, an optional field", "nullable": true }, "lastName": { "type": "string", "description": "This is the contact's last name, an optional field", "nullable": true }, "email": { "type": "string", "description": "This is the contact's email, an optional field", "nullable": true }, "phone": { "type": "string", "description": "This is the contact's phone, an optional field", "nullable": true } }, "additionalProperties": false, "description": "Contact list item (without attributes for performance)" }, "ContactUpdateRequestDto": { "type": "object", "properties": { "id": { "type": "string", "description": "This is the contact's system wide unique identifier", "format": "uuid", "nullable": true }, "firstName": { "type": "string", "description": "This is the contact's first name", "nullable": true }, "lastName": { "type": "string", "description": "This is the contact's last name", "nullable": true }, "email": { "type": "string", "description": "This is the contact's email", "nullable": true }, "phone": { "type": "string", "description": "This is the contact's phone number", "nullable": true } }, "additionalProperties": false, "description": "Represents a request to update a contact" }, "ConversationCreateRequestDto": { "required": [ "type" ], "type": "object", "properties": { "contactId": { "type": "string", "description": "The ID of the Contact record this Conversation will be associated with; if set and valid, the phone number will be ignored.\r\nIf set and invalid, throws an error. If the contact exists, it will NOT be updated.", "format": "uuid", "nullable": true }, "phone": { "type": "string", "description": "The Phone of the Contact record this Conversation will be associated with; if set, the phone number will be looked up\r\nand if a Contact exists with that number, that Contact will be utilized. If the phone number does NOT exist, a new\r\ncontact will be created using the specified number. If the contact exists, it will NOT be updated.", "nullable": true }, "email": { "type": "string", "description": "The Email of the Contact record this Conversation will be associated with if it is created.", "nullable": true }, "firstName": { "type": "string", "description": "The FirstName of the Contact record this Conversation will be associated with if it is created.", "nullable": true }, "lastName": { "type": "string", "description": "The LastName of the Contact record this Conversation will be associated with if it is created.", "nullable": true }, "message": { "type": "string", "description": "The contents of the text message the user will receive. For Scheduled conversations, omit this field to\r\nuse the organization's configured scheduled-call template, which resolves ${user}, ${organization},\r\n${day}, ${date}, ${time}, ${timezone}, and ${scheduledDate}. If provided, the message is sent as-is\r\nand placeholders are not resolved.", "nullable": true }, "notes": { "type": "string", "description": "Notes to save on the Conversation.", "nullable": true }, "name": { "type": "string", "description": "Optional name/title for the conversation. For StartRecording, this becomes the session name.\r\nFor TakePhotos, this becomes the photo session name.", "nullable": true }, "type": { "$ref": "#/components/schemas/ConversationType" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional. Array of tag names to assign to the project. Tags will be auto-created if they don't exist.", "nullable": true }, "autoStartRecording": { "type": "boolean", "description": "This only applies to LiveConversation" }, "sendSmsNotification": { "type": "boolean", "description": "When set to true, the user is sent a text message invite to the Conversation.\r\nOnly applies to LiveConversation, RecordingRequest, and Scheduled types; ignored for StartRecording, TakePhotos,\r\nand Uploads." }, "sendEmailNotification": { "type": "boolean", "description": "When set to true, the user is sent an email invite/reminder to the Conversation. Requires Email or ContactId to be set.\r\nEmail invite/reminder delivery also requires Allow Email Invitations to be enabled in organization settings.\r\nOnly applies to LiveConversation, RecordingRequest, and Scheduled types; ignored for StartRecording, TakePhotos, and Uploads." }, "assignedUserId": { "type": "string", "description": "Optional. The user to assign the conversation to.", "format": "uuid", "nullable": true }, "startAt": { "type": "string", "description": "Required when Type is Scheduled. The scheduled start date/time in UTC.", "format": "date-time", "nullable": true }, "endAt": { "type": "string", "description": "Optional when Type is Scheduled. The scheduled end date/time in UTC.", "format": "date-time", "nullable": true }, "timezone": { "type": "string", "description": "Optional IANA timezone used for scheduled reminder text formatting. If omitted, the organization's default\r\ntimezone is used.", "nullable": true }, "projectId": { "type": "string", "description": "Optional. The id of a project to associate the conversation with. If specified, will link\r\nthis session into the specified project. If this value is provided then ProjectExternalId will be ignored.", "nullable": true }, "projectExternalId": { "type": "string", "description": "Optional. The external id of a project to associate this conversation with. If specified, will link\r\nthis session into the specified project. See LiveSwitch.Integration.Api.Models.v1.Conversation.ConversationCreateRequestDto.ProjectAutoCreate for more.", "nullable": true }, "projectAutoCreate": { "type": "boolean", "description": "Optional, default false. If this value is true, and no project with the specified ProjectExternalId exists,\r\na project will be created using the ProjectExternalId and ProjectName.\r\nIf this value is true, ProjectExternalId is required.\r\nIf this value is false, and the ProjectExternalId is specified but does not\r\nexist, the request will fail and no data will be modified." }, "projectName": { "type": "string", "description": "Optional, default empty. Only used if ProjectAutoCreate is true, and no project with a matching\r\nProjectExternalId was found. If not specified, will auto-generate a name\r\nusing the pattern \"Project [project external id]\". Note that project names must be unique.", "nullable": true }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/EntityAttributeValueDto" }, "description": "Optional attributes to set on the conversation. Use either attributeId or attributeGroupName+attributeName.", "nullable": true }, "guidedInstructionId": { "type": "string", "description": "Optional. The ID of the guided instructions to apply to the conversation.\r\nUse an ID returned by `GET /v1/guided-instructions`.\r\nSupported conversation types are `RecordingRequest`, `StartRecording`, and `TakePhotos`.\r\nWhen provided it must be a valid GUID; an empty or whitespace value is ignored (treated as no guided instruction).", "nullable": true } }, "additionalProperties": false, "description": "DTO for Conversation create request" }, "ConversationDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the Conversation", "format": "uuid" }, "type": { "type": "string", "description": "Represents the type of Conversation. Values are LiveConversation, RecordingRequest, StartRecording, TakePhotos, or Uploads", "nullable": true }, "organizationId": { "type": "string", "description": "The OrganizationID that owns this Conversation", "format": "uuid", "nullable": true }, "hostJoinUrl": { "type": "string", "description": "The conversation URL the host will use to join and take notes, screenshots, etc.\r\nFor StartRecording, TakePhotos, and Uploads types, this will be null.", "nullable": true }, "participantJoinUrl": { "type": "string", "description": "The conversation URL the participant will use.\r\nFor StartRecording and TakePhotos types, this will be the URL for the user to start their own recording or photo session.\r\nFor Uploads types, this will be null. Use the documents API to upload files to the conversation.", "nullable": true }, "conversationUrl": { "type": "string", "description": "The conversation URL that an authenticated admin user can use to review the recording, notes, etc.", "nullable": true }, "embeddedConversationUrl": { "type": "string", "description": "The conversation URL that an authenticated admin user can use to review the recording, notes, etc, without a header or navigation bar.", "nullable": true }, "projectShareUrl": { "type": "string", "description": "The URL that an un-authenticated user can use to review the recording, notes, etc. This URL will be blank if the project is not shared.", "nullable": true }, "projectUrl": { "type": "string", "description": "The URL that an authenticated user can use to review the recording, notes, etc.", "nullable": true }, "projectEmbeddedUrl": { "type": "string", "description": "The URL that an authenticated user can use to review the recording, notes, etc, without any header/nav bar/etc.", "nullable": true }, "projectEmbeddedShareUrl": { "type": "string", "description": "The URL that an un-authenticated user can use to review the recording, notes, etc, without any header/nav bar/etc. This URL will be blank if the project is not shared.", "nullable": true }, "projectId": { "type": "string", "description": "The project identifier, if there is one, associated with this Conversation.", "nullable": true }, "assignedUserId": { "type": "string", "description": "The ID of the LiveSwitch user assigned to this Conversation, or null when unassigned.", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "description": "The date and time the conversation was created", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date and time the conversation was last updated", "format": "date-time" }, "startAt": { "type": "string", "description": "The scheduled start date/time for scheduled conversations, or null for non-scheduled conversations.", "format": "date-time", "nullable": true }, "endAt": { "type": "string", "description": "The scheduled end date/time for scheduled conversations, or null for non-scheduled conversations.", "format": "date-time", "nullable": true }, "name": { "type": "string", "description": "The name of the conversation", "nullable": true }, "contactId": { "type": "string", "description": "The ID of the Contact record associated with this Conversation", "nullable": true }, "status": { "type": "string", "description": "The Status of the Conversation. Useful when listening for updates via Webhooks, tracking the \"ReadyForReview\" state meaning\r\nat least one recording is available. Note that this Status may occur multiple times if multiple recordings are created for this Conversation.", "nullable": true }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagDto" }, "description": "Tags assigned to this project", "nullable": true }, "qrCodeId": { "type": "string", "description": "The ID of the QR code that was used to create this conversation, or null.", "format": "uuid", "nullable": true }, "kioskId": { "type": "string", "description": "The ID of the Kiosk that was used to create this conversation, or null.", "format": "uuid", "nullable": true }, "formId": { "type": "string", "description": "The ID of the Form that was used to create this conversation, or null.", "format": "uuid", "nullable": true }, "formSubmissionId": { "type": "string", "description": "The ID of the Form Submission that was used to create this conversation, or null. Note that a given Form can be submitted multiple times, each creating a new FormSubmission.", "format": "uuid", "nullable": true }, "contact": { "$ref": "#/components/schemas/ContactDto" }, "createdByEmail": { "type": "string", "description": "The email address of the user who created this Conversation", "nullable": true }, "notes": { "type": "string", "description": "Notes associated with this Conversation", "nullable": true }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/EntityAttributeResponseDto" }, "description": "Attributes assigned to this conversation", "nullable": true } }, "additionalProperties": false }, "ConversationListDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the Conversation", "format": "uuid" }, "type": { "type": "string", "description": "Represents the type of Conversation. Values are LiveConversation, RecordingRequest, StartRecording, TakePhotos, or Uploads", "nullable": true }, "organizationId": { "type": "string", "description": "The OrganizationID that owns this Conversation", "format": "uuid", "nullable": true }, "hostJoinUrl": { "type": "string", "description": "The conversation URL the host will use to join and take notes, screenshots, etc.\r\nFor StartRecording, TakePhotos, and Uploads types, this will be null.", "nullable": true }, "participantJoinUrl": { "type": "string", "description": "The conversation URL the participant will use.\r\nFor StartRecording and TakePhotos types, this will be the URL for the user to start their own recording or photo session.\r\nFor Uploads types, this will be null. Use the documents API to upload files to the conversation.", "nullable": true }, "conversationUrl": { "type": "string", "description": "The conversation URL that an authenticated admin user can use to review the recording, notes, etc.", "nullable": true }, "embeddedConversationUrl": { "type": "string", "description": "The conversation URL that an authenticated admin user can use to review the recording, notes, etc, without a header or navigation bar.", "nullable": true }, "projectShareUrl": { "type": "string", "description": "The URL that an un-authenticated user can use to review the recording, notes, etc. This URL will be blank if the project is not shared.", "nullable": true }, "projectUrl": { "type": "string", "description": "The URL that an authenticated user can use to review the recording, notes, etc.", "nullable": true }, "projectEmbeddedUrl": { "type": "string", "description": "The URL that an authenticated user can use to review the recording, notes, etc, without any header/nav bar/etc.", "nullable": true }, "projectEmbeddedShareUrl": { "type": "string", "description": "The URL that an un-authenticated user can use to review the recording, notes, etc, without any header/nav bar/etc. This URL will be blank if the project is not shared.", "nullable": true }, "projectId": { "type": "string", "description": "The project identifier, if there is one, associated with this Conversation.", "nullable": true }, "assignedUserId": { "type": "string", "description": "The ID of the LiveSwitch user assigned to this Conversation, or null when unassigned.", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "description": "The date and time the conversation was created", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date and time the conversation was last updated", "format": "date-time" }, "startAt": { "type": "string", "description": "The scheduled start date/time for scheduled conversations, or null for non-scheduled conversations.", "format": "date-time", "nullable": true }, "endAt": { "type": "string", "description": "The scheduled end date/time for scheduled conversations, or null for non-scheduled conversations.", "format": "date-time", "nullable": true }, "name": { "type": "string", "description": "The name of the conversation", "nullable": true }, "contactId": { "type": "string", "description": "The ID of the Contact record associated with this Conversation", "nullable": true }, "status": { "type": "string", "description": "The Status of the Conversation. Useful when listening for updates via Webhooks, tracking the \"ReadyForReview\" state meaning\r\nat least one recording is available. Note that this Status may occur multiple times if multiple recordings are created for this Conversation.", "nullable": true }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagDto" }, "description": "Tags assigned to this project", "nullable": true }, "qrCodeId": { "type": "string", "description": "The ID of the QR code that was used to create this conversation, or null.", "format": "uuid", "nullable": true }, "kioskId": { "type": "string", "description": "The ID of the Kiosk that was used to create this conversation, or null.", "format": "uuid", "nullable": true }, "formId": { "type": "string", "description": "The ID of the Form that was used to create this conversation, or null.", "format": "uuid", "nullable": true }, "formSubmissionId": { "type": "string", "description": "The ID of the Form Submission that was used to create this conversation, or null. Note that a given Form can be submitted multiple times, each creating a new FormSubmission.", "format": "uuid", "nullable": true }, "createdByEmail": { "type": "string", "description": "The email address of the user who created this Conversation", "nullable": true }, "contact": { "$ref": "#/components/schemas/ContactDto" }, "notes": { "type": "string", "description": "Notes associated with this Conversation", "nullable": true } }, "additionalProperties": false, "description": "Conversation list item (without attributes for performance)" }, "ConversationType": { "enum": [ "LiveConversation", "RecordingRequest", "StartRecording", "TakePhotos", "Uploads", "Scheduled" ], "type": "string", "description": "Represents the type of Conversation" }, "ConversationUpdateRequestDto": { "type": "object", "properties": { "contactId": { "type": "string", "description": "Optional. The ID of the Contact record to associate with this Conversation.", "format": "uuid", "nullable": true }, "notes": { "type": "string", "description": "Optional. Notes for the conversation.", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional. Array of tag names to assign to the conversation. Tags will be auto-created if they don't exist.", "nullable": true }, "name": { "type": "string", "description": "Optional. Name/title for the conversation.", "nullable": true }, "projectId": { "type": "string", "description": "Optional. The ID of the Project to associate with this Conversation.", "format": "uuid", "nullable": true }, "assignedUserId": { "type": "string", "description": "Optional. The ID of the LiveSwitch user to assign this Conversation to.", "format": "uuid", "nullable": true } }, "additionalProperties": false, "description": "DTO for Conversation update request" }, "CreateSparkRequestDto": { "type": "object", "properties": { "sparkTemplateId": { "type": "string", "description": "The ID of the Spark template to run. Obtain available IDs from GET /v1/spark-templates.", "nullable": true, "example": "eda160d7-5372-463c-8162-1f84648b93ac" }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/SparkTaskInputRequestDto" }, "description": "Input values for tasks in the Spark template, sent only with `skipInputValidation`: true. Normally, validate\r\nthe inputs first with POST /v1/spark-templates/{id}/validate-inputs and send its `validationToken` instead.\r\nThe Spark runs with the template's default task selection, matching Contact Admin.\r\nIdentify each task with `tasks[].codeName` from GET /v1/spark-templates.", "nullable": true }, "validationToken": { "type": "string", "description": "The token returned by POST /v1/spark-templates/{id}/validate-inputs. The Spark runs with the inputs that were\r\nvalidated, without validating them again. Required when the Spark template has user inputs, unless\r\n`skipInputValidation` is true; not needed for a template with no user inputs. Do not send `tasks` with\r\nit. Valid for 24 hours, and only until the Spark template's tasks or inputs change.", "nullable": true }, "skipInputValidation": { "type": "boolean", "description": "Set to true to run with `tasks` as sent, without validating them (no validation token needed). The platforms\r\nthe Spark uses must still be connected: if one is not, the run is refused with a 422 naming the platform and its login link.\r\nDefault false: send a `validationToken` from POST /v1/spark-templates/{id}/validate-inputs." }, "shareWith": { "type": "array", "items": { "type": "string" }, "description": "Optional sharing targets for the completed Spark.\r\nAccepted values: `[\"anyone\"]` to generate a public share URL.\r\nOmit or pass an empty array for no public sharing.", "nullable": true } }, "additionalProperties": false }, "CreateSparkResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this spark run. Use with GET /v1/sparks/{id}\r\nto poll for status.", "nullable": true }, "status": { "type": "string", "description": "Always `queued` — the spark has been accepted and will run when media is available.", "nullable": true } }, "additionalProperties": false }, "DeleteResult": { "type": "object", "properties": { "success": { "type": "boolean" } }, "additionalProperties": false }, "DocumentDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Refers to the unique identifier for a document.", "format": "uuid" }, "relatedEntity": { "$ref": "#/components/schemas/DocumentRelatedEntity" }, "projectId": { "type": "string", "description": "Refers to the project id in LiveSwitch Contact.", "format": "uuid", "nullable": true }, "conversationId": { "type": "string", "description": "Refers to the session id in LiveSwitch Contact.", "format": "uuid", "nullable": true }, "organizationId": { "type": "string", "description": "Refers to the organization id in LiveSwitch Contact.", "format": "uuid", "nullable": true }, "index": { "type": "integer", "description": "Refers to the display order from LiveSwitch Contact.", "format": "int32" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagDto" }, "description": "Tags assigned to this document", "nullable": true }, "externalAccessAllowed": { "type": "boolean", "description": "Refers to if the record can be accessed by the public url." }, "publicUrl": { "type": "string", "description": "Refers to the public url that can access the document without being logged into LiveSwitch Contact. Access can be removed if requested.", "nullable": true }, "thumbnailUrl": { "type": "string", "description": "Refers to the public url that can access the document's thumbnail without being logged into LiveSwitch Contact. Access can be removed if requested.", "nullable": true }, "fileName": { "type": "string", "description": "Refers to the best guess file name, not all files or snapshots have filenames attached to them.", "nullable": true }, "caption": { "type": "string", "description": "Refers to a caption added to the document.", "nullable": true }, "createdAt": { "type": "string", "description": "The date and time the document was created", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date and time the document was last updated", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Refers to a snapspot or asset uploaded to a project or session." }, "DocumentRelatedEntity": { "enum": [ "File", "Snapshot" ], "type": "string", "description": "What entity table does a document relate to when requiring more information about the document." }, "DocumentType": { "enum": [ "Image", "Document", "Video" ], "type": "string", "description": "Represents the type of document being uploaded" }, "EntityAttributeDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of this entity attribute instance.", "format": "uuid", "nullable": true }, "organizationId": { "type": "string", "description": "The organization ID.", "format": "uuid", "nullable": true }, "attributeId": { "type": "string", "description": "The attribute definition ID.", "format": "uuid", "nullable": true }, "attributeName": { "type": "string", "description": "The attribute definition name.", "nullable": true }, "attributeGroupId": { "type": "string", "description": "The attribute group ID.", "format": "uuid", "nullable": true }, "attributeGroupName": { "type": "string", "description": "The attribute group name.", "nullable": true }, "entityId": { "type": "string", "description": "The entity ID this attribute is attached to.", "format": "uuid", "nullable": true }, "title": { "type": "string", "description": "Optional title/display text (for link attributes, this is the link text).", "nullable": true }, "value": { "maxLength": 255, "type": "string", "description": "The attribute value.", "nullable": true }, "createdAt": { "type": "string", "description": "Timestamp when created.", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "description": "Timestamp when updated.", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "The value of the attribute added for an entity" }, "EntityAttributeRequestDto": { "required": [ "entityId", "value" ], "type": "object", "properties": { "attributeId": { "type": "string", "description": "The ID of the attribute definition (use this OR attributeGroupName+attributeName)", "format": "uuid", "nullable": true }, "attributeGroupName": { "type": "string", "description": "The attribute group name (must be used with attributeName)", "nullable": true }, "attributeName": { "type": "string", "description": "The attribute name within the group (must be used with attributeGroupName)", "nullable": true }, "entityId": { "type": "string", "description": "The ID of the entity (contact, conversation, etc.)", "format": "uuid" }, "value": { "maxLength": 255, "minLength": 1, "type": "string", "description": "The value to set" }, "title": { "type": "string", "description": "Optional title/display text (for link attributes, this is the link text)", "nullable": true } }, "additionalProperties": false, "description": "Request DTO for creating or updating an entity attribute.\r\nUse either attributeId OR (attributeGroupName + attributeName) to identify the attribute." }, "EntityAttributeResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of this entity attribute instance.", "format": "uuid", "nullable": true }, "organizationId": { "type": "string", "description": "The organization ID.", "format": "uuid", "nullable": true }, "attributeId": { "type": "string", "description": "The attribute definition ID.", "format": "uuid", "nullable": true }, "attributeName": { "type": "string", "description": "The attribute definition name.", "nullable": true }, "entityId": { "type": "string", "description": "The entity ID this attribute is attached to.", "format": "uuid", "nullable": true }, "title": { "type": "string", "description": "Optional title/display text (for link attributes, this is the link text).", "nullable": true }, "value": { "maxLength": 255, "type": "string", "description": "The attribute value.", "nullable": true }, "createdAt": { "type": "string", "description": "Timestamp when created.", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "description": "Timestamp when updated.", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "The value of the attribute added for an entity (response without group details)" }, "EntityAttributeUpdateRequestDto": { "type": "object", "properties": { "value": { "maxLength": 255, "type": "string", "description": "The value to set", "nullable": true }, "title": { "maxLength": 255, "type": "string", "description": "Optional title/display text (for link attributes, this is the link text)", "nullable": true } }, "additionalProperties": false, "description": "Request DTO for updating an entity attribute.\r\nOnly value and title can be updated." }, "EntityAttributeValueDto": { "type": "object", "properties": { "attributeId": { "type": "string", "description": "The ID of the attribute definition", "format": "uuid", "nullable": true }, "attributeGroupName": { "type": "string", "description": "The attribute group name (must be used with attributeName)", "nullable": true }, "attributeName": { "type": "string", "description": "The attribute name within the group (must be used with attributeGroupName)", "nullable": true }, "value": { "type": "string", "description": "The value to set", "nullable": true }, "title": { "type": "string", "description": "Optional title/display text (for link attributes, this is the link text)", "nullable": true } }, "additionalProperties": false, "description": "Represents an attribute value to set on an entity. Use either attributeId OR (attributeGroupName + attributeName)." }, "EntityType": { "enum": [ "Conversations", "Contacts", "Projects" ], "type": "string" }, "FieldValidatorDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "nullable": true }, "errorMessageTemplate": { "type": "string", "nullable": true }, "customValidator": { "type": "string", "nullable": true }, "value": { "type": "string", "nullable": true } }, "additionalProperties": false }, "FileMetadataDto": { "type": "object", "properties": { "fileName": { "type": "string", "description": "Original filename including extension", "nullable": true }, "contentType": { "type": "string", "description": "MIME type of the file (e.g., image/jpeg, application/pdf, video/mp4)", "nullable": true } }, "additionalProperties": false, "description": "Represents metadata for a file to be uploaded" }, "FileUploadResponseDto": { "type": "object", "properties": { "conversationId": { "type": "string", "description": "The conversation ID where files will be uploaded", "format": "uuid" }, "totalFiles": { "type": "integer", "description": "Total number of files requested", "format": "int32" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/FileUploadResultDto" }, "description": "Presigned URL results for each file", "nullable": true } }, "additionalProperties": false, "description": "Response containing presigned URLs for uploading files to LiveSwitch Contact" }, "FileUploadResultDto": { "type": "object", "properties": { "fileName": { "type": "string", "description": "Original filename", "nullable": true }, "errorMessage": { "type": "string", "description": "Error message if presigned URL generation failed", "nullable": true }, "presignedUrl": { "type": "string", "description": "Presigned URL for uploading the file to S3", "nullable": true }, "expiresIn": { "type": "integer", "description": "Number of seconds until the presigned URL expires", "format": "int32", "nullable": true }, "documentType": { "$ref": "#/components/schemas/DocumentType" } }, "additionalProperties": false, "description": "Represents the result of requesting a presigned URL for file upload" }, "FormDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "headline": { "type": "string", "nullable": true }, "isDefault": { "type": "boolean" }, "style": { "nullable": true }, "version": { "type": "integer", "format": "int32", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FormFieldDto" }, "nullable": true } }, "additionalProperties": false }, "FormFieldDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "placeholder": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/FormFieldOptionDto" }, "nullable": true }, "order": { "type": "integer", "format": "int32" }, "canBeDeleted": { "type": "boolean" }, "validators": { "type": "array", "items": { "$ref": "#/components/schemas/FieldValidatorDto" }, "nullable": true } }, "additionalProperties": false }, "FormFieldOptionDto": { "type": "object", "properties": { "label": { "type": "string", "nullable": true }, "value": { "type": "string", "nullable": true } }, "additionalProperties": false }, "FormSubmissionFieldResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fieldId": { "type": "string", "format": "uuid" }, "value": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "formField": { "$ref": "#/components/schemas/FormSubmissionFormFieldDto" } }, "additionalProperties": false }, "FormSubmissionFormFieldDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true } }, "additionalProperties": false }, "FormSubmissionResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "formId": { "type": "string", "format": "uuid" }, "contactId": { "type": "string", "format": "uuid" }, "conversationId": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true }, "formSubmissionFields": { "type": "array", "items": { "$ref": "#/components/schemas/FormSubmissionFieldResponseDto" }, "nullable": true } }, "additionalProperties": false }, "GuidedInstructionDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "showInRequest": { "type": "boolean" }, "showInRecording": { "type": "boolean" }, "showInPhotos": { "type": "boolean" }, "showInForms": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/GuidedInstructionItemDto" }, "nullable": true } }, "additionalProperties": false }, "GuidedInstructionItemDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "instructionId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "nullable": true }, "order": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "MeDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "organizationName": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true } }, "additionalProperties": false }, "OrganizationSettingsDto": { "type": "object", "properties": { "defaultCountryCode": { "type": "string", "nullable": true }, "autoStartRecordings": { "type": "boolean" }, "isTestAccount": { "type": "boolean" }, "isSmsEnabled": { "type": "boolean" } }, "additionalProperties": false }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } }, "additionalProperties": { } }, "ProjectCreateRequestDto": { "required": [ "name" ], "type": "object", "properties": { "name": { "minLength": 1, "type": "string", "description": "The name of the project" }, "externalId": { "type": "string", "description": "External identifier for the project used for integration purposes", "nullable": true }, "status": { "$ref": "#/components/schemas/ProjectStatus" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional. Array of tag names to assign to the project. Tags will be auto-created if they don't exist.", "nullable": true }, "address": { "type": "string", "description": "Optional. Human-readable address for the project location (e.g., \"1600 Amphitheatre Parkway, Mountain View, CA\").", "nullable": true }, "contactIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional. Array of contact IDs to associate with the project.\r\nContacts must belong to the same organization as the project.", "nullable": true }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/EntityAttributeValueDto" }, "description": "Optional attributes to set on the project. Use either attributeId or attributeGroupName+attributeName.", "nullable": true } }, "additionalProperties": false }, "ProjectDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the Project", "format": "uuid" }, "name": { "type": "string", "description": "The name of the project", "nullable": true }, "externalId": { "type": "string", "description": "External identifier for the project used for integration purposes", "nullable": true }, "organizationId": { "type": "string", "description": "The OrganizationID that owns this Project", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "description": "The date and time the project was created", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date and time the project was last updated", "format": "date-time" }, "status": { "$ref": "#/components/schemas/ProjectStatus" }, "projectUrl": { "type": "string", "description": "The URL that an authenticated user can use to access the project", "nullable": true }, "projectEmbeddedUrl": { "type": "string", "description": "The URL that an authenticated user can use to access the project without header/nav bar", "nullable": true }, "projectShareUrl": { "type": "string", "description": "The URL that allows public access to the project", "nullable": true }, "projectEmbeddedShareUrl": { "type": "string", "description": "The URL that allows public access to the project without header/nav bar", "nullable": true }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagDto" }, "description": "Tags assigned to this project", "nullable": true }, "address": { "type": "string", "description": "Address associated with this project", "nullable": true }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactDto" }, "description": "Contacts associated with this project", "nullable": true }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/EntityAttributeResponseDto" }, "description": "Attributes assigned to this project", "nullable": true } }, "additionalProperties": false }, "ProjectFileUploadRequestDto": { "type": "object", "properties": { "fileMetadata": { "type": "array", "items": { "$ref": "#/components/schemas/FileMetadataDto" }, "description": "Metadata for the files to upload", "nullable": true }, "conversationName": { "type": "string", "description": "Optional name for the conversation that will be created. Defaults to 'Files Upload'.", "nullable": true }, "contactId": { "type": "string", "description": "Optional contact/customer ID to associate with the conversation", "format": "uuid", "nullable": true } }, "additionalProperties": false, "description": "Request for uploading files to a project" }, "ProjectListDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the Project", "format": "uuid" }, "name": { "type": "string", "description": "The name of the project", "nullable": true }, "externalId": { "type": "string", "description": "External identifier for the project used for integration purposes", "nullable": true }, "organizationId": { "type": "string", "description": "The OrganizationID that owns this Project", "format": "uuid", "nullable": true }, "createdAt": { "type": "string", "description": "The date and time the project was created", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date and time the project was last updated", "format": "date-time" }, "status": { "$ref": "#/components/schemas/ProjectStatus" }, "projectUrl": { "type": "string", "description": "The URL that an authenticated user can use to access the project", "nullable": true }, "projectEmbeddedUrl": { "type": "string", "description": "The URL that an authenticated user can use to access the project without header/nav bar", "nullable": true }, "projectShareUrl": { "type": "string", "description": "The URL that allows public access to the project", "nullable": true }, "projectEmbeddedShareUrl": { "type": "string", "description": "The URL that allows public access to the project without header/nav bar", "nullable": true }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagDto" }, "description": "Tags assigned to this project", "nullable": true }, "address": { "type": "string", "description": "Address associated with this project", "nullable": true }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactDto" }, "description": "Contacts associated with this project", "nullable": true } }, "additionalProperties": false, "description": "Project list item (without attributes and contacts for performance)" }, "ProjectStatus": { "enum": [ "NotStarted", "InProgress", "Completed" ], "type": "string" }, "ProjectUpdateRequestDto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the project", "nullable": true }, "externalId": { "type": "string", "description": "External identifier for the project used for integration purposes", "nullable": true }, "status": { "$ref": "#/components/schemas/ProjectStatus" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional. Array of tag names to assign to the project. Tags will be auto-created if they don't exist. If provided, replaces all existing tags.", "nullable": true }, "address": { "type": "string", "description": "Optional. Human-readable address for the project location (e.g., \"1600 Amphitheatre Parkway, Mountain View, CA\").", "nullable": true }, "contactIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Optional. Array of contact IDs to associate with the project.\r\nIf provided, replaces all existing contact associations.\r\nContacts must belong to the same organization as the project.", "nullable": true } }, "additionalProperties": false }, "RecordingDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Refers to the unique identifier for a recording.", "format": "uuid" }, "publicUrl": { "type": "string", "description": "Refers to the public url that can access the recording without being logged into LiveSwitch Contact. Access can be removed if requested.", "nullable": true }, "thumbnailUrl": { "type": "string", "description": "Refers to the public url that can access the recording's thumbnail without being logged into LiveSwitch Contact. Access can be removed if requested.", "nullable": true }, "conversationId": { "type": "string", "description": "Refers to the session id in LiveSwitch Contact.", "format": "uuid", "nullable": true }, "projectId": { "type": "string", "description": "Refers to the project id in LiveSwitch Contact.", "format": "uuid", "nullable": true }, "organizationId": { "type": "string", "description": "Refers to the organization id in LiveSwitch Contact.", "format": "uuid", "nullable": true }, "externalAccessAllowed": { "type": "boolean", "description": "Refers to if the record can be accessed by the public url." }, "recordingType": { "$ref": "#/components/schemas/ConversationType" }, "recordingStatus": { "$ref": "#/components/schemas/RecordingStatus" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagDto" }, "description": "Tags assigned to this recording", "nullable": true }, "createdAt": { "type": "string", "description": "The date and time the recording was created", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date and time the recording was last updated", "format": "date-time", "nullable": true } }, "additionalProperties": false, "description": "Refers to a recording record in LiveSwitch Contact. Could be a live call, a self recording or a requested recording." }, "RecordingStatus": { "enum": [ "Pending", "InProgress", "Completed", "Failed", "Processing" ], "type": "string" }, "ShareSparkResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The Spark run ID that was shared.", "nullable": true }, "shareUrl": { "type": "string", "description": "Public URL where anyone can view this Spark report without authentication.\r\nStable across repeated share calls for the same Spark.", "nullable": true } }, "additionalProperties": false, "description": "Response for enabling public sharing on a Spark report." }, "SparkCategoryDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this category.", "format": "uuid" }, "name": { "type": "string", "description": "Display name of the category.", "nullable": true }, "description": { "type": "string", "description": "Optional description of the category.", "nullable": true } }, "additionalProperties": false }, "SparkDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this spark run.", "nullable": true }, "sparkTemplateId": { "type": "string", "description": "The ID of the Spark template that was run.", "nullable": true }, "status": { "type": "string", "description": "Current status: `queued`, `running`, `completed`, `failed`, or `cancelled`.", "nullable": true }, "createdAt": { "type": "string", "description": "When the spark run was created.", "format": "date-time" }, "shareUrl": { "type": "string", "description": "Public share URL for this spark report. Non-null only when sharing has been enabled on this analysis in Scribe.", "nullable": true } }, "additionalProperties": false, "description": "Represents a Spark run (queued, running, completed, or failed)." }, "SparkListResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SparkDto" }, "nullable": true }, "total": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "SparkTaskDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Internal Scribe task identifier for this task. This is exposed for compatibility and diagnostics;\r\ncreate requests should use `tasks[].codeName`.", "nullable": true }, "codeName": { "type": "string", "description": "Stable code name for this task. Use this as `tasks[].codeName` in the create request.", "nullable": true }, "name": { "type": "string", "description": "Display name of the task.", "nullable": true }, "type": { "type": "string", "description": "Task type. Either `user-input` (requires values in `tasks[].inputs`) or\r\n`platform` (requires a connected platform integration).", "nullable": true }, "platformCodeName": { "type": "string", "description": "For `platform` tasks: the stable platform code name (e.g. `hubspot` or\r\n`chariot-chariot`). Null for `user-input` tasks.", "nullable": true }, "platformName": { "type": "string", "description": "For `platform` tasks: the name of the required platform (e.g. `HubSpot`).\r\nNull for `user-input` tasks.", "nullable": true }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/SparkTaskInputDto" }, "description": "For `user-input` tasks: the schema of inputs required. Use `key` as the field\r\nname in `tasks[].inputs` when running a spark. Null for `platform` tasks.", "nullable": true }, "isRequired": { "type": "boolean", "description": "True when this task requires input or is required by the template. Spark create requests run\r\nthe template's default task selection; `tasks[]` is used to supply input values." } }, "additionalProperties": false }, "SparkTaskInputDto": { "type": "object", "properties": { "key": { "type": "string", "description": "The input field key. Use as a key in `tasks[].inputs` when running a spark.", "nullable": true }, "label": { "type": "string", "description": "Human-readable label for this input field.", "nullable": true }, "type": { "type": "string", "description": "The expected value type. One of: `text`, `textarea`, `number`, `email`, `phone`,\r\n`url`, `date`, `datetime`, `time`, `checkbox`, `select`, `radio`,\r\n`multiselect`, `autocomplete`, `multi_autocomplete`.\r\n\n`date`/`datetime` take an ISO 8601 string (e.g. `2026-10-01`, `2026-10-01T14:30:00Z`).\r\n`checkbox` is a yes/no answer: send `true` or `false`.\r\n`email`, `phone`, `url` and `time` are accepted as text; their format is not checked.\r\n\n\r\nSelection types take one of the valid answers: from `options` for a fixed list, or from the options\r\nlookup when `lookup` is set. `multiselect` and `multi_autocomplete` take a list.\r\n", "nullable": true }, "required": { "type": "boolean", "description": "Whether this input must be provided. When true, omitting this key from `tasks[].inputs`\r\nwill result in a validation error." }, "description": { "type": "string", "description": "Optional helper text describing what value to provide.", "nullable": true }, "multiple": { "type": "boolean", "description": "True when this input takes a list of answers (`multiselect`, `multi_autocomplete`)." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/SparkTaskInputOptionDto" }, "description": "The fixed list of valid answers for a dropdown or radio input. Send one option's `value`\r\n(or a list of them when `multiple` is true). Null when the input is free-form or when its answers\r\ncome from a connected platform — `options` and `lookup` are never both set.", "nullable": true }, "lookup": { "$ref": "#/components/schemas/SparkTaskInputLookupDto" }, "validation": { "$ref": "#/components/schemas/SparkTaskInputValidationDto" }, "default": { "description": "The value used when this input is left out, if the template defines one.", "nullable": true } }, "additionalProperties": false }, "SparkTaskInputLookupDto": { "type": "object", "properties": { "hasOptions": { "type": "boolean", "description": "True: valid answers can be fetched from the options lookup endpoint." }, "searchable": { "type": "boolean", "description": "True when the lookup takes a `search` term (e.g. a name, phone number or email). False when it returns\r\na whole list, usually narrowed by the fields in `dependsOn`." }, "displayLabelRequired": { "type": "boolean", "description": "True when you should send the picked option's label as `displayLabel` alongside its `value`:\r\nthe platform is searched with that label to confirm the value. Send the option object exactly as the lookup\r\nreturned it and this is taken care of." }, "platformName": { "type": "string", "description": "The platform the answers come from.", "nullable": true }, "dependsOn": { "type": "array", "items": { "type": "string" }, "description": "Keys of inputs in the same task that must be answered first. Pass each one's value to the options lookup as\r\n`parent[key]=value`.", "nullable": true } }, "additionalProperties": false }, "SparkTaskInputOptionDto": { "type": "object", "properties": { "value": { "description": "The value to send in `tasks[].inputs`." }, "label": { "type": "string", "description": "What a person sees for this option. Send it back as `displayLabel` alongside `value`.", "nullable": true }, "search": { "type": "string", "description": "The search term that found this option, on options from the options lookup. Send it back with the option:\r\nvalidation searches the platform with it again to confirm your answer. Omitted for fixed-list options.", "nullable": true } }, "additionalProperties": false }, "SparkTaskInputOptionsResponseDto": { "type": "object", "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/SparkTaskInputOptionDto" }, "description": "The valid answers. Send the one you pick back in `tasks[].inputs` as\r\n`{ \"value\": ..., \"displayLabel\": ... }` (its `label` is the display label).", "nullable": true } }, "additionalProperties": false }, "SparkTaskInputRequestDto": { "type": "object", "properties": { "codeName": { "type": "string", "description": "Stable task code name from GET /v1/spark-templates (tasks[].codeName).", "nullable": true, "example": "identify_opportunity_id" }, "inputs": { "type": "object", "additionalProperties": { }, "description": "Input values for this task. Required when the task has required input fields.\r\nKeys are input field keys from tasks[].inputs[].key.\r\nValues are raw scalar values (string, number, or boolean), or a list of them for an input whose\r\n`multiple` is true.\r\nFor a selection input, send back the option you picked exactly as the options lookup returned it:\r\n`{ \"value\": \"8f2c1a94-...\", \"label\": \"John Smith\", \"search\": \"john\" }` (`displayLabel` is accepted for\r\n`label`), or a list of them for a multi-value input. `search` is what validation searches the platform\r\nwith to confirm the value. For a fixed-list dropdown or radio a plain value is enough — its label is filled in for you.\r\nA plain value for a connected input only works where the value is itself the search key (e.g. a job number).", "nullable": true, "example": { "customer_name": { "value": "086d9a35-f81d-413d-8188-b3e000bf0775", "displayLabel": "Peter Arroyo" }, "quote_number": { "value": "89198382-ca9b-426f-bf71-b433015cf4aa", "displayLabel": "Quote Number 1245" }, "rooms": [ { "value": "kitchen", "displayLabel": "Kitchen" }, { "value": "garage", "displayLabel": "Garage" } ], "job_number": "123456" } } }, "additionalProperties": false, "description": "Input values for one task in a Spark report." }, "SparkTaskInputValidationDto": { "type": "object", "properties": { "required": { "type": "boolean", "description": "Whether this input must be provided. Same as the input's `required`." }, "minLength": { "type": "integer", "description": "Minimum length of a `text`/`textarea` answer.", "format": "int32", "nullable": true }, "maxLength": { "type": "integer", "description": "Maximum length of a `text`/`textarea` answer.", "format": "int32", "nullable": true }, "min": { "type": "number", "description": "Smallest allowed number. Advisory: not currently enforced.", "format": "double", "nullable": true }, "max": { "type": "number", "description": "Largest allowed number. Advisory: not currently enforced.", "format": "double", "nullable": true }, "pattern": { "type": "string", "description": "Regular expression a `text`/`textarea` answer must match.", "nullable": true }, "patternMessage": { "type": "string", "description": "The error shown when `pattern` does not match.", "nullable": true } }, "additionalProperties": false }, "SparkTemplateDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this Spark template.", "format": "uuid" }, "name": { "type": "string", "description": "Display name of the Spark template.", "nullable": true }, "description": { "type": "string", "description": "Optional description of what this Spark template does.", "nullable": true }, "category": { "$ref": "#/components/schemas/SparkCategoryDto" }, "requiresUserInput": { "type": "boolean", "description": "True when this Spark template has at least one `user-input` task. When true, you must\r\nsupply task inputs via `tasks[].inputs` when running the spark." }, "requiresPlatformLogin": { "type": "boolean", "description": "True when this Spark template requires a connected platform (e.g. HubSpot) to run." }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/SparkTaskDto" }, "description": "The actionable tasks in this Spark template. Only `user-input` and `platform` task\r\ntypes are included — internal processing tasks are omitted.", "nullable": true }, "createdAt": { "type": "string", "description": "The date and time this Spark template was created.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "The date and time this Spark template was last updated.", "format": "date-time" } }, "additionalProperties": false }, "SparkTemplatesResponseDto": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SparkTemplateDto" }, "description": "The list of installed Spark templates available to this organization.", "nullable": true }, "nextCursor": { "type": "string", "description": "Cursor to pass as `cursor` in the next request to retrieve the next page.\r\nNull when there are no more results.", "nullable": true } }, "additionalProperties": false }, "TagCreateRequestDto": { "required": [ "name" ], "type": "object", "properties": { "name": { "minLength": 1, "type": "string", "description": "The name of the tag." }, "hexColor": { "type": "string", "description": "The hex-based color value for display. Optional field.", "nullable": true } }, "additionalProperties": false }, "TagDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the Tag.", "format": "uuid" }, "name": { "type": "string", "description": "The string value for display.", "nullable": true }, "hexColor": { "type": "string", "description": "The hex-based color value for display. Useful if you want to match the color in your application to LiveSwitch.", "nullable": true } }, "additionalProperties": false }, "TagUpdateRequestDto": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the tag.", "nullable": true }, "hexColor": { "type": "string", "description": "The hex-based color value for display. Optional field.", "nullable": true } }, "additionalProperties": false, "description": "DTO for tag update request" }, "TokenResponseType": { "enum": [ "Token", "Code" ], "type": "string", "description": "The type of auth token to create" }, "UpdateOrganizationSmsSettingsDto": { "required": [ "isSmsEnabled" ], "type": "object", "properties": { "isSmsEnabled": { "type": "boolean" } }, "additionalProperties": false }, "ValidateSparkInputsRequestDto": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/SparkTaskInputRequestDto" }, "description": "Input values for tasks in the Spark template, exactly as for running a Spark.\r\nIdentify each task with `tasks[].codeName` from GET /v1/spark-templates.", "nullable": true } }, "additionalProperties": false }, "ValidateSparkInputsResponseDto": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Always true: invalid inputs get a 422 with the errors instead." }, "validationToken": { "type": "string", "description": "Send this as `validationToken` when running the Spark (POST /v1/conversations/{id}/sparks or\r\n/v1/projects/{id}/sparks) to run with these validated inputs. It carries the inputs, so do not send\r\n`tasks` with it.", "nullable": true }, "validatedAt": { "type": "string", "description": "When the inputs were validated.", "format": "date-time" }, "expiresAt": { "type": "string", "description": "When the token stops being accepted (24 hours after validation). It also stops being accepted if the\r\nSpark template changes before then.", "format": "date-time" } }, "additionalProperties": false }, "WebhookCreateRequestDto": { "type": "object", "properties": { "eventType": { "$ref": "#/components/schemas/WebhookEventType" }, "name": { "type": "string", "description": "A readable name for a user to identify a webhook", "nullable": true }, "description": { "type": "string", "description": "A description of what the purpose of this webhook is", "nullable": true }, "url": { "type": "string", "description": "The URL to be invoked", "nullable": true }, "entityName": { "$ref": "#/components/schemas/WebhookEntityType" }, "appId": { "type": "string", "description": "The app id, if specified. This is useful for linking directly to your application, so you can identify your requests uniquely", "nullable": true }, "enabled": { "type": "boolean", "description": "Whether or not this webhook will fire.", "nullable": true } }, "additionalProperties": false }, "WebhookDto": { "type": "object", "properties": { "eventType": { "$ref": "#/components/schemas/WebhookEventType" }, "name": { "type": "string", "description": "A readable name for a user to identify a webhook", "nullable": true }, "description": { "type": "string", "description": "A description of what the purpose of this webhook is", "nullable": true }, "url": { "type": "string", "description": "The URL to be invoked", "nullable": true }, "entityName": { "$ref": "#/components/schemas/WebhookEntityType" }, "appId": { "type": "string", "description": "The app id, if specified. This is useful for linking directly to your application, so you can identify your requests uniquely", "nullable": true }, "enabled": { "type": "boolean", "description": "Whether or not this webhook will fire.", "nullable": true }, "id": { "type": "string", "format": "uuid", "nullable": true } }, "additionalProperties": false }, "WebhookEntityType": { "enum": [ "Conversations", "Contacts", "AppInstallations", "Recordings", "Documents", "Accounts" ], "type": "string" }, "WebhookEventType": { "enum": [ "Create", "Update", "Delete" ], "type": "string" }, "WebhookUpdateRequestDto": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of this webhook", "format": "uuid" }, "eventType": { "$ref": "#/components/schemas/WebhookEventType" }, "name": { "type": "string", "description": "A readable name for a user to identify a webhook", "nullable": true }, "description": { "type": "string", "description": "A description of what the purpose of this webhook is", "nullable": true }, "url": { "type": "string", "description": "The URL to be invoked", "nullable": true }, "entityName": { "$ref": "#/components/schemas/WebhookEntityType" }, "appId": { "type": "string", "description": "The app id, if specified. This is useful for linking directly to your application, so you can identify your requests uniquely", "nullable": true }, "enabled": { "type": "boolean", "description": "Whether or not this webhook will fire.", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth2 authentication using Auth0 Implicit flow", "flows": { "implicit": { "authorizationUrl": "https://id.liveswitch.com/authorize", "scopes": { "openid": "OpenID Connect scope", "profile": "Access to user profile", "email": "Access to user email", "me": "Access to user information", "contacts": "Read access to contacts", "contacts.write": "Write access to contacts", "conversations": "Read access to conversations", "conversations.write": "Write access to conversations", "organizations": "Read access to organizations", "webhooks": "Read access to webhooks", "webhooks.write": "Write access to webhooks", "applications": "Read access to applications", "applications.write": "Write access to applications", "forms": "Read access to forms", "projects": "Read access to projects", "projects.write": "Write access to projects", "recordings": "Read access to recordings", "documents": "Read access to documents", "accounts": "Read access to accounts", "guided-instructions": "Read access to guided instructions", "sparks": "Read access to Spark runs", "sparks.write": "Write access to Spark runs", "spark-templates": "Read access to installed Spark templates for the organization", "scribe-templates": "Read access to installed Scribe templates (legacy)" } } } }, "bearer": { "type": "http", "description": "

Please enter a valid token. This shoud NOT include the Bearer: prefix, but just the token itself.

\n
\n

To generate a token from the Swagger UI:

\n

\n 1. Select the 'v1/tokens' endpoint in the Swagger UI
\n 2. Set the 'redirect' setting to false
\n 3. Fill in the values according to your application configuration
\n 4. Click 'Execute'
\n

\n
\n

\n The response from this request will include the URL you need to generate a token. Copy/paste it into a new window and follow the instructions.\n

", "scheme": "bearer", "bearerFormat": "JWT" } } }, "security": [ { "bearer": [ ] } ] }