{ "info": { "title": "telli API", "version": "2.0.0", "description": "telli V2 API" }, "servers": [ { "url": "https://api.telli.com", "description": "prod" } ], "security": [ { "BearerAuth": [] } ], "openapi": "3.1.1", "paths": { "/v2/account/health": { "get": { "operationId": "accounts.getAccountHealth", "summary": "Get account health", "description": "Returns the current system availability for the authenticated account.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "AccountHealth" }, "status": { "enum": [ "operational", "degraded" ] } }, "required": [ "id", "type", "status" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "ACCOUNT_NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "Account not found" }, "data": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" } }, "required": [ "accountId" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v2/agents": { "get": { "operationId": "agents.listAgents", "summary": "List agents", "description": "Returns a paginated list of agents for the authenticated account.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 50 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "const": "AgentCollection" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "Agent" }, "title": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "language": { "type": "string" } }, "required": [ "id", "type", "title", "createdAt", "language" ] } }, "pageInfo": { "type": "object", "properties": { "hasNextPage": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasNextPage", "nextCursor" ] }, "meta": { "type": "object", "properties": { "limit": { "type": "number" }, "count": { "type": "number" }, "total": { "type": "number" } }, "required": [ "limit", "count", "total" ] } }, "required": [ "type", "data", "pageInfo", "meta" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INVALID_CURSOR" }, "status": { "const": 400 }, "message": { "type": "string", "default": "Invalid pagination cursor" }, "data": { "type": "object", "properties": { "cursor": { "type": "string" } }, "required": [ "cursor" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v2/agents/{id}": { "get": { "operationId": "agents.getAgent", "summary": "Get agent", "description": "Returns a single agent by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "Agent" }, "title": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "language": { "type": "string" } }, "required": [ "id", "type", "title", "createdAt", "language" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "AGENT_NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "Agent not found" }, "data": { "type": "object", "properties": { "agentId": { "type": "string", "format": "uuid" } }, "required": [ "agentId" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v2/properties/contacts": { "get": { "operationId": "contactProperties.listContactProperties", "summary": "List contact properties", "description": "Returns all contact properties for the authenticated account.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "const": "ContactPropertyList" }, "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "const": "ContactProperty" }, "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]*$" }, "dataType": { "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ] }, "source": { "enum": [ "system", "user", "integration" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] }, "description": "Only applicable for select and multi_select data types" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "key", "dataType", "source", "label", "createdAt", "updatedAt" ] } } }, "required": [ "type", "data" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "operationId": "contactProperties.createContactProperty", "summary": "Create contact property", "description": "Creates a new contact property for the authenticated account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]*$" }, "dataType": { "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ] }, "label": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] }, "description": "Only applicable for select and multi_select data types" } }, "required": [ "key", "dataType", "label" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "const": "ContactProperty" }, "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]*$" }, "dataType": { "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ] }, "source": { "enum": [ "system", "user", "integration" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] }, "description": "Only applicable for select and multi_select data types" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "key", "dataType", "source", "label", "createdAt", "updatedAt" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "DUPLICATE_OPTION_VALUE" }, "status": { "const": 400 }, "message": { "type": "string", "default": "Option values must be unique" }, "data": { "type": "object", "properties": { "duplicateValues": { "type": "array", "items": { "type": "string" } } }, "required": [ "duplicateValues" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PROPERTY_LIMIT_EXCEEDED" }, "status": { "const": 403 }, "message": { "type": "string", "default": "You've reached the maximum of 150 contact properties. Delete unused properties or contact us to add more." }, "data": { "type": "object", "properties": { "limit": { "type": "number" }, "current": { "type": "number" } }, "required": [ "limit", "current" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "DUPLICATE_PROPERTY_KEY" }, "status": { "const": 409 }, "message": { "type": "string", "default": "Property with key already exists" }, "data": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "KEY_CONFLICTS_WITH_SYSTEM" }, "status": { "const": 409 }, "message": { "type": "string", "default": "Key conflicts with a system property" }, "data": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v2/properties/contacts/{key}": { "get": { "operationId": "contactProperties.getContactProperty", "summary": "Get contact property", "description": "Returns a single contact property by key.", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]*$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "const": "ContactProperty" }, "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]*$" }, "dataType": { "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ] }, "source": { "enum": [ "system", "user", "integration" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] }, "description": "Only applicable for select and multi_select data types" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "key", "dataType", "source", "label", "createdAt", "updatedAt" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PROPERTY_NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "Property not found" }, "data": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "operationId": "contactProperties.updateContactProperty", "summary": "Update contact property", "description": "Updates an existing contact property by key.", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]*$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] }, "description": "Only applicable for select and multi_select data types" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "const": "ContactProperty" }, "key": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]*$" }, "dataType": { "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ] }, "source": { "enum": [ "system", "user", "integration" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] }, "description": "Only applicable for select and multi_select data types" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "key", "dataType", "source", "label", "createdAt", "updatedAt" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "ENUM_OPTION_REMOVAL" }, "status": { "const": 400 }, "message": { "type": "string", "default": "Cannot remove existing enum options" }, "data": { "type": "object", "properties": { "removedOptions": { "type": "array", "items": { "type": "string" } } }, "required": [ "removedOptions" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "DUPLICATE_OPTION_VALUE" }, "status": { "const": 400 }, "message": { "type": "string", "default": "Option values must be unique" }, "data": { "type": "object", "properties": { "duplicateValues": { "type": "array", "items": { "type": "string" } } }, "required": [ "duplicateValues" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "403": { "description": "403", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SYSTEM_PROPERTY_IMMUTABLE" }, "status": { "const": 403 }, "message": { "type": "string", "default": "System properties cannot be modified" }, "data": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PROPERTY_NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "Property not found" }, "data": { "type": "object", "properties": { "key": { "type": "string" } }, "required": [ "key" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v2/contacts": { "get": { "operationId": "contacts.listContacts", "summary": "List contacts", "description": "Returns a paginated list of contacts for the authenticated account.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 50 }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "const": "ContactCollection" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "Contact" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "salutation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "timezoneIana": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": {}, "dataType": { "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ] }, "label": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "dataType" ] } } }, "required": [ "id", "type", "externalId", "externalUrl", "salutation", "firstName", "lastName", "phoneNumber", "timezoneIana", "email", "createdAt", "updatedAt", "properties" ] } }, "pageInfo": { "type": "object", "properties": { "hasNextPage": { "type": "boolean" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "hasNextPage", "nextCursor" ] }, "meta": { "type": "object", "properties": { "limit": { "type": "number" }, "count": { "type": "number" }, "total": { "type": "number" } }, "required": [ "limit", "count", "total" ] } }, "required": [ "type", "data", "pageInfo", "meta" ] } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INVALID_CURSOR" }, "status": { "const": 400 }, "message": { "type": "string", "default": "Invalid pagination cursor" }, "data": { "type": "object", "properties": { "cursor": { "type": "string" } }, "required": [ "cursor" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] }, "post": { "operationId": "contacts.createContact", "summary": "Create contact", "description": "Creates a new contact. Properties are validated against the account's property schema.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "externalUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "salutation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstName": { "type": "string", "minLength": 1, "maxLength": 50 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 50 }, "phoneNumber": { "type": "string", "minLength": 1, "maxLength": 20 }, "timezoneIana": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": {} }, "required": [ "key" ] } } }, "required": [ "firstName", "lastName", "phoneNumber" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "Contact" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "salutation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "timezoneIana": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": {}, "dataType": { "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ] }, "label": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "dataType" ] } } }, "required": [ "id", "type", "externalId", "externalUrl", "salutation", "firstName", "lastName", "phoneNumber", "timezoneIana", "email", "createdAt", "updatedAt", "properties" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "DUPLICATE_EXTERNAL_ID" }, "status": { "const": 409 }, "message": { "type": "string", "default": "External ID already exists for this account" }, "data": { "type": "object", "properties": { "externalId": { "type": "string" } }, "required": [ "externalId" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "VALIDATION_ERROR" }, "status": { "const": 422 }, "message": { "type": "string", "default": "Validation failed" }, "data": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } }, "required": [ "code", "message", "path" ] } } }, "required": [ "issues" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v2/contacts/{id}": { "get": { "operationId": "contacts.getContact", "summary": "Get contact", "description": "Returns a single contact by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "Contact" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "salutation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "timezoneIana": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": {}, "dataType": { "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ] }, "label": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "dataType" ] } } }, "required": [ "id", "type", "externalId", "externalUrl", "salutation", "firstName", "lastName", "phoneNumber", "timezoneIana", "email", "createdAt", "updatedAt", "properties" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONTACT_NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "Contact not found" }, "data": { "type": "object", "properties": { "contactId": { "type": "string", "format": "uuid" } }, "required": [ "contactId" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] }, "patch": { "operationId": "contacts.updateContact", "summary": "Update contact", "description": "Updates an existing contact. Properties are merged with existing ones after validation.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "externalUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "salutation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstName": { "type": "string", "minLength": 1, "maxLength": 50 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 50 }, "phoneNumber": { "type": "string", "minLength": 1, "maxLength": 20 }, "timezoneIana": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": {} }, "required": [ "key" ] } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "Contact" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "salutation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "timezoneIana": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": {}, "dataType": { "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ] }, "label": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "dataType" ] } } }, "required": [ "id", "type", "externalId", "externalUrl", "salutation", "firstName", "lastName", "phoneNumber", "timezoneIana", "email", "createdAt", "updatedAt", "properties" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONTACT_NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "Contact not found" }, "data": { "type": "object", "properties": { "contactId": { "type": "string", "format": "uuid" } }, "required": [ "contactId" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "DUPLICATE_EXTERNAL_ID" }, "status": { "const": 409 }, "message": { "type": "string", "default": "External ID already exists for this account" }, "data": { "type": "object", "properties": { "externalId": { "type": "string" } }, "required": [ "externalId" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "VALIDATION_ERROR" }, "status": { "const": 422 }, "message": { "type": "string", "default": "Validation failed" }, "data": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } }, "required": [ "code", "message", "path" ] } } }, "required": [ "issues" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] }, "put": { "operationId": "contacts.replaceContact", "summary": "Replace contact", "description": "Fully replaces an existing contact. All omitted optional fields are reset to their default values (null). Properties are replaced entirely rather than merged.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "default": null }, "externalUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "default": null }, "salutation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null }, "firstName": { "type": "string", "minLength": 1, "maxLength": 50 }, "lastName": { "type": "string", "minLength": 1, "maxLength": 50 }, "phoneNumber": { "type": "string", "minLength": 1, "maxLength": 20 }, "timezoneIana": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null }, "properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": {} }, "required": [ "key" ] }, "default": [] } }, "required": [ "firstName", "lastName", "phoneNumber" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "Contact" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "salutation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "timezoneIana": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": {}, "dataType": { "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ] }, "label": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "dataType" ] } } }, "required": [ "id", "type", "externalId", "externalUrl", "salutation", "firstName", "lastName", "phoneNumber", "timezoneIana", "email", "createdAt", "updatedAt", "properties" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONTACT_NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "Contact not found" }, "data": { "type": "object", "properties": { "contactId": { "type": "string", "format": "uuid" } }, "required": [ "contactId" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "DUPLICATE_EXTERNAL_ID" }, "status": { "const": 409 }, "message": { "type": "string", "default": "External ID already exists for this account" }, "data": { "type": "object", "properties": { "externalId": { "type": "string" } }, "required": [ "externalId" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "422": { "description": "422", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "VALIDATION_ERROR" }, "status": { "const": 422 }, "message": { "type": "string", "default": "Validation failed" }, "data": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } }, "required": [ "code", "message", "path" ] } } }, "required": [ "issues" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "operationId": "contacts.deleteContact", "summary": "Delete contact", "description": "Deletes a contact and anonymizes all personal data.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "not": {} }, { "not": {} } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONTACT_NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "Contact not found" }, "data": { "type": "object", "properties": { "contactId": { "type": "string", "format": "uuid" } }, "required": [ "contactId" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "409": { "description": "409", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONTACT_HAS_PENDING_CALLS" }, "status": { "const": 409 }, "message": { "type": "string", "default": "A call for this contact is still being processed. Please wait for all calls to complete before deleting." }, "data": { "type": "object", "properties": { "contactId": { "type": "string", "format": "uuid" } }, "required": [ "contactId" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONTACT_HAS_ACTIVE_CALLS" }, "status": { "const": 409 }, "message": { "type": "string", "default": "Cannot delete contact: call currently in progress" }, "data": { "type": "object", "properties": { "contactId": { "type": "string", "format": "uuid" } }, "required": [ "contactId" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/v2/external/contacts/{externalId}": { "get": { "operationId": "contacts.getContactByExternalId", "summary": "Get contact by external ID", "description": "Returns a single contact by its external ID.", "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "const": "Contact" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "salutation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "timezoneIana": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": {}, "dataType": { "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ] }, "label": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label" ] } } }, "required": [ "key", "dataType" ] } } }, "required": [ "id", "type", "externalId", "externalUrl", "salutation", "firstName", "lastName", "phoneNumber", "timezoneIana", "email", "createdAt", "updatedAt", "properties" ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "API key is missing or invalid" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "PAYMENT_REQUIRED" }, "status": { "const": 402 }, "message": { "type": "string", "default": "API access requires a paid plan" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "CONTACT_NOT_FOUND_BY_EXTERNAL_ID" }, "status": { "const": 404 }, "message": { "type": "string", "default": "Contact not found" }, "data": { "type": "object", "properties": { "externalId": { "type": "string" } }, "required": [ "externalId" ] } }, "required": [ "defined", "code", "status", "message", "data" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } }, "security": [ { "BearerAuth": [] } ] } } }, "webhooks": { "call_ended": { "post": { "summary": "Call ended", "description": "Sent when a call reaches a terminal state, after post-processing completes. Includes the call outcome, transcript, collected data, and the contact; analysis fields are null when the call did not connect.", "operationId": "call_ended", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "call_ended", "description": "Always `call_ended`." }, "call": { "type": "object", "properties": { "ended_reason": { "type": "string", "enum": [ "agent-ended-call", "agent-forwarded-call", "agent-busy", "agent-did-not-answer", "contact-busy", "contact-ended-call", "contact-did-not-answer", "phone-provider-closed-connection", "other" ], "description": "Who or what ended the call. Always set: `other` covers reasons that do not map to a specific cause." }, "call_id": { "type": "string", "description": "telli identifier of this call." }, "loop_id": { "type": "string", "description": "Identifier of the call loop. Automatic retries within one scheduled sequence share it." }, "attempt": { "type": "number", "description": "Number of calls in the loop when this event was sent, counting from 1." }, "from_number": { "type": "string", "description": "Number the call was placed from, in E.164 format." }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Whether telli placed the call (`outbound`) or received it (`inbound`)." }, "to_number": { "type": "string", "description": "Number the call was placed to, in E.164 format." }, "external_contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your own identifier for the contact, if one was supplied." }, "contact_id": { "type": "string", "description": "telli identifier of the contact on the call." }, "contact_details": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Free-form dynamic variables stored on the contact when the event was sent. Empty or null if none." }, "contact_properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable key of the contact property, as defined in Settings > Contact properties." }, "value": { "description": "Value stored for this contact. The JSON type follows `dataType`." }, "dataType": { "type": "string", "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ], "description": "Data type of the property." }, "label": { "description": "Human-readable label of the property.", "type": "string" }, "options": { "description": "Allowed options. Present only for `select` and `multi_select` properties.", "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Stored value of the option." }, "label": { "type": "string", "description": "Human-readable label of the option." }, "description": { "description": "Optional longer description of the option.", "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "key", "value", "dataType" ], "additionalProperties": false }, "description": "Structured contact properties when the event was sent." }, "agent_id": { "type": "string", "description": "Identifier of the agent that handled the call." }, "triggered_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Unix timestamp in milliseconds of when the call was triggered." }, "triggered_at_iso": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 form of `triggered_at`." }, "started_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Unix timestamp in milliseconds of when the call connected, or null if it never connected." }, "started_at_iso": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 form of `started_at`." }, "ended_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Unix timestamp in milliseconds of when the call ended." }, "ended_at_iso": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 form of `ended_at`." }, "call_length_min": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Call duration rounded up to whole minutes. Use `call_length_sec` for exact duration." }, "call_length_sec": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Call duration in whole seconds." }, "call_status": { "type": "string", "deprecated": true, "description": "Deprecated. Use `state`, `status`, and `follow_up` instead. One of `INITIATED`, `RINGING`, `IN_PROGRESS`, `COMPLETED`, `ANSWERED`, `NOT_REACHED`, `VOICEMAIL`, or `ERROR`." }, "state": { "type": "string", "enum": [ "queued", "ringing", "in_progress", "processing", "ended" ], "description": "Where the call is in its lifecycle: `queued`, `ringing`, `in_progress`, `processing`, or `ended`." }, "status": { "anyOf": [ { "type": "string", "enum": [ "connected", "not_connected", "voicemail", "failed" ] }, { "type": "null" } ], "description": "What happened once the call ended: `connected`, `not_connected`, `voicemail`, or `failed`. Null until the call has ended." }, "follow_up": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "agent_follow_up", "description": "Always `agent_follow_up`." }, "scheduled_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "ISO 8601 timestamp of when the follow-up call is scheduled." } }, "required": [ "type", "scheduled_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "The follow-up telli scheduled from this call, or null if none was scheduled." }, "transcript": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Plain-text transcript of the call, or null if unavailable." }, "transcriptObject": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "role": { "type": "string", "const": "user" }, "content": { "type": "string" } }, "required": [ "role", "content" ], "additionalProperties": false }, { "type": "object", "properties": { "role": { "type": "string", "const": "agent" }, "toolActivity": { "type": "string" }, "type": { "type": "string", "const": "function_call" }, "toolParameters": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "role", "toolActivity" ], "additionalProperties": false }, { "type": "object", "properties": { "role": { "type": "string", "const": "agent" }, "type": { "type": "string", "const": "function_call_output" }, "content": { "type": "string" }, "callId": { "type": "string" }, "isError": { "type": "boolean" }, "toolName": { "type": "string" } }, "required": [ "role", "type", "content", "callId", "isError" ], "additionalProperties": false }, { "type": "object", "properties": { "role": { "type": "string", "const": "agent" }, "content": { "type": "string" } }, "required": [ "role", "content" ], "additionalProperties": false } ] } }, { "type": "null" } ], "description": "Turn-by-turn transcript. Contact turns carry `content`; agent turns carry either `content` or a tool activity. Null if unavailable." }, "call_analysis": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "boolean", "description": "Whether the analysis field was detected in the call." }, "details": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Supporting detail extracted from the transcript, or null when the analysis produced none." } }, "required": [ "value", "details" ], "additionalProperties": false }, { "type": "object", "properties": { "value": { "type": "boolean", "description": "Whether the analysis field was detected in the call." } }, "required": [ "value" ], "additionalProperties": false } ] }, "description": "System-provided call analysis, keyed by field name. Each entry always has a boolean `value`; fields that support supporting detail also have `details`. Note this shape differs from `call_outcome`." }, { "type": "null" } ], "description": "System-provided call analysis, or null if the call was not analyzed." }, "call_outcome": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "boolean" }, { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "reason": { "type": "string" }, "fieldSchema": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "const": "string" }, { "type": "array", "prefixItems": [ { "type": "string", "const": "string" }, { "type": "string", "const": "null" } ] }, { "type": "string", "const": "number" }, { "type": "array", "prefixItems": [ { "type": "string", "const": "number" }, { "type": "string", "const": "null" } ] }, { "type": "string", "const": "boolean" }, { "type": "array", "prefixItems": [ { "type": "string", "const": "boolean" }, { "type": "string", "const": "null" } ] }, { "type": "string", "const": "array" }, { "type": "array", "prefixItems": [ { "type": "string", "const": "array" }, { "type": "string", "const": "null" } ] } ] }, "enum": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] } }, "items": { "type": "object", "properties": { "type": { "type": "string", "const": "string" }, "enum": { "type": "array", "items": { "type": "string" } } }, "required": [ "type" ], "additionalProperties": false }, "uniqueItems": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": false }, "error": { "type": "string" } }, "required": [ "value", "fieldSchema" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Custom call analysis fields you configured in telli, keyed by field name. Note this shape differs from `call_analysis`." }, "collected_data": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "in_progress", "confirmed", "declined", "error" ], "description": "Outcome of the Collect Data task: `confirmed` when the caller confirmed the value, `declined` when they refused, `error` when collection failed, `in_progress` when the call ended mid-collection." }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The collected value, or null when nothing was collected." }, "latitude": { "description": "Latitude returned by address validation. Present when validated coordinates are available for an `address` task.", "type": "number" }, "longitude": { "description": "Longitude returned by address validation. Present when validated coordinates are available for an `address` task.", "type": "number" } }, "required": [ "status", "value" ], "additionalProperties": false }, "description": "Data actively collected and confirmed with the caller, keyed by Collect Data task name." }, { "type": "null" } ], "description": "Results of the agent's Collect Data tasks. Empty or null when none were triggered." }, "booked_slot_for": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the appointment booked during the call, or null if none was booked." }, "recording_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "URL of the call recording, or null when recording is disabled or unavailable." }, "sip_status_code": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "SIP response code returned by the phone network, for example 200." }, "sip_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable SIP status, for example `OK`." }, "transfer": { "anyOf": [ { "type": "object", "properties": { "destination": { "type": "string", "description": "Transfer target the call was transferred to: an E.164 phone number or a tel:/sip: URI." }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of when the call was transferred." } }, "required": [ "destination", "completed_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "Transfer details when the call was transferred, or null if the call was not transferred." } }, "required": [ "ended_reason", "call_id", "loop_id", "attempt", "from_number", "direction", "to_number", "external_contact_id", "contact_id", "contact_details", "contact_properties", "agent_id", "triggered_at", "triggered_at_iso", "started_at", "started_at_iso", "ended_at", "ended_at_iso", "call_length_min", "call_length_sec", "call_status", "state", "status", "follow_up", "transcript", "transcriptObject", "call_analysis", "call_outcome", "collected_data", "booked_slot_for", "recording_url", "sip_status_code", "sip_status", "transfer" ], "additionalProperties": false }, "contact": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "telli identifier of the contact." }, "external_contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your own identifier for the contact, if one was supplied." }, "external_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Link back to the contact in your own system, if one was supplied." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp of when the contact was created in telli." }, "gender": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Gender recorded for the contact, or null if unknown." }, "first_name": { "type": "string", "description": "First name of the contact." }, "last_name": { "type": "string", "description": "Last name of the contact." }, "phone_number": { "type": "string", "description": "Phone number of the contact in E.164 format." }, "in_call_since": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of when the contact's current call started, or null if not on a call." }, "reached_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of when the contact was first reached, or null if never reached." }, "contact_details": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Free-form dynamic variables stored on the contact. Empty or null if none." }, "call_attempts": { "type": "number", "description": "Number of calls associated with this contact so far, including inbound calls they placed." }, "next_call_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of the next scheduled call, or null if none is scheduled." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address of the contact, or null if unknown." }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA timezone of the contact, for example `America/Los_Angeles`." }, "salutation": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Salutation for the contact, for example `Ms.`." }, "status": { "type": "string", "enum": [ "new", "pending", "reached", "closed" ], "description": "Where the contact stands in the dialer: `new` (not called yet), `pending` (in the dialer, being called), `closed` (dialer exhausted, no further attempts), or `reached` (conversation happened, no further attempts)." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable key of the contact property, as defined in Settings > Contact properties." }, "value": { "description": "Value stored for this contact. The JSON type follows `dataType`." }, "dataType": { "type": "string", "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ], "description": "Data type of the property." }, "label": { "description": "Human-readable label of the property.", "type": "string" }, "options": { "description": "Allowed options. Present only for `select` and `multi_select` properties.", "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Stored value of the option." }, "label": { "type": "string", "description": "Human-readable label of the option." }, "description": { "description": "Optional longer description of the option.", "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "key", "value", "dataType" ], "additionalProperties": false }, "description": "Structured contact properties, resolved against your account's property schema." } }, "required": [ "contact_id", "external_contact_id", "external_url", "created_at", "gender", "first_name", "last_name", "phone_number", "in_call_since", "reached_at", "contact_details", "call_attempts", "next_call_at", "email", "timezone", "salutation", "status", "properties" ], "additionalProperties": false, "description": "The contact as it stood after the call was processed." } }, "required": [ "event", "call", "contact" ], "additionalProperties": false }, "example": { "event": "call_ended", "call": { "ended_reason": "contact-ended-call", "call_id": "b4a05730-2abc-4eb0-8066-2e4d23b53ba9", "loop_id": "ba99c99d-19b9-4a0d-8df6-3e213088989a", "attempt": 1, "from_number": "+17755719467", "direction": "outbound", "to_number": "+14155552671", "external_contact_id": "external-123", "contact_id": "6bd1e7e0-6d00-4c0b-ad5b-daa72457a27d", "contact_details": { "company": "Art Studio Inc" }, "contact_properties": [ { "key": "industry", "value": "retail", "dataType": "string", "label": "Industry" } ], "agent_id": "d8931604-92ad-45cf-9071-d9cd2afbad0c", "triggered_at": 1731956924302, "triggered_at_iso": "2024-11-18T15:08:44.302Z", "started_at": 1731956932264, "started_at_iso": "2024-11-18T15:08:52.264Z", "ended_at": 1731957002078, "ended_at_iso": "2024-11-18T15:10:02.078Z", "call_length_min": 2, "call_length_sec": 69, "call_status": "COMPLETED", "state": "ended", "status": "connected", "follow_up": null, "transcript": "Agent: Hello...", "transcriptObject": [ { "role": "agent", "content": "Hello..." }, { "role": "user", "content": "Hi, I was hoping to book an appointment." }, { "role": "agent", "toolActivity": "get_available_timeslots", "type": "function_call" }, { "role": "agent", "content": "I can offer you Thursday at 13:15." } ], "call_analysis": { "appointment": { "value": true, "details": "2025-02-18T15:30:00Z" }, "interest": { "value": true, "details": "The customer is interested in buying an ice cream machine" } }, "call_outcome": { "custom_lost_reason": { "value": "PRODUCT_TOO_EXPENSIVE", "fieldSchema": { "type": [ "string", "null" ], "enum": [ "CUSTOMER_NOT_INTERESTED", "CUSTOMER_PREVIOUSLY_CONTACTED", "PRODUCT_TOO_EXPENSIVE" ] } } }, "collected_data": { "email": { "status": "confirmed", "value": "frida@kahlo.com" }, "delivery_address": { "status": "confirmed", "value": "Rosenthaler Straße 51, 10178 Berlin, Germany", "latitude": 52.5253059, "longitude": 13.4043936 } }, "booked_slot_for": "2025-02-24T15:30:00Z", "recording_url": "https://example.com/recording.wav", "sip_status_code": 200, "sip_status": "OK", "transfer": null }, "contact": { "contact_id": "6bd1e7e0-6d00-4c0b-ad5b-daa72457a27d", "external_contact_id": "external-123", "external_url": null, "created_at": "2024-11-18T15:00:00.000Z", "gender": null, "first_name": "Frida", "last_name": "Kahlo", "phone_number": "+14155552671", "in_call_since": null, "reached_at": "2024-11-18T15:08:52.264Z", "contact_details": { "company": "Art Studio Inc" }, "call_attempts": 1, "next_call_at": null, "email": "frida@kahlo.com", "timezone": "America/Los_Angeles", "salutation": "Ms.", "status": "reached", "properties": [ { "key": "industry", "value": "retail", "dataType": "string", "label": "Industry" } ] } } } } }, "responses": { "2XX": { "description": "Acknowledged. Return any 2xx within 15 seconds or the message is retried." } } } }, "auto_dialer_status_changed": { "post": { "summary": "Auto dialer status changed", "description": "Sent when a contact enters or exits the auto dialer. Exits carry a reason.", "operationId": "auto_dialer_status_changed", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "auto_dialer_status_changed", "description": "Always `auto_dialer_status_changed`." }, "contact": { "type": "object", "properties": { "id": { "type": "string", "description": "telli identifier of the contact." }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your own identifier for the contact, if one was supplied." } }, "required": [ "id", "external_id" ], "additionalProperties": false }, "auto_dialer": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "in_dialer", "description": "The contact entered the auto dialer." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of when the contact entered the auto dialer." } }, "required": [ "status", "updated_at" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "not_in_dialer", "description": "The contact exited the auto dialer." }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp of when the contact exited the auto dialer." }, "reason": { "type": "string", "enum": [ "last_call_was_connected", "scheduler_gave_up_interval", "scheduler_gave_up_smart", "call_transferred", "manually_removed_from_dialer", "no_next_opportunity", "sip_error", "call_failed", "dialing_unavailable" ], "description": "Why the contact exited. Sent only for `not_in_dialer`." } }, "required": [ "status", "updated_at", "reason" ], "additionalProperties": false } ], "description": "Whether the contact is now in the auto dialer, and — when they exited — why." } }, "required": [ "event", "contact", "auto_dialer" ], "additionalProperties": false }, "example": { "event": "auto_dialer_status_changed", "contact": { "id": "6bd1e7e0-6d00-4c0b-ad5b-daa72457a27d", "external_id": "external-123" }, "auto_dialer": { "status": "not_in_dialer", "updated_at": "2024-11-18T15:10:02.078Z", "reason": "last_call_was_connected" } } } } }, "responses": { "2XX": { "description": "Acknowledged. Return any 2xx within 15 seconds or the message is retried." } } } }, "contact_status_changed": { "post": { "summary": "Contact status changed", "description": "Deprecated, and removed on July 1, 2027. Sent when a contact's status changes. Use `auto_dialer_status_changed` to track auto dialer membership instead.", "operationId": "contact_status_changed", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "const": "contact_status_changed", "description": "Always `contact_status_changed`." }, "contact": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "telli identifier of the contact." }, "external_contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Your own identifier for the contact, if one was supplied." }, "status": { "type": "string", "enum": [ "new", "pending", "reached", "closed" ], "description": "Where the contact stands in the dialer: `new` (not called yet), `pending` (in the dialer, being called), `closed` (dialer exhausted, no further attempts), or `reached` (conversation happened, no further attempts)." }, "status_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of when the status changed." }, "reached_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 timestamp of when the contact was first reached, or null if never reached." }, "first_name": { "type": "string", "description": "First name of the contact." }, "last_name": { "type": "string", "description": "Last name of the contact." }, "phone_number": { "type": "string", "description": "Phone number of the contact in E.164 format." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Email address of the contact, or null if unknown." }, "contact_details": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Free-form dynamic variables stored on the contact. Empty or null if none." }, "properties": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable key of the contact property, as defined in Settings > Contact properties." }, "value": { "description": "Value stored for this contact. The JSON type follows `dataType`." }, "dataType": { "type": "string", "enum": [ "string", "number", "boolean", "date", "datetime", "select", "multi_select", "phone_number", "email" ], "description": "Data type of the property." }, "label": { "description": "Human-readable label of the property.", "type": "string" }, "options": { "description": "Allowed options. Present only for `select` and `multi_select` properties.", "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Stored value of the option." }, "label": { "type": "string", "description": "Human-readable label of the option." }, "description": { "description": "Optional longer description of the option.", "type": "string" } }, "required": [ "value", "label" ], "additionalProperties": false } } }, "required": [ "key", "value", "dataType" ], "additionalProperties": false }, "description": "Structured contact properties, resolved against your account's property schema." } }, "required": [ "contact_id", "external_contact_id", "status", "status_updated_at", "reached_at", "first_name", "last_name", "phone_number", "email", "contact_details", "properties" ], "additionalProperties": false } }, "required": [ "event", "contact" ], "additionalProperties": false }, "example": { "event": "contact_status_changed", "contact": { "contact_id": "6bd1e7e0-6d00-4c0b-ad5b-daa72457a27d", "external_contact_id": "external-123", "status": "reached", "status_updated_at": "2024-11-18T15:10:02.078Z", "reached_at": "2024-11-18T15:08:52.264Z", "first_name": "Frida", "last_name": "Kahlo", "phone_number": "+14155552671", "email": "frida@kahlo.com", "contact_details": { "company": "Art Studio Inc" }, "properties": [ { "key": "industry", "value": "retail", "dataType": "string", "label": "Industry" } ] } } } } }, "responses": { "2XX": { "description": "Acknowledged. Return any 2xx within 15 seconds or the message is retried." } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key authentication. Use your telli API key as the bearer token." } } } }