Hello world
" }, "cc": { "type": "string", "description": "CC recipients (optional)" }, "bcc": { "type": "string", "description": "BCC recipients (optional)" }, "lead_id": { "type": "string", "description": "Associate email with a contact ID (optional)" }, "opportunity_id": { "type": "string", "description": "Associate email with an opportunity ID (optional)" }, "signature_id": { "type": "string", "description": "Append this signature to the email (optional, get from signatures/get)" }, "tracking": { "type": "string", "description": "Enable open tracking, set to \"y\" (optional)" } }, "required": [ "token", "to", "subject", "html" ] } } } } } }, "/api/1.0/emails/get.json": { "post": { "operationId": "email_get_inbox", "summary": "Get emails from inbox or sent folder", "tags": [ "emails" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "type": { "type": "string", "description": "Folder: \"inbox\" (default) or \"sent\"", "example": "inbox" }, "var_resultspage": { "type": "string", "description": "Maximum number of results", "example": "20" }, "var_page": { "type": "string", "description": "Page number", "example": "1" }, "search_value": { "type": "string", "description": "Search in subject (optional)" }, "unread_only": { "type": "string", "description": "Show only unread, set to \"y\" (optional)" } }, "required": [ "token", "type", "var_resultspage", "var_page" ] } } } } } }, "/api/1.0/emails/getone.json": { "post": { "operationId": "email_get_one", "summary": "Get a single email with full body", "tags": [ "emails" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "email_id": { "type": "string", "description": "ID of the email" } }, "required": [ "token", "email_id" ] } } } } } }, "/api/1.0/emails/signatures/get.json": { "post": { "operationId": "email_get_signatures", "summary": "Get all email signatures", "tags": [ "emails" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" } }, "required": [ "token" ] } } } } } }, "/api/1.0/emails/signatures/save.json": { "post": { "operationId": "email_save_signature", "summary": "Create or update an email signature", "tags": [ "emails" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "signature_id": { "type": "string", "description": "ID of signature to update (omit to create new)" }, "name": { "type": "string", "description": "Signature name", "example": "My Signature" }, "html": { "type": "string", "description": "Signature HTML content", "example": "Best regards
" }, "is_default": { "type": "string", "description": "Set as default signature, \"true\" or \"false\"", "example": "false" } }, "required": [ "token", "signature_id", "name", "html", "is_default" ] } } } } } }, "/api/1.0/emails/signatures/delete.json": { "post": { "operationId": "email_delete_signature", "summary": "Delete an email signature", "tags": [ "emails" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "signature_id": { "type": "string", "description": "ID of the signature to delete" } }, "required": [ "token", "signature_id" ] } } } } } }, "/api/1.0/emails/templates/get.json": { "post": { "operationId": "email_get_templates", "summary": "Get all email templates", "tags": [ "emails" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" } }, "required": [ "token" ] } } } } } }, "/api/1.0/emails/templates/create.json": { "post": { "operationId": "email_create_template", "summary": "Create a new email template", "tags": [ "emails" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "name": { "type": "string", "description": "Template name", "example": "My Template" }, "subject": { "type": "string", "description": "Default email subject (optional)" }, "html": { "type": "string", "description": "Template HTML content", "example": "Hello {{name}}
" } }, "required": [ "token", "name", "html" ] } } } } } }, "/api/1.0/emails/templates/edit.json": { "post": { "operationId": "email_edit_template", "summary": "Edit an email template", "tags": [ "emails" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "template_id": { "type": "string", "description": "ID of the template to edit" }, "name": { "type": "string", "description": "Template name (optional)" }, "subject": { "type": "string", "description": "Default email subject (optional)" }, "html": { "type": "string", "description": "Template HTML content (optional)" } }, "required": [ "token", "template_id" ] } } } } } }, "/api/1.0/emails/templates/delete.json": { "post": { "operationId": "email_delete_template", "summary": "Delete an email template", "tags": [ "emails" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "template_id": { "type": "string", "description": "ID of the template to delete" } }, "required": [ "token", "template_id" ] } } } } } }, "/api/1.0/voice/countries.json": { "get": { "operationId": "get_voice_countries", "summary": "Get complete list of countries with ISO code, name, and phone code", "tags": [ "voice" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "verified_http_read", "x-shared-core": "app-express:get_voice_countries", "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } }, { "name": "lang", "in": "query", "required": false, "description": "Language for country names. Use \"es\" for Spanish (optional)", "schema": { "type": "string" } } ] } }, "/api/1.0/phonenumbers/countries.json": { "get": { "operationId": "phonenumbers_get_countries", "summary": "Get all countries with phone numbers available for purchase: ISO code, name, phone prefix, available number types and how many area groups each one has. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } } ] } }, "/api/1.0/phonenumbers/did_groups.json": { "get": { "operationId": "phonenumbers_get_did_groups", "summary": "Get purchasable number groups (area codes) of a country with client prices in EUR. Each group lists its SKUs (capacity plans): setup and monthly price, included channels, per-minute incoming cost (coste_xmin/coste_xllam, 0 for flat-rate plans) and whether the plan is sellable. needs_registration=true means identity documents are required after purchase. Global/UIFN groups are returned for any country. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } }, { "name": "country", "in": "query", "required": true, "description": "Country ISO2 code (e.g. ES, GB, US)", "schema": { "type": "string", "example": "ES" } }, { "name": "type", "in": "query", "required": false, "description": "Filter by group type: Local, National, Mobile, Toll-free, Shared Cost, Global (optional)", "schema": { "type": "string" } }, { "name": "q", "in": "query", "required": false, "description": "Search by area name or prefix (optional)", "schema": { "type": "string" } } ] } }, "/api/1.0/phonenumbers/available_dids.json": { "get": { "operationId": "phonenumbers_get_available_dids", "summary": "Get the specific numbers available to pick inside a DID group (live from the provider). If the list is empty a new random number can still be ordered (new_number_available is always true). Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } }, { "name": "did_group", "in": "query", "required": true, "description": "DID group id (from did_groups.json)", "schema": { "type": "string" } } ] } }, "/api/1.0/phonenumbers/order.json": { "post": { "operationId": "phonenumbers_order", "summary": "Buy a phone number: creates the order at the provider, charges the voice credit balance and assigns the line to a PBX (creates a new PBX with a default IVR if none is given). If needs_registration is true the number requires identity verification (see requirements, identity and identity_submit endpoints). The line starts as activating (estado 0) and switches to active automatically when the provider confirms. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "did_group_id": { "type": "string", "description": "DID group id (from did_groups.json)" }, "sku_id": { "type": "string", "description": "Capacity plan SKU id of the group (from did_groups.json, only sellable SKUs)" }, "available_did_id": { "type": "string", "description": "Specific number picked from available_dids.json; omit to get a new random number (optional)" }, "idcampanadondecrear": { "type": "integer", "description": "PBX id where to attach the number; omit to create a new PBX with a default IVR (optional)" }, "lang": { "type": "string", "description": "2-letter language for the default IVR TTS voice when a new PBX is created (optional, default en)" } }, "required": [ "token", "did_group_id", "sku_id" ] } } } } } }, "/api/1.0/phonenumbers/requirements.json": { "get": { "operationId": "phonenumbers_get_requirements", "summary": "Get the regulatory registration requirements of a DID group: accepted identity/address proof types, mandatory identity fields and permanent document templates. Returns needs_registration=false with an empty list when no registration is needed. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } }, { "name": "did_group_id", "in": "query", "required": true, "description": "DID group id (from did_groups.json)", "schema": { "type": "string" } } ] } }, "/api/1.0/phonenumbers/identity.json": { "post": { "operationId": "phonenumbers_create_identity", "summary": "Create a regulatory identity with its address at the provider (needed for numbers with needs_registration). Returns identity_id and address_id to use with identity_document.json and identity_submit.json. The identity is saved and reusable for future numbers (see identities_list.json). Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "identity.identity_type": { "type": "string", "description": "Identity type: personal or business", "example": "personal" }, "identity.first_name": { "type": "string", "description": "First name (or legal representative for business)" }, "identity.last_name": { "type": "string", "description": "Last name" }, "identity.phone_number": { "type": "string", "description": "Contact phone number with international prefix" }, "identity.company_name": { "type": "string", "description": "Company name (business identities)" }, "identity.company_reg_number": { "type": "string", "description": "Company registration number (if required by the country)" }, "identity.vat_id": { "type": "string", "description": "VAT id (if required by the country)" }, "identity.personal_tax_id": { "type": "string", "description": "Personal tax id (if required by the country)" }, "identity.id_number": { "type": "string", "description": "Personal id/passport number (if required by the country)" }, "identity.birth_date": { "type": "string", "description": "Birth date YYYY-MM-DD (if required by the country)" }, "identity.contact_email": { "type": "string", "description": "Contact email (optional)" }, "address.country_iso": { "type": "string", "description": "Address country ISO2 code", "example": "ES" }, "address.city_name": { "type": "string", "description": "City" }, "address.postal_code": { "type": "string", "description": "Postal code" }, "address.address": { "type": "string", "description": "Street address" }, "address.description": { "type": "string", "description": "Address description (optional)" } }, "required": [ "token", "identity.identity_type", "identity.first_name", "identity.last_name", "identity.phone_number", "identity.company_name", "identity.company_reg_number", "identity.vat_id", "identity.personal_tax_id", "identity.id_number", "identity.birth_date", "address.country_iso", "address.city_name", "address.postal_code", "address.address" ] } } } } } }, "/api/1.0/phonenumbers/identities_list.json": { "get": { "operationId": "phonenumbers_list_identities", "summary": "List the client's saved regulatory identities with their addresses and verification status, to reuse them when registering another number. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } } ] } }, "/api/1.0/phonenumbers/address.json": { "post": { "operationId": "phonenumbers_create_address", "summary": "Add an additional address to one of the client's existing regulatory identities (identity reuse for a number in another city/country). Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "identity_id": { "type": "string", "description": "Identity id owned by the client (from identities_list.json)" }, "address.country_iso": { "type": "string", "description": "Address country ISO2 code", "example": "ES" }, "address.city_name": { "type": "string", "description": "City" }, "address.postal_code": { "type": "string", "description": "Postal code" }, "address.address": { "type": "string", "description": "Street address" }, "address.description": { "type": "string", "description": "Address description (optional)" } }, "required": [ "token", "identity_id", "address.country_iso", "address.city_name", "address.postal_code", "address.address" ] } } } } } }, "/api/1.0/phonenumbers/identity_document.json": { "post": { "operationId": "phonenumbers_upload_identity_document", "summary": "Upload a verification document (multipart form-data, field name: file; pdf/jpg/png, max 20MB). The file is encrypted client-side before being sent to the provider. kind=proof_identity links it to an identity (needs proof_type_id), kind=proof_address to an address (needs proof_type_id and address_id), kind=permanent_document to a permanent template (needs template_id). Proof type and template ids come from requirements.json. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "file": { "type": "string", "format": "binary", "description": "Document file (multipart form-data; pdf, jpg or png, max 20MB)" }, "kind": { "type": "string", "description": "Document kind: proof_identity, proof_address or permanent_document", "example": "proof_identity" }, "identity_id": { "type": "string", "description": "Identity id owned by the client (required for proof_identity and permanent_document)" }, "proof_type_id": { "type": "string", "description": "Proof type id from requirements.json (required for proof_identity and proof_address)" }, "address_id": { "type": "string", "description": "Address id the proof belongs to (required for proof_address)" }, "template_id": { "type": "string", "description": "Permanent document template id from requirements.json (required for permanent_document)" }, "description": { "type": "string", "description": "File description (optional)" } }, "required": [ "token", "file", "kind", "identity_id", "proof_type_id", "address_id", "template_id" ] } } } } } }, "/api/1.0/phonenumbers/identity_submit.json": { "post": { "operationId": "phonenumbers_submit_identity", "summary": "Submit the address verification of a purchased number for provider review. Optionally pre-validates against the address requirement so missing data is reported instantly (validation_failed) instead of days later as a rejection. On approval the line is activated automatically and the user gets a push notification. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "did_id": { "type": "string", "description": "DID id of the purchased number (returned by order.json)" }, "address_id": { "type": "string", "description": "Address id of one of the client's identities" }, "identity_id": { "type": "string", "description": "Identity id, when the address alone is ambiguous (optional)" }, "address_requirement_id": { "type": "string", "description": "Address requirement id from requirements.json to pre-validate before submitting (optional, recommended)" }, "service_description": { "type": "string", "description": "Short description of the service using the number (optional, default: CRM phone line)" } }, "required": [ "token", "did_id", "address_id" ] } } } } } }, "/api/1.0/phonenumbers/identity_status.json": { "get": { "operationId": "phonenumbers_get_identity_status", "summary": "Get the live verification status of a number registration (pending, approved or rejected with reject reasons). If the provider already approved it, the line is activated on the spot. Pass did_id or verification_id. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } }, { "name": "did_id", "in": "query", "required": true, "description": "DID id of the number (alternative to verification_id)", "schema": { "type": "string" } }, { "name": "verification_id", "in": "query", "required": true, "description": "Verification id returned by identity_submit.json (alternative to did_id)", "schema": { "type": "string" } } ] } }, "/api/1.0/phonenumbers/pending_registrations.json": { "get": { "operationId": "phonenumbers_get_pending_registrations", "summary": "Get the client's numbers with identity registration pending (not sent, in review or rejected) plus the numbers still activating (bought without registration, waiting for provider confirmation, last 72h). Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } } ] } }, "/api/1.0/phonenumbers/capacity_info.json": { "get": { "operationId": "phonenumbers_get_capacity_info", "summary": "Get the current channel capacity of a phone line (included and dedicated channels) and the monthly price per extra dedicated channel in EUR. pool_disponible=false means extra channels are not available for that country. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } }, { "name": "phoneline", "in": "query", "required": true, "description": "Phone line number (digits only, with country prefix)", "schema": { "type": "string", "example": "34930000000" } } ] } }, "/api/1.0/phonenumbers/contract_channels.json": { "post": { "operationId": "phonenumbers_contract_channels", "summary": "Buy extra dedicated channels for a phone line (1 to 50). Charges the voice credit balance, expands the DID capacity at the provider and adds the price to the line's monthly renewal. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "phoneline": { "type": "string", "description": "Phone line number (digits only, with country prefix)", "example": "34930000000" }, "channels": { "type": "integer", "description": "Number of dedicated channels to add (1-50)", "example": "1" } }, "required": [ "token", "phoneline", "channels" ] } } } } } }, "/api/1.0/phonenumbers/move.json": { "post": { "operationId": "phonenumbers_move", "summary": "Move a phone number to another PBX of the same client, or create a new PBX (with a default IVR) and move it there. Identify the line with phoneline or id_alias; set to_pbx_id for an existing PBX or new_pbx=true to create one. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "phoneline": { "type": "string", "description": "Phone line number to move (alternative to id_alias)", "example": "34930000000" }, "id_alias": { "type": "integer", "description": "Internal line id (alternative to phoneline)" }, "to_pbx_id": { "type": "integer", "description": "Destination PBX id (required unless new_pbx is true)" }, "new_pbx": { "type": "boolean", "description": "Set to true to create a new PBX and move the number there" }, "new_pbx_name": { "type": "string", "description": "Name for the new PBX (optional, only with new_pbx)" }, "lang": { "type": "string", "description": "2-letter language for the new PBX default IVR TTS voice (optional, default en)" } }, "required": [ "token", "phoneline", "id_alias", "to_pbx_id", "new_pbx" ] } } } } } }, "/api/1.0/phonenumbers/clone_pbx.json": { "post": { "operationId": "phonenumbers_clone_pbx", "summary": "Clone a PBX: campaign, configuration and all call-flow nodes (node links are remapped). Phone numbers are NOT cloned. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "pbx_id": { "type": "integer", "description": "PBX id to clone (must belong to the client)" }, "new_name": { "type": "string", "description": "Name for the cloned PBX (optional, default: original name + (copy))" } }, "required": [ "token", "pbx_id" ] } } } } } }, "/api/1.0/phonenumbers/delete.json": { "post": { "operationId": "phonenumber_delete", "summary": "Cancel a phone line: terminates the number at the provider and removes the line. The purchase is refunded in credits only if cancelled the same month it was bought. The cancellation is irreversible. Requires phone numbers management permission.", "tags": [ "phonenumbers" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "phoneline": { "type": "string", "description": "Phone line number to cancel (digits only, with country prefix)", "example": "34930000000" } }, "required": [ "token", "phoneline" ] } } } } } }, "/api/1.0/domains/check.json": { "get": { "operationId": "domain_check_availability", "summary": "Check domain availability and pricing. Returns availability status, price in credits, original price, current balance and whether the user can afford it.", "tags": [ "domains" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } }, { "name": "domain", "in": "query", "required": true, "description": "Domain name to check (e.g. example.com)", "schema": { "type": "string" } } ] } }, "/api/1.0/domains/register.json": { "post": { "operationId": "domain_register", "summary": "Buy a domain in Cloudflare and leave it fully working in the same call. Registrant contact is NOT required (Cloudflare uses the account's default registrant, already verified, so no ICANN verification email is ever sent). Credits are charged atomically BEFORE the purchase and refunded only if the registrar confirms it failed. The domain is saved with status 'active': there is no activation step and no email to confirm. The services listed in 'services' are activated right away (DNS records in Cloudflare + mail server).", "tags": [ "domains" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "domain": { "type": "string", "description": "Domain name to register" }, "services": { "type": "array", "description": "Service keys to activate on purchase. Also accepts a comma-separated string ('web,mail,cabinet') or the ?services= query param. Aliases: app=crm, cloud=infinitycloud, trade=cabinet, correo=mail, hosting=web. Default: [\"mail\",\"web\"]", "example": [ "mail", "web" ] }, "years": { "type": "integer", "description": "Ignored: Cloudflare always registers for 1 year", "example": "1" }, "contact": { "type": "object", "description": "OPTIONAL registrant data (firstName, lastName, address1, city, state, postalCode, country, phone, email, org). Only stored in mail_domains.contact — it is never sent to the registrar." } }, "required": [ "token", "domain", "services", "years" ] } } } } } }, "/api/1.0/domains/activate.json": { "post": { "operationId": "domain_activate", "summary": "Re-activate / repair a domain. Since 2026-07-29 register.json already leaves the domain active and serving, so this is NOT a required step of the purchase any more: it re-creates the DNS records in Cloudflare, re-registers the domain in the mail server and marks it active. Idempotent — safe to call as many times as needed.", "tags": [ "domains" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "domain": { "type": "string", "description": "Domain name to re-activate" }, "services": { "type": "array", "description": "OPTIONAL service keys. Defaults to the services the domain already has (or mail+web).", "example": [ "mail", "web" ] } }, "required": [ "token", "domain" ] } } } } } }, "/api/1.0/domains/servers.json": { "get": { "operationId": "domain_get_services", "summary": "Get the status of all configured services for a domain. Returns each service key, status, host and value.", "tags": [ "domains" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } }, { "name": "domain", "in": "query", "required": true, "description": "Domain name to query", "schema": { "type": "string" } } ] } }, "/api/1.0/domains/managed.json": { "get": { "operationId": "domain_get_managed", "summary": "Get all domains managed by the user's company. Returns domains filtered by company_id with status, verification state, SMTP/IMAP config and services. Does not include shared platform domains.", "tags": [ "domains" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } } ] } }, "/api/1.0/domains/add.json": { "post": { "operationId": "domain_add_custom", "summary": "Add a custom (already owned) domain for verification. Saves it with status pending_verification and returns the required DNS records. The user must configure DNS and call dns/verify.json before activation.", "tags": [ "domains" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "domain": { "type": "string", "description": "Domain name to add" } }, "required": [ "token", "domain" ] } } } } } }, "/api/1.0/domains/dns/verify.json": { "get": { "operationId": "domain_dns_verify", "summary": "Verify DNS configuration for a domain. Performs real DNS lookups checking MX, SPF and DMARC records. If all pass, registers the domain in the mail server and marks it as active and verified.", "tags": [ "domains" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token", "schema": { "type": "string", "example": "YOUR_APIKEY" } }, { "name": "domain", "in": "query", "required": true, "description": "Domain name to verify", "schema": { "type": "string" } } ] } }, "/api/1.0/domains/delete_domain.json": { "post": { "operationId": "domain_delete", "summary": "Delete a domain completely. Removes all email accounts associated with that domain from the mail server, disconnects all agents using emails on that domain, removes all reverse proxy routes (domain, www, service subdomains), and deletes the domain record from the database. System domains cannot be deleted.", "tags": [ "domains" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "domain": { "type": "string", "description": "Domain name to delete" } }, "required": [ "token", "domain" ] } } } } } }, "/api/1.0/domains/renewdomain.json": { "post": { "operationId": "domain_renew", "summary": "Check the renewal status of a domain. Manual renewal is NOT supported: domains bought in Cloudflare renew themselves via auto_renew (enabled at purchase). A nightly cron charges the client's credits one day before expiry and pushes the expiry date forward; if there is not enough balance it turns auto_renew off and deactivates the domain. Master only.", "tags": [ "domains" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "domain": { "type": "string", "description": "Domain name" } }, "required": [ "token", "domain" ] } } } } } }, "/api/1.0/domains/markasdelete.json": { "post": { "operationId": "domain_mark_delete", "summary": "Mark a domain for deletion. Changes the domain status to 'pending_delete' so it will not be automatically renewed when it expires. The domain is not deleted immediately — it remains active until expiration. System domains cannot be marked.", "tags": [ "domains" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "domain": { "type": "string", "description": "Domain name to mark for deletion" } }, "required": [ "token", "domain" ] } } } } } }, "/api/1.0/domains/activate_services.json": { "post": { "operationId": "domain_activate_services", "summary": "Activate several services for a domain in a single call. For registered domains it creates every DNS record in one batch against Cloudflare; services flagged as proxied go through Cloudflare's orange-cloud proxy, which terminates HTTPS and talks HTTP to the origin. For external domains it verifies the public DNS before marking each service active. Same engine register.json uses.", "tags": [ "domains" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "domain": { "type": "string", "description": "Domain name" }, "services": { "type": "array", "description": "Service keys to activate: mail, web, crm, meets, infinitycloud, cabinet. Also accepts a comma-separated string and aliases (app=crm, cloud=infinitycloud, trade=cabinet).", "example": [ "crm", "meets", "mail" ] } }, "required": [ "token", "domain", "services" ] } } } } } }, "/api/1.0/emailservices/domains.json": { "get": { "operationId": "email_list_domains", "summary": "List the domains available to create a new email account / mailbox for the authenticated agent (use this before email_create_account to know which domains the user can create an email on). The result is the intersection of emelyse.com plus active mail_domains owned by the token company with domains reported active by the mail provider. SMTP/IMAP settings are server-authoritative.", "tags": [ "emailservices" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ok", "domains" ], "properties": { "ok": { "type": "boolean", "const": true }, "domains": { "type": "array", "maxItems": 101, "items": { "type": "object", "additionalProperties": false, "required": [ "domain", "smtp_host", "smtp_port", "smtp_secure", "imap_host", "imap_port", "imap_secure", "ignoreTLS", "requireTLS" ], "properties": { "domain": { "type": "string", "maxLength": 253 }, "smtp_host": { "type": "string" }, "smtp_port": { "type": "string" }, "smtp_secure": { "type": "boolean" }, "imap_host": { "type": "string" }, "imap_port": { "type": "string" }, "imap_secure": { "type": "boolean" }, "ignoreTLS": { "type": "boolean" }, "requireTLS": { "type": "boolean" } } } } } }, "example": { "ok": true, "domains": [ { "domain": "emelyse.com", "smtp_host": "emelyse.com", "smtp_port": "587", "smtp_secure": true, "imap_host": "emelyse.com", "imap_port": "143", "imap_secure": false, "ignoreTLS": false, "requireTLS": false } ] } } } }, "401": { "description": "EMPTY_TOKEN | error_apitokennotfound | token_type_not_allowed | token_company_mismatch: The token is missing, invalid, disabled or not bound to the authenticated agent company.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "403": { "description": "scope_denied | permission_denied: The app token lacks the emailservices scope or the authenticated account is not allowed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "500": { "description": "internal_error: An unexpected tenant-domain or configuration mapping read failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "502": { "description": "mail_provider_unavailable | mail_provider_rejected | mail_provider_invalid_response: The bounded provider request failed or returned an unexpected status/JSON shape.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "503": { "description": "mail_provider_not_configured: MAIL_API_URL, MAIL_ADMIN_EMAIL and MAIL_ADMIN_PASSWORD are not all configured in the server environment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "504": { "description": "mail_provider_timeout: The mail provider did not answer before the configured timeout.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } } }, "x-bridge-status": "verified_shared_provider_read", "x-shared-core": "domainBridgeCores.emailservices.listDomains", "x-socket-parity": [ "DEVwebsite/modules/configemail.html:loadManagedDomains", "profile_updateAdvanced managed-domain eligibility" ], "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token for the agent whose mailbox will be configured. Scoped app tokens require the emailservices scope. The company and agent are derived only from this token.", "schema": { "type": "string", "example": "YOUR_APIKEY" } } ] } }, "/api/1.0/emailservices/create.json": { "post": { "operationId": "email_create_account", "summary": "Create a new email account / mailbox on a managed domain and configure it for the agent authenticated by token (this is the tool to use when the user asks to create an email, create a mailbox, or set up a new email address like name@yourdomain.com). The shared socket/HTTP core validates tenant domain ownership and live provider state, creates and verifies the new mailbox before an atomic local switch, then disconnects the old poller and removes only a strictly owned previous managed mailbox. HTTP calls require an idempotency key.", "tags": [ "emailservices" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful idempotent replay", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ok", "email", "job_id", "created", "idempotent_replay", "password_generated", "password_available", "sensitive", "password", "config", "cleanup" ], "properties": { "ok": { "type": "boolean", "const": true }, "email": { "type": "string", "format": "email" }, "job_id": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "created": { "type": "boolean" }, "idempotent_replay": { "type": "boolean" }, "password_generated": { "type": "boolean" }, "password_available": { "type": "boolean" }, "sensitive": { "type": "boolean", "const": true }, "password": { "type": [ "string", "null" ], "description": "Sensitive. Present for the fresh operation; replay returns it only while this exact job still owns the authenticated agent's current configuration." }, "config": { "type": "object", "additionalProperties": false, "required": [ "smtp_host", "smtp_port", "smtp_secure", "imap_host", "imap_port", "imap_secure", "ignoreTLS", "requireTLS" ], "properties": { "smtp_host": { "type": "string" }, "smtp_port": { "type": "string" }, "smtp_secure": { "type": "boolean" }, "imap_host": { "type": "string" }, "imap_port": { "type": "string" }, "imap_secure": { "type": "boolean" }, "ignoreTLS": { "type": "boolean" }, "requireTLS": { "type": "boolean" } } }, "cleanup": { "type": "object", "additionalProperties": false, "required": [ "poller", "previous_managed_account" ], "properties": { "poller": { "type": "string" }, "previous_managed_account": { "type": "string" } } } } }, "example": { "ok": true, "email": "support@emelyse.com", "job_id": "66a4c5ce924b434a8db0e331", "created": true, "idempotent_replay": false, "password_generated": true, "password_available": true, "sensitive": true, "password": "ExampleGeneratedPass123!", "config": { "smtp_host": "emelyse.com", "smtp_port": "587", "smtp_secure": true, "imap_host": "emelyse.com", "imap_port": "143", "imap_secure": false, "ignoreTLS": false, "requireTLS": false }, "cleanup": { "poller": "completed", "previous_managed_account": "deleted" } } } } }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "ok", "email", "job_id", "created", "idempotent_replay", "password_generated", "password_available", "sensitive", "password", "config", "cleanup" ], "properties": { "ok": { "type": "boolean", "const": true }, "email": { "type": "string", "format": "email" }, "job_id": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "created": { "type": "boolean" }, "idempotent_replay": { "type": "boolean" }, "password_generated": { "type": "boolean" }, "password_available": { "type": "boolean" }, "sensitive": { "type": "boolean", "const": true }, "password": { "type": [ "string", "null" ], "description": "Sensitive. Present for the fresh operation; replay returns it only while this exact job still owns the authenticated agent's current configuration." }, "config": { "type": "object", "additionalProperties": false, "required": [ "smtp_host", "smtp_port", "smtp_secure", "imap_host", "imap_port", "imap_secure", "ignoreTLS", "requireTLS" ], "properties": { "smtp_host": { "type": "string" }, "smtp_port": { "type": "string" }, "smtp_secure": { "type": "boolean" }, "imap_host": { "type": "string" }, "imap_port": { "type": "string" }, "imap_secure": { "type": "boolean" }, "ignoreTLS": { "type": "boolean" }, "requireTLS": { "type": "boolean" } } }, "cleanup": { "type": "object", "additionalProperties": false, "required": [ "poller", "previous_managed_account" ], "properties": { "poller": { "type": "string" }, "previous_managed_account": { "type": "string" } } } } }, "example": { "ok": true, "email": "support@emelyse.com", "job_id": "66a4c5ce924b434a8db0e331", "created": true, "idempotent_replay": false, "password_generated": true, "password_available": true, "sensitive": true, "password": "ExampleGeneratedPass123!", "config": { "smtp_host": "emelyse.com", "smtp_port": "587", "smtp_secure": true, "imap_host": "emelyse.com", "imap_port": "143", "imap_secure": false, "ignoreTLS": false, "requireTLS": false }, "cleanup": { "poller": "completed", "previous_managed_account": "deleted" } } } } }, "400": { "description": "invalid_request | email_required | invalid_email | invalid_local_part | invalid_password | idempotency_key_required | invalid_idempotency_key | conflicting_idempotency_key | agent_id_not_allowed | company_id_not_allowed: The request shape, address, password or HTTP idempotency key is invalid. Raw agent_id and company_id overrides are rejected before authentication normalization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "401": { "description": "EMPTY_TOKEN | error_apitokennotfound | token_type_not_allowed | token_company_mismatch: The API token is missing, invalid, disabled or bound to a different tenant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "403": { "description": "scope_denied | permission_denied | domain_not_allowed: The token lacks emailservices scope/permission or the requested domain is not active and owned exactly by the token company.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "404": { "description": "agent_not_found: The authenticated agent no longer exists in the token company.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "409": { "description": "idempotency_conflict | operation_in_progress | recovery_manual_required | domain_not_active | email_in_use | configuration_changed: The idempotency key has a different payload, another live lease holds the company+agent lock, uncertain stale provider state requires manual reconciliation, the provider domain is inactive, the mailbox already exists, or local mail state changed concurrently.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "500": { "description": "persistence_failed | internal_error: The local atomic switch failed. A mailbox created by this operation is compensated only after strict provider id/email/company/agent verification.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "502": { "description": "mail_provider_unavailable | mail_provider_rejected | mail_provider_invalid_response | mail_provider_verification_failed: The provider request failed, returned an unexpected bounded JSON/status, or the newly created mailbox could not be verified.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "503": { "description": "mail_provider_not_configured | safety_unavailable: Required provider environment credentials are absent or the unique lock/idempotency indexes are unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "504": { "description": "mail_provider_timeout: A mail provider operation exceeded its configured timeout.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } } }, "x-bridge-status": "verified_shared_transactional_core", "x-shared-core": "domainBridgeCores.emailservices.createManagedAccount", "x-socket-parity": [ "profile_updateAdvanced(is_managed_domain=true)", "profile_updateAdvancedRESP('managed','ok')" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token", "email", "idempotency_key" ], "properties": { "token": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 3, "maxLength": 254 }, "password": { "type": "string", "maxLength": 128, "description": "Empty means generate securely; non-empty values must pass the documented complexity policy." }, "idempotency_key": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]{8,128}$" } } }, "examples": { "example_1": { "summary": "Generate a strong password server-side", "value": { "token": "YOUR_APIKEY", "email": "support@emelyse.com", "idempotency_key": "mail-create-20260726-001" } }, "example_2": { "summary": "Use a caller-supplied strong password", "value": { "token": "YOUR_APIKEY", "email": "sales@owned.example", "password": "ExampleStrongPass123!", "idempotency_key": "mail-create-20260726-002" } } } } } } } }, "/api/1.0/uploads/create.json": { "post": { "operationId": "uploads_create", "summary": "Secure multipart upload for public API, AI assistants and MCP tools. Upload 1-5 files under the repeated 'files' field (10 MiB each, 25 MiB aggregate). Send the API key in the multipart field token, consistently with the other POST APIs. Files may optionally be attached to one visible CRM record by sending entitykey and record_id together; company and RBAC scope always come from the token, never from client-supplied IDs.", "tags": [ "uploads" ], "x-enabled-for-ai-assistant": true, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "files" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "files": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "object", "required": [ "id", "name", "mime_type", "size", "checksum_sha256", "created_at", "association" ], "properties": { "id": { "type": "string", "pattern": "^[a-f0-9]{24}$" }, "name": { "type": "string" }, "mime_type": { "type": "string" }, "size": { "type": "integer", "minimum": 1, "maximum": 10485760 }, "checksum_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "created_at": { "type": "integer", "description": "Unix UTC epoch seconds" }, "association": { "oneOf": [ { "type": "object", "required": [ "entitykey", "record_id" ], "properties": { "entitykey": { "type": "string" }, "record_id": { "type": "string", "pattern": "^[a-f0-9]{24}$" } } }, { "type": "null" } ] } } } } } }, "example": { "status": "ok", "files": [ { "id": "69d9d868740030527e46055b", "name": "document.pdf", "mime_type": "application/pdf", "size": 123456, "checksum_sha256": "64 lowercase hexadecimal characters", "created_at": 1785000000, "association": { "entitykey": "leads", "record_id": "69d9d868740030527e46055a" } } ] } } } }, "400": { "description": "invalid_multipart | invalid_content_length | unexpected_query_parameter | files_required | unexpected_form_field | unexpected_file_field | incomplete_association | invalid_entitykey | invalid_record_id | invalid_file_name | invalid_temporary_file | empty_file | file_size_mismatch: Malformed multipart input, missing files, unsupported fields, or invalid optional association.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "401": { "description": "EMPTY_TOKEN | error_apitokennotfound: The multipart token field is missing, invalid or no longer authorized.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "403": { "description": "permission_denied | scope_denied: The token user role is not allowed to upload or a scoped app token lacks the 'uploads' scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "404": { "description": "entity_not_found | record_not_found_or_not_visible: The optional entity/record does not exist in this company or is outside the token user's RBAC visibility.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "411": { "description": "content_length_required: Content-Length is required so the server can enforce the aggregate request limit before parsing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "413": { "description": "request_too_large | file_too_large | too_many_files | aggregate_size_too_large: Request exceeds 27 MiB, a file exceeds 10 MiB, more than 5 files were sent, or files exceed 25 MiB combined.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "415": { "description": "multipart_form_data_required | file_type_not_allowed | mime_extension_mismatch | file_signature_mismatch: Wrong request media type or a file failed the extension, MIME or content-signature allowlist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "500": { "description": "upload_failed | server_error | record_visibility_check_failed: Unexpected storage, database or visibility failure. Temporary files are cleaned and completed cloud/database writes are rolled back best-effort.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } } }, "x-bridge-status": "verified_http_upload", "x-shared-core": "api-uploads:uploads_create", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token sent as a multipart text field, using the same token value as the other APIs. Scoped app tokens need the 'uploads' scope; personal client tokens remain constrained by their user RBAC. Required.", "example": "YOUR_APIKEY" }, "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "Repeat this multipart field once per local file. Required; 1-5 files, max 10 MiB each and 25 MiB combined. Allowed extensions/MIME pairs: pdf, jpg/jpeg, png, gif, webp, txt, md, csv, doc, xls, ppt, docx, xlsx, pptx, mp3, wav, ogg and mp4. Content signatures are checked; SVG/HTML/scripts/executables and application/octet-stream are rejected.", "minItems": 1, "maxItems": 5 }, "entitykey": { "type": "string", "description": "Optional entity key from entities/schemas.json: leads, companies, opportunities, tasks, tickets or cust_*. Must be sent together with record_id. Omit both fields for a private, unassociated upload owned by the API user.", "example": "leads" }, "record_id": { "type": "string", "description": "Optional 24-character ObjectId of the record to attach to. Must belong to the token company and be visible under the token user's RBAC scope; otherwise the API returns record_not_found_or_not_visible without revealing cross-company existence.", "example": "69d9d868740030527e46055a" } }, "required": [ "token", "files" ] } } } } } }, "/api/1.0/sendwhatsapp/getsessionsandtemplates.json": { "post": { "operationId": "whatsapp_get_sessions_and_templates", "summary": "List every connected WhatsApp Business session and its approved Meta templates. Call this before sending free-form messages, files or templates: use the returned session _id as idses and inspect template name, language and components before template dispatch. Returns discovery data only; the separate enabled send endpoints perform dispatch.", "tags": [ "sendwhatsapp" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token of the company. Required.", "example": "YOUR_APIKEY" } }, "required": [ "token" ] } } } } } }, "/api/1.0/sendwhatsapp/sendmsgtemplate.json": { "post": { "operationId": "sendwhatsapp_sendmsgtemplate", "summary": "Send a pre-approved WhatsApp Business template message directly through the Meta Cloud API and return Meta's response synchronously (including the delivered message wamid on success, or Meta's error on failure). Use this to start conversations outside the 24-hour customer service window, to send transactional notifications (OTP, order updates, shipping, reminders), or to re-engage a lead when the free-form chat window is closed. MANDATORY WORKFLOW: (1) first call /api/1.0/sendwhatsapp/getsessionsandtemplates.json to discover the sessions and their approved templates; (2) pick the session 'idses' the user wants to send from and the exact 'template_name' that matches the intent; (3) inspect that template's 'components' array — if any component contains {{1}}, {{2}}, {{3}}... body variables, pass the matching values inside the simplified 'variables' field (the server auto-inspects the template and places each value in the correct Meta slot — you do NOT need to build the Meta components array yourself). If the template has ZERO body variables and no TEXT header variable, simply omit 'variables' entirely. IMPORTANT — MEDIA HEADERS (IMAGE/VIDEO/DOCUMENT): do NOT ask the user for a media URL and do NOT send 'variables.header' for these. The server auto-loads the media from the file that was originally uploaded with the template (infinitycloud), falling back to Meta's stored example. Only pass 'variables.header' as a media URL if the user explicitly asks to override the template's attached file with a different one. Never invent variable values — if the user did not provide body/text values, ask first. Unlike the old queue-based behaviour, this endpoint now POSTs to Meta synchronously: a successful response returns 'wamid' from Meta, and a failure returns status:'error' with the Meta error embedded.", "tags": [ "sendwhatsapp" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token of the company. Required.", "example": "YOUR_APIKEY" }, "idses": { "type": "string", "description": "WhatsApp session _id (24-char Mongo ObjectId) identifying which WhatsApp Business number sends the message. Obtain it from /api/1.0/sendwhatsapp/getsessionsandtemplates.json. Required." }, "to": { "type": "string", "description": "Recipient phone number in full international format, digits only, no '+' sign, no spaces, no dashes (e.g. 34600000000). Required.", "example": "34682288834" }, "template_name": { "type": "string", "description": "Exact 'name' field of the approved WhatsApp template to send (e.g. 'datalysewowia'). Must be one of the templates returned by getsessionsandtemplates for the chosen session. Required." }, "language": { "type": "string", "description": "Template language code (e.g. 'es', 'en_US', 'pt_BR'). Optional: defaults to the template's own language. Only override it if you know the same template has multiple approved translations." }, "variables": { "type": "object", "description": "Simplified template variables — the server auto-inspects the approved template's components and places each value in the correct Meta slot, so you do NOT build the Meta components array yourself. Shape: an object with any of these keys — 'body' is an array of strings matching the template BODY's {{1}},{{2}},... placeholders in order (e.g. body:['Marc','OFFER105']); 'header' is used ONLY when the template HEADER is TEXT with a {{1}} variable (value is the plain text) OR when the caller wants to explicitly override an IMAGE/VIDEO/DOCUMENT media template with a different public URL (normally you should NOT send 'header' for media templates — the server auto-loads the file that was uploaded with the template); 'button' is an array of URL-button values where each element is either a plain string or an object {index:N, payload:'...'} for button parameter {{1}}. Shortcuts: pass a bare array of strings (['123456','Marc']) to fill only body variables, or a bare string ('123456') for a single body variable. Count and order of 'body' entries MUST match the {{n}} placeholders in the template's BODY text — use /api/1.0/sendwhatsapp/getsessionsandtemplates.json to inspect the template first. Omit this field entirely when the template has no body variables.", "example": { "body": [ "123456" ] } }, "components": { "type": "array", "description": "ADVANCED / OPTIONAL escape hatch. Pre-built Meta Cloud API components array in the exact Meta shape (entries like {type:'body', parameters:[{type:'text', text:'...'}]}). Only use this if you are replicating an existing hand-crafted Meta payload — normally you should use the simpler 'variables' field instead and let the server build the components automatically. If both 'components' and 'variables' are provided, 'components' wins.", "example": [ { "type": "body", "parameters": [ { "type": "text", "text": "HOLA" } ] } ] } }, "required": [ "token", "idses", "to", "template_name" ] }, "examples": { "example_1": { "summary": "Template WITHOUT variables", "value": { "token": "YOUR_APIKEY", "idses": "6797065fdfec41b50d649e64", "to": "34660558411", "template_name": "sample_template" } }, "example_2": { "summary": "Template with ONE body variable {{1}} (simplified 'variables')", "value": { "token": "YOUR_APIKEY", "idses": "6797065fdfec41b50d649e64", "to": "34660558411", "template_name": "authcodenow", "variables": [ "123456" ] } }, "example_3": { "summary": "Template with TEXT header variable + body variables (simplified 'variables')", "value": { "token": "YOUR_APIKEY", "idses": "6797065fdfec41b50d649e64", "to": "34660558411", "template_name": "datalysewowia", "variables": { "header": "Header value", "body": [ "Marc", "OFFER105" ] } } }, "example_4": { "summary": "Template with BODY variable only (re-engage after 24h)", "value": { "token": "YOUR_APIKEY", "idses": "YOUR_SESSION_ID", "to": "34600000000", "template_name": "mensajecuandopasanlas24holacomoestas", "variables": [ "HOLA" ] } }, "example_5": { "summary": "Template with VIDEO/IMAGE/DOCUMENT header — no 'variables.header' needed", "value": { "token": "YOUR_APIKEY", "idses": "YOUR_SESSION_ID", "to": "34600000000", "template_name": "templatenewfeatureannouncement", "language": "es" } }, "example_6": { "summary": "Template with media header + body variables + URL button (media auto-loaded)", "value": { "token": "YOUR_APIKEY", "idses": "6797065fdfec41b50d649e64", "to": "34660558411", "template_name": "templateshipmentupdate", "variables": { "body": [ "Emily", "OFFER105", "31/12/2025" ], "button": [ { "index": 0, "payload": "promo2025" } ] } } }, "example_7": { "summary": "Explicit media override (rare — only when user wants a different file)", "value": { "token": "YOUR_APIKEY", "idses": "6797065fdfec41b50d649e64", "to": "34660558411", "template_name": "templateshipmentupdate", "variables": { "header": "https://example.com/override-banner.jpg", "body": [ "Emily", "OFFER105", "31/12/2025" ] } } } } } } } } }, "/api/1.0/sendwhatsapp/sendmsg.json": { "post": { "operationId": "whatsapp_send_message", "summary": "Send a free-form WhatsApp text message from a company WhatsApp Business number. This works only inside Meta's 24-hour customer-service window; when it is closed, use the enabled sendmsgtemplate endpoint with an approved template. Obtain idses from getsessionsandtemplates.json and send exactly the recipient and text requested by the user.", "tags": [ "sendwhatsapp" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token of the company. Required.", "example": "YOUR_APIKEY" }, "idses": { "type": "string", "description": "WhatsApp session _id (24-char Mongo ObjectId) identifying which WhatsApp Business number sends the message. Obtain from /api/1.0/sendwhatsapp/getsessionsandtemplates.json. Required." }, "to": { "type": "string", "description": "Recipient phone number in full international format, digits only, no '+' sign or spaces (e.g. 34600000000). Required.", "example": "34682288834" }, "text": { "type": "string", "description": "UTF-8 body of the WhatsApp message. Supports WhatsApp's basic markdown (*bold*, _italic_, ~strike~, ```mono```). Required.", "example": "hello world" } }, "required": [ "token", "idses", "to", "text" ] } } } } } }, "/api/1.0/sendwhatsapp/sendfile.json": { "post": { "operationId": "whatsapp_send_file", "summary": "Send a media/document file by WhatsApp. The file must be on a public HTTPS URL Meta can fetch with the correct Content-Type. This works inside the 24-hour customer-service window; outside it, use the enabled template endpoint when the approved template supports that media. Obtain idses first and use only the recipient/file explicitly requested.", "tags": [ "sendwhatsapp" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token of the company. Required.", "example": "YOUR_APIKEY" }, "idses": { "type": "string", "description": "WhatsApp session _id (24-char Mongo ObjectId) identifying which WhatsApp Business number sends the file. Obtain from /api/1.0/sendwhatsapp/getsessionsandtemplates.json. Required." }, "to": { "type": "string", "description": "Recipient phone number in full international format, digits only, no '+' sign or spaces (e.g. 34600000000). Required.", "example": "34682288834" }, "file_url": { "type": "string", "description": "Publicly reachable HTTPS URL of the file to send. Meta will fetch it; the host must serve the file without authentication and with the correct Content-Type header. Required." }, "filename": { "type": "string", "description": "Display filename (including extension) shown to the recipient — especially important for PDFs and documents. Optional for images/videos." }, "caption": { "type": "string", "description": "Optional caption text that appears under the media (images/videos only; ignored for audio and most document types)." } }, "required": [ "token", "idses", "to", "file_url" ] } } } } } }, "/api/1.0/companyuserdata/companyproperties.json": { "post": { "operationId": "get_company_properties", "summary": "Get all statuses, and additional data for company", "tags": [ "companyuserdata" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" } }, "required": [ "token" ] } } } } } }, "/api/1.0/companyuserdata/getallagents.json": { "post": { "operationId": "get_all_agents", "summary": "Get all agents for the company", "tags": [ "companyuserdata" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" } }, "required": [ "token" ] } } } } } }, "/api/1.0/payments/get.json": { "post": { "operationId": "get_payments", "summary": "Get a paginated list of payments/credits for the authenticated company. Supports filtering by payment type, lead, agent, and date range (datefrom/dateto/timezone). Dates are filtered against the payment 'date' field (unix timestamp in seconds). Use this to answer questions like 'show me payments last month', 'list credits for lead X', or 'how many payments did agent Y process in January'.", "tags": [ "payments" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "var_resultspage": { "type": "string", "description": "Maximum number of results to display", "example": "20" }, "var_page": { "type": "string", "description": "Page number", "example": "1" }, "ispayment": { "type": "string", "description": "Filter by type: \"y\" for payments, \"n\" for credits (optional)" }, "id_lead": { "type": "string", "description": "Filter by lead ID (optional)" }, "agent_id": { "type": "string", "description": "Filter by agent ID (optional)" }, "datefrom": { "type": "string", "description": "Start date for filtering results by payment date (optional, format: YYYY-MM-DD, example: 2026-01-01). Requires dateto and timezone to apply." }, "dateto": { "type": "string", "description": "End date for filtering results by payment date (optional, format: YYYY-MM-DD, example: 2026-12-31). Requires datefrom and timezone to apply." }, "timezone": { "type": "string", "description": "Timezone for date filtering (optional, example: Europe/Madrid). Required together with datefrom and dateto." } }, "required": [ "token", "var_resultspage", "var_page" ] } } } } } }, "/api/1.0/payments/edit.json": { "post": { "operationId": "edit_payment", "summary": "Edit a payment", "tags": [ "payments" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "payment_id": { "type": "string", "description": "ID of the payment to edit" }, "name": { "type": "string", "description": "Payment name (optional)" }, "agent_id": { "type": "string", "description": "Agent ID (optional)" }, "amount": { "type": "string", "description": "Payment amount (optional)" }, "amount_usd": { "type": "string", "description": "Amount in USD (optional)" }, "amount_eur": { "type": "string", "description": "Amount in EUR (optional)" }, "currency": { "type": "string", "description": "Currency code (optional)" }, "ispayment": { "type": "string", "description": "Payment type flag (optional)" }, "mt4_transtype": { "type": "string", "description": "Transaction type (optional)" } }, "required": [ "token", "payment_id" ] } } } } } }, "/api/1.0/payments/delete.json": { "post": { "operationId": "delete_payment", "summary": "Delete a payment (soft delete)", "tags": [ "payments" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "payment_id": { "type": "string", "description": "ID of the payment to delete" } }, "required": [ "token", "payment_id" ] } } } } } }, "/api/1.0/budgets/getlist.json": { "post": { "operationId": "get_budgets_list", "summary": "Get a list of budgets/quotes", "tags": [ "budgets" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.budgets.list", "x-socket-parity": [ "budget_getbudgets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "var_resultspage": { "type": "string", "description": "Maximum number of results to display", "example": "20" }, "var_page": { "type": "string", "description": "Page number", "example": "1" }, "id_lead": { "type": "string", "description": "Filter by lead ID (optional)" }, "agent_id": { "type": "string", "description": "Filter by agent ID (optional)" }, "search_value": { "type": "string", "description": "Search by budget name (optional)" } }, "required": [ "token", "var_resultspage", "var_page" ] } } } } } }, "/api/1.0/budgets/getbudget.json": { "post": { "operationId": "get_one_budget", "summary": "Get a single budget/quote by ID", "tags": [ "budgets" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.budgets.detail", "x-socket-parity": [ "budget_getonebudget" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "budget_id": { "type": "string", "description": "ID of the budget" } }, "required": [ "token", "budget_id" ] } } } } } }, "/api/1.0/budgets/edit.json": { "post": { "operationId": "edit_budget", "summary": "Edit a budget/quote", "tags": [ "budgets" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.budgets.edit", "x-socket-parity": [ "budget_editbudget" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "budget_id": { "type": "string", "description": "ID of the budget to edit" }, "budget_name": { "type": "string", "description": "Budget name (optional)" }, "budget_template": { "type": "string", "description": "Budget template (optional)" }, "budget_lang": { "type": "string", "description": "Budget language (optional)" }, "budget_currency": { "type": "string", "description": "Currency code (optional)" }, "budget_vat": { "type": "string", "description": "VAT percentage (optional)" }, "budget_comentsbuyer": { "type": "string", "description": "Comments for buyer (optional)" }, "budget_terms": { "type": "string", "description": "Terms and conditions (optional)" }, "concepts": { "type": "array", "description": "Array of budget line items/concepts (optional)" }, "total": { "type": "string", "description": "Total amount (optional)" }, "totalvat": { "type": "string", "description": "Total with VAT (optional)" }, "totalsinvat": { "type": "string", "description": "Total without VAT (optional)" } }, "required": [ "token", "budget_id" ] } } } } } }, "/api/1.0/budgets/remove.json": { "post": { "operationId": "remove_budget", "summary": "Remove a budget/quote permanently", "tags": [ "budgets" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.budgets.remove", "x-socket-parity": [ "budget_deleteBudget" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "budget_id": { "type": "string", "description": "ID of the budget to remove" } }, "required": [ "token", "budget_id" ] } } } } } }, "/api/1.0/leads/getactivity.json": { "post": { "operationId": "get_lead_activity", "summary": "Get activity/timeline for a contact", "tags": [ "leads" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "lead_id": { "type": "string", "description": "ID of the contact" }, "type": { "type": "string", "description": "Filter by activity type: callin, callout, email, emailin, emailout, note, sms, form_completed, etc. (optional)" }, "var_resultspage": { "type": "string", "description": "Maximum number of results to display", "example": "20" }, "var_page": { "type": "string", "description": "Page number", "example": "1" } }, "required": [ "token", "lead_id", "var_resultspage", "var_page" ] } } } } } }, "/api/1.0/opportunities/getactivity.json": { "post": { "operationId": "get_opportunity_activity", "summary": "Get activity/timeline for an opportunity", "tags": [ "opportunities" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "opportunity_id": { "type": "string", "description": "ID of the opportunity" }, "type": { "type": "string", "description": "Filter by activity type (optional)" }, "var_resultspage": { "type": "string", "description": "Maximum number of results to display", "example": "20" }, "var_page": { "type": "string", "description": "Page number", "example": "1" } }, "required": [ "token", "opportunity_id", "var_resultspage", "var_page" ] } } } } } }, "/api/1.0/companies/getactivity.json": { "post": { "operationId": "get_company_activity", "summary": "Get activity/timeline for a company (includes activity from contacts inside the company)", "tags": [ "companies" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "company_lead_id": { "type": "string", "description": "ID of the company" }, "type": { "type": "string", "description": "Filter by activity type (optional)" }, "var_resultspage": { "type": "string", "description": "Maximum number of results to display", "example": "20" }, "var_page": { "type": "string", "description": "Page number", "example": "1" } }, "required": [ "token", "company_lead_id", "var_resultspage", "var_page" ] } } } } } }, "/api/1.0/tasks/getactivity.json": { "post": { "operationId": "get_task_activity", "summary": "Get activity/timeline for a task", "tags": [ "tasks" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "task_id": { "type": "string", "description": "ID of the task" }, "type": { "type": "string", "description": "Filter by activity type (optional)" }, "var_resultspage": { "type": "string", "description": "Maximum number of results to display", "example": "20" }, "var_page": { "type": "string", "description": "Page number", "example": "1" } }, "required": [ "token", "task_id", "var_resultspage", "var_page" ] } } } } } }, "/api/1.0/tickets/getactivity.json": { "post": { "operationId": "get_ticket_activity", "summary": "Get activity/timeline for a ticket", "tags": [ "tickets" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "ticket_id": { "type": "string", "description": "ID of the ticket" }, "type": { "type": "string", "description": "Filter by activity type (optional)" }, "var_resultspage": { "type": "string", "description": "Maximum number of results to display", "example": "20" }, "var_page": { "type": "string", "description": "Page number", "example": "1" } }, "required": [ "token", "ticket_id", "var_resultspage", "var_page" ] } } } } } }, "/api/1.0/companyuserdata/getpricepercredit.json": { "post": { "operationId": "get_price_per_credit", "summary": "Get price per credit for VOIP calls and SMS, balance and plan info", "tags": [ "companyuserdata" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" } }, "required": [ "token" ] } } } } } }, "/api/1.0/companyuserdata/agentstypes.json": { "post": { "operationId": "get_agents_types", "summary": "Get all agent types (roles) for the company, including the number of agents assigned to each type", "tags": [ "companyuserdata" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" } }, "required": [ "token" ] } } } } } }, "/api/1.0/companyuserdata/callerids.json": { "post": { "operationId": "get_callerids", "summary": "List all outbound caller IDs available to the company, filtered by permissions. Returns every line with host, id, campaign, country, alias, state and costs. The host value is the caller_id accepted by the enabled AI-agent call creation endpoint. Return every row when the user asks for caller IDs.", "tags": [ "companyuserdata" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" } }, "required": [ "token" ] } } } } } }, "/api/1.0/sendvoicecall/listaiagents.json": { "post": { "operationId": "sendvoicecall_listaiagents", "summary": "List every configured AI voice agent with id, name, language, voice, system-prompt summary and knowledge base. Call this before the enabled createcall endpoint to select the agent_ai_id matching the user's requested call purpose. This endpoint itself does not place calls.", "tags": [ "sendvoicecall" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token of the company. Required.", "example": "YOUR_APIKEY" } }, "required": [ "token" ] } } } } } }, "/api/1.0/webagentsai/getone.json": { "post": { "operationId": "webagentsai_getone", "summary": "Get a single AI agent by ID with a redacted, allowlisted configuration that excludes secrets, credentials, RAG settings, private prompts and webhooks", "tags": [ "webagentsai" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.ai.detail", "x-socket-parity": [ "aiagents_getone" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "agent_ai_id": { "type": "string", "description": "ID of the AI agent to retrieve" } }, "required": [ "token", "agent_ai_id" ] } } } } } }, "/api/1.0/sendvoicecall/createcall.json": { "post": { "operationId": "sendvoicecall_createcall", "summary": "Create a new AI voice call batch campaign that will phone one or more recipients using an AI agent. Use this when the user wants the system to actually place outbound phone calls (e.g. 'call these leads', 'phone these customers', 'launch a reminder call campaign'). MANDATORY WORKFLOW: (1) call /api/1.0/sendvoicecall/listaiagents.json to pick the right 'agent_ai_id' for the campaign's purpose; (2) call /api/1.0/companyuserdata/callerids.json to pick a valid 'caller_id' (one of the company's phone lines allowed to place outbound calls); (3) build the 'recipients' array with one entry per person to call, each with phone (international format, digits only), name and country ISO code. Optionally schedule the campaign: set mode='schedule' plus start_date/start_time/end_time/timezone, or mode='immediately' to dial as soon as the worker picks it up. Returns a batch_id that can be later used with getone.json, stop.json, pause.json and unpause.json. Never invent phone numbers — only use the ones the user explicitly provided or the ones retrieved from a previous query.", "tags": [ "sendvoicecall" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token of the company. Required.", "example": "YOUR_APIKEY" }, "agent_ai_id": { "type": "string", "description": "Mongo ObjectId of the AI voice agent that will conduct the calls. Obtain from /api/1.0/sendvoicecall/listaiagents.json. Required." }, "caller_id": { "type": "string", "description": "Phone number (caller id) the AI will dial out from. Must be one of the callerids available to the company — obtain from /api/1.0/companyuserdata/callerids.json. Can also be a shared caller id in the format 'compartido 999id_campana'. Required." }, "batch_name": { "type": "string", "description": "Human-readable name for this call batch (shown in the UI and reports). Optional." }, "recipients": { "type": "array", "description": "JSON array of call targets. Each element is an object with three string fields: 'phone' (international format, digits only, no '+' and no spaces, e.g. 34660558411), 'name' (display name, e.g. Marc) and 'country' (ISO 3166-1 alpha-2 lowercase, e.g. es, us, mx). At least one recipient is required. Pass it as a real JSON array of objects — do NOT wrap it in a string. See the 'default' field for a concrete example.", "example": [ { "name": "marc", "phone": "34660558411", "country": "es" }, { "name": "James", "phone": "34682288834", "country": "es" } ] }, "mode": { "type": "string", "description": "Dispatch mode. 'immediately' (default) starts dialing as soon as the worker picks up the batch; 'schedule' uses the start_date/start_time/end_time/timezone fields below. Required.", "example": "immediately" }, "timezone": { "type": "string", "description": "IANA timezone for start_date/start_time/end_time when mode='schedule' (e.g. 'Europe/Madrid', 'America/Mexico_City'). Optional, defaults to 'UTC'.", "example": "UTC" }, "start_date": { "type": "string", "description": "Date the campaign can start dialing, in YYYY-MM-DD format. Only used when mode='schedule'. Optional, defaults to today." }, "start_time": { "type": "string", "description": "Earliest hour of the day at which the AI is allowed to place calls, in 24h HH:MM format. Only used when mode='schedule'. Optional, defaults to '10:00'.", "example": "10:00" }, "end_time": { "type": "string", "description": "Latest hour of the day at which the AI is allowed to place calls, in 24h HH:MM format. Only used when mode='schedule'. Optional, defaults to '19:00'.", "example": "19:00" }, "rate_per_minute": { "type": "string", "description": "Maximum number of simultaneous new calls the dialer is allowed to open per minute. Use to throttle spend and avoid carrier rate-limits. Optional, defaults to '30'.", "example": "30" }, "date_start_ms": { "type": "string", "description": "Alternative to start_date/start_time: absolute Unix timestamp in MILLISECONDS (UTC) at which dialing should begin. Optional." } }, "required": [ "token", "agent_ai_id", "caller_id", "recipients", "mode" ] } } } } } }, "/api/1.0/agents/list.json": { "post": { "operationId": "agents_list", "summary": "Get all agents (users) for the company", "tags": [ "agents" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "apibridge_controlListAgentsCore", "x-socket-parity": [ "control_getAgentsTODOSSIEMPRE" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" } }, "required": [ "token" ] } } } } } }, "/api/1.0/departments/list.json": { "post": { "operationId": "departments_list", "summary": "Get all departments for the company", "tags": [ "departments" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "apibridge_controlListDepartmentsCore", "x-socket-parity": [ "control_getDepartmentsall", "control_getAgentsTODOSSIEMPRE" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" } }, "required": [ "token" ] } } } } } }, "/api/1.0/companyuserdata/invoicesget.json": { "post": { "operationId": "invoices_get", "summary": "Get invoices for the authenticated agent, optionally filtered by date range", "tags": [ "companyuserdata" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "date_start": { "type": "string", "description": "Start timestamp for date range filter (optional)" }, "date_end": { "type": "string", "description": "End timestamp for date range filter (optional)" } }, "required": [ "token" ] } } } } } }, "/api/1.0/scripts/create.json": { "post": { "operationId": "scripts_create", "summary": "Create a new script/form with optional inputs definition", "tags": [ "scripts" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.scripts.create", "x-socket-parity": [ "scripts_createscriptmodal", "formsv2_getcreateformScript" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "name": { "type": "string", "description": "Name of the script/form", "example": "My form" }, "description": { "type": "string", "description": "Description (optional)" }, "action": { "type": "string", "description": "Form action type (optional)" }, "msgthanks": { "type": "string", "description": "Thank you message shown after form completion (optional)" }, "msgerrorblank": { "type": "string", "description": "Error message for blank required fields (optional)" }, "inputs": { "type": "object", "description": "Form inputs definition object (optional)", "example": {} }, "form_agent_id": { "type": "string", "description": "Default agent ID for form submissions (optional)" } }, "required": [ "token", "name" ] } } } } } }, "/api/1.0/scripts/edit.json": { "post": { "operationId": "scripts_edit", "summary": "Edit an existing script/form. Only provided fields are updated", "tags": [ "scripts" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.scripts.edit", "x-socket-parity": [ "formsv2_saveform" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "script_id": { "type": "string", "description": "ID of the script/form to edit" }, "name": { "type": "string", "description": "Name of the script/form (optional)" }, "description": { "type": "string", "description": "Description (optional)" }, "action": { "type": "string", "description": "Form action type (optional)" }, "msgthanks": { "type": "string", "description": "Thank you message (optional)" }, "msgerrorblank": { "type": "string", "description": "Error message for blank fields (optional)" }, "inputs": { "type": "object", "description": "Form inputs definition object (optional)", "example": {} }, "form_agent_id": { "type": "string", "description": "Default agent ID for form submissions (optional)" } }, "required": [ "token", "script_id" ] } } } } } }, "/api/1.0/scripts/remove.json": { "post": { "operationId": "scripts_remove", "summary": "Delete a script/form and all its completed submissions and activity records", "tags": [ "scripts" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.scripts.remove", "x-socket-parity": [ "scripts_deletescript" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "script_id": { "type": "string", "description": "ID of the script/form to delete" } }, "required": [ "token", "script_id" ] } } } } } }, "/api/1.0/scripts/viewsends.json": { "post": { "operationId": "scripts_viewsends", "summary": "Get completed form submissions with pagination, date range and search filters", "tags": [ "scripts" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.scripts.submissions", "x-socket-parity": [ "scripts_getscriptscompleted" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "script_id": { "type": "string", "description": "Filter by script/form ID (optional)" }, "date_from": { "type": "string", "description": "Start date for filter in ISO format YYYY-MM-DD (optional)" }, "date_to": { "type": "string", "description": "End date for filter in ISO format YYYY-MM-DD (optional)" }, "filter_field": { "type": "string", "description": "Field identifier in datasform to search in (optional)" }, "search_value": { "type": "string", "description": "Text to search for in the filter_field (optional)" }, "var_resultspage": { "type": "string", "description": "Results per page (default 20)", "example": "20" }, "var_page": { "type": "string", "description": "Page number (default 1)", "example": "1" } }, "required": [ "token", "var_resultspage", "var_page" ] } } } } } }, "/api/1.0/notifications/list.json": { "post": { "operationId": "notifications_list", "summary": "Get notifications for the authenticated agent with pagination", "tags": [ "notifications" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "var_resultspage": { "type": "string", "description": "Results per page (default 20)", "example": "20" }, "var_page": { "type": "string", "description": "Page number (default 1)", "example": "1" }, "read": { "type": "string", "description": "Filter by read status: 0 for unread, 1 for read (optional, returns all by default)" } }, "required": [ "token", "var_resultspage", "var_page" ] } } } } } }, "/api/1.0/notifications/sendpush.json": { "post": { "operationId": "notifications_sendpush", "summary": "Send a push notification to an agent. Same logic as workflows sendnoti block", "tags": [ "notifications" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "title": { "type": "string", "description": "Notification title" }, "text": { "type": "string", "description": "Notification text/body" }, "target_agent_id": { "type": "string", "description": "Agent ID to send the notification to (optional, defaults to self)" }, "assign_to": { "type": "string", "description": "Set to 'current' to send to the lead's owner agent (requires id_lead)" }, "id_lead": { "type": "string", "description": "Lead ID to link in the notification and resolve owner agent (optional)" }, "type": { "type": "string", "description": "Notification type (default 'noti')", "example": "noti" }, "badge": { "type": "string", "description": "Badge letter shown in notification (default 'L')", "example": "L" } }, "required": [ "token", "title", "text", "assign_to", "type", "badge" ] } } } } } }, "/api/1.0/notifications/read.json": { "post": { "operationId": "notifications_read", "summary": "Mark one or all notifications as read", "tags": [ "notifications" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "notification_id": { "type": "string", "description": "ID of a single notification to mark as read (optional if read_all is used)" }, "read_all": { "type": "string", "description": "Set to 'y' to mark all notifications as read" } }, "required": [ "token", "read_all" ] } } } } } }, "/api/1.0/workflows/list.json": { "post": { "operationId": "workflows_list", "summary": "List workflows of the authenticated company so AI/MCP can discover the Mongo `_id` needed by workflows_start and workflows_manualexecute. Filter by `name` with a partial case-insensitive contains match. Optional status filter (0=paused, 1=active). Returns a safe DTO with `_id`, name, status/workflow_status, fortype and queue counters — never the raw block graph. Paginate with perpage (max 5000) and var_page.", "tags": [ "workflows" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "workflows", "total", "total_all", "page", "page_size", "perpage" ], "properties": { "status": { "type": "string", "const": "ok" }, "workflows": { "type": "array", "items": { "type": "object", "required": [ "_id", "name", "status", "workflow_status", "fortype" ], "properties": { "_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$", "description": "Use this value as workflow_id in workflows_start / workflows_manualexecute" }, "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "name": { "type": "string" }, "status": { "type": "integer", "enum": [ 0, 1 ] }, "workflow_status": { "type": "integer", "enum": [ 0, 1 ] }, "fortype": { "type": "string" }, "workflow_fortype": { "type": "string" }, "workflow_onevent": { "type": "string" }, "allow_reregistrations": { "type": "integer" }, "queued": { "type": "integer" }, "queued_bulk": { "type": "integer" }, "created_at": {}, "updated_at": {} } } }, "total": { "type": "integer" }, "total_all": { "type": "integer" }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "perpage": { "type": "integer" } } }, "example": { "status": "ok", "workflows": [ { "_id": "69d9d868740030527e460551", "id": "69d9d868740030527e460551", "name": "Qualified lead follow-up", "status": 0, "workflow_status": 0, "fortype": "leads", "workflow_fortype": "leads", "workflow_onevent": "", "allow_reregistrations": 0, "queued": 0, "queued_bulk": 0, "created_at": null, "updated_at": null } ], "total": 1, "total_all": 12, "page": 1, "page_size": 50, "perpage": 50 } } } }, "400": { "description": "invalid_status | invalid_filter_field | search_too_long: Status is not 0/1, filter field is not name, or the name/search text exceeds 200 characters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "401": { "description": "EMPTY_TOKEN | error_apitokennotfound | client_id_not_found | conflicting_token | token_type_not_allowed | client_disabled | company_not_found | token_company_mismatch: The API token or its tenant binding is invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "403": { "description": "permission_denied | scope_denied: The token user is neither master nor allowed to manage workflows, or the app token lacks workflows scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "500": { "description": "internal_error: Unexpected persistence or query failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.workflows.list", "x-socket-parity": [ "workflows_getWorkflows" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 1 }, "name": { "type": "string", "maxLength": 200 }, "var_workflowsstatus": { "type": "string", "enum": [ "", "0", "1" ] }, "search_value": { "type": "string", "maxLength": 200 }, "filter_typesworkflows": { "type": "string", "enum": [ "", "name" ] }, "perpage": { "type": "integer", "minimum": 1, "maximum": 5000 }, "var_resultspage": { "type": "integer", "minimum": 1, "maximum": 5000 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 5000 }, "var_page": { "type": "integer", "minimum": 1 }, "page": { "type": "integer", "minimum": 1 } } }, "examples": { "example_1": { "summary": "Find workflows by name then activate", "value": { "token": "YOUR_APIKEY", "name": "follow-up", "perpage": 50 } }, "example_2": { "summary": "List only active workflows", "value": { "token": "YOUR_APIKEY", "var_workflowsstatus": "1", "perpage": 100 } } } } } } } }, "/api/1.0/workflows/create.json": { "post": { "operationId": "workflows_create", "summary": "Create a paused workflow. Legacy mode omits definition and creates only the workflow header. Complete versioned mode sends definition.version=1 and atomically creates the header plus a fully validated block graph. Complete mode requires idempotency_key, generates every Mongo ObjectId server-side, enforces tenant/plan boundaries and returns the temporary-key-to-ObjectId map. Both modes always persist workflow status 0.", "tags": [ "workflows" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful idempotent replay", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "workflow_id", "name", "fortype", "workflow_status", "created", "idempotent", "next_steps" ], "properties": { "status": { "type": "string", "const": "ok" }, "workflow_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "name": { "type": "string" }, "fortype": { "type": "string", "enum": [ "leads", "companies", "opportunities", "tickets", "calendar", "budgets", "events" ] }, "workflow_status": { "type": "integer", "const": 0 }, "created": { "type": "boolean" }, "idempotent": { "type": "boolean" }, "definition_version": { "type": "integer", "const": 1 }, "block_ids": { "type": "object", "propertyNames": { "pattern": "^b:[A-Za-z][A-Za-z0-9._-]{0,63}$" }, "additionalProperties": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, "graph": { "type": "object", "additionalProperties": false, "required": [ "entry_key", "entry", "blocks" ], "properties": { "entry_key": { "type": "string", "pattern": "^b:[A-Za-z][A-Za-z0-9._-]{0,63}$" }, "entry": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "blocks": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "additionalProperties": false, "required": [ "key", "id", "block_type", "next_key", "next", "branch_keys", "branches" ], "properties": { "key": { "type": "string" }, "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "block_type": { "type": "string" }, "next_key": { "type": [ "string", "null" ] }, "next": { "oneOf": [ { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, { "type": "null" } ] }, "branch_keys": { "type": "array", "items": { "type": "string" } }, "branches": { "type": "array", "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } } } } } }, "next_steps": { "type": "object", "additionalProperties": false, "required": [ "configure", "activate" ], "properties": { "configure": { "type": "string" }, "activate": { "type": "string" } } } }, "oneOf": [ { "title": "Legacy mode response", "not": { "required": [ "definition_version" ] } }, { "title": "Complete mode response", "required": [ "definition_version", "block_ids", "graph" ] } ] }, "example": { "status": "ok", "workflow_id": "69d9d868740030527e46055a", "name": "Qualified lead follow-up", "fortype": "leads", "workflow_status": 0, "created": true, "idempotent": false, "definition_version": 1, "block_ids": { "b:wait": "69d9d868740030527e46055b", "b:segment": "69d9d868740030527e46055c", "b:email-vip": "69d9d868740030527e46055d", "b:notify-owner": "69d9d868740030527e46055e" }, "graph": { "entry_key": "b:wait", "entry": "69d9d868740030527e46055b", "blocks": [ { "key": "b:wait", "id": "69d9d868740030527e46055b", "block_type": "delay", "next_key": "b:segment", "next": "69d9d868740030527e46055c", "branch_keys": [], "branches": [] }, { "key": "b:segment", "id": "69d9d868740030527e46055c", "block_type": "bifurcation", "next_key": null, "next": null, "branch_keys": [ "b:email-vip", "b:notify-owner" ], "branches": [ "69d9d868740030527e46055d", "69d9d868740030527e46055e" ] }, { "key": "b:email-vip", "id": "69d9d868740030527e46055d", "block_type": "sendemail", "next_key": null, "next": null, "branch_keys": [], "branches": [] }, { "key": "b:notify-owner", "id": "69d9d868740030527e46055e", "block_type": "sendnoti", "next_key": null, "next": null, "branch_keys": [], "branches": [] } ] }, "next_steps": { "configure": "The validated version 1 graph is ready for review.", "activate": "The workflow remains paused until its graph is valid and explicitly started." } } } } }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "workflow_id", "name", "fortype", "workflow_status", "created", "idempotent", "next_steps" ], "properties": { "status": { "type": "string", "const": "ok" }, "workflow_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "name": { "type": "string" }, "fortype": { "type": "string", "enum": [ "leads", "companies", "opportunities", "tickets", "calendar", "budgets", "events" ] }, "workflow_status": { "type": "integer", "const": 0 }, "created": { "type": "boolean" }, "idempotent": { "type": "boolean" }, "definition_version": { "type": "integer", "const": 1 }, "block_ids": { "type": "object", "propertyNames": { "pattern": "^b:[A-Za-z][A-Za-z0-9._-]{0,63}$" }, "additionalProperties": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, "graph": { "type": "object", "additionalProperties": false, "required": [ "entry_key", "entry", "blocks" ], "properties": { "entry_key": { "type": "string", "pattern": "^b:[A-Za-z][A-Za-z0-9._-]{0,63}$" }, "entry": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "blocks": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "additionalProperties": false, "required": [ "key", "id", "block_type", "next_key", "next", "branch_keys", "branches" ], "properties": { "key": { "type": "string" }, "id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "block_type": { "type": "string" }, "next_key": { "type": [ "string", "null" ] }, "next": { "oneOf": [ { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, { "type": "null" } ] }, "branch_keys": { "type": "array", "items": { "type": "string" } }, "branches": { "type": "array", "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } } } } } }, "next_steps": { "type": "object", "additionalProperties": false, "required": [ "configure", "activate" ], "properties": { "configure": { "type": "string" }, "activate": { "type": "string" } } } }, "oneOf": [ { "title": "Legacy mode response", "not": { "required": [ "definition_version" ] } }, { "title": "Complete mode response", "required": [ "definition_version", "block_ids", "graph" ] } ] }, "example": { "status": "ok", "workflow_id": "69d9d868740030527e46055a", "name": "Qualified lead follow-up", "fortype": "leads", "workflow_status": 0, "created": true, "idempotent": false, "definition_version": 1, "block_ids": { "b:wait": "69d9d868740030527e46055b", "b:segment": "69d9d868740030527e46055c", "b:email-vip": "69d9d868740030527e46055d", "b:notify-owner": "69d9d868740030527e46055e" }, "graph": { "entry_key": "b:wait", "entry": "69d9d868740030527e46055b", "blocks": [ { "key": "b:wait", "id": "69d9d868740030527e46055b", "block_type": "delay", "next_key": "b:segment", "next": "69d9d868740030527e46055c", "branch_keys": [], "branches": [] }, { "key": "b:segment", "id": "69d9d868740030527e46055c", "block_type": "bifurcation", "next_key": null, "next": null, "branch_keys": [ "b:email-vip", "b:notify-owner" ], "branches": [ "69d9d868740030527e46055d", "69d9d868740030527e46055e" ] }, { "key": "b:email-vip", "id": "69d9d868740030527e46055d", "block_type": "sendemail", "next_key": null, "next": null, "branch_keys": [], "branches": [] }, { "key": "b:notify-owner", "id": "69d9d868740030527e46055e", "block_type": "sendnoti", "next_key": null, "next": null, "branch_keys": [], "branches": [] } ] }, "next_steps": { "configure": "The validated version 1 graph is ready for review.", "activate": "The workflow remains paused until its graph is valid and explicitly started." } } } } }, "400": { "description": "invalid_fortype | invalid_name | idempotency_key_required | invalid_idempotency_key | unexpected_field | client_supplied_id: Invalid common fields, unsupported fortype, missing complete-mode retry key, unknown input, or an attempt to supply server-owned IDs.; invalid_definition | unsupported_definition_version | invalid_activator | activator_requires_conditions_or_event | workflow_event_requires_events_fortype | events_fortype_requires_workflow_event | invalid_workflow_event | invalid_conditions | invalid_condition_group | invalid_condition | invalid_condition_fortype | invalid_condition_field | invalid_condition_operator | invalid_condition_value: definition.version/activator/condition structure or values are invalid.; invalid_block | invalid_block_type | invalid_block_payload | invalid_json_value | invalid_object_key | payload_field_required | invalid_payload_field | payload_field_too_large | conflicting_payload_fields | invalid_reference_id | duplicate_reference_id | assignment_targets_required | invalid_whatsapp_template_json | webhook_https_required | invalid_webhook_url | webhook_private_destination | webhook_host_not_resolvable: A block payload failed its type-specific allowlist, tenant-reference format, size, assignment, JSON, or public HTTPS webhook validation.; invalid_block_reference | duplicate_block_key | workflow_graph_missing_entry | workflow_graph_missing_reference | workflow_graph_cycle | workflow_graph_orphan_blocks | workflow_graph_multiple_parents | workflow_graph_entry_has_parent | invalid_branch_references | branch_reference_count_mismatch: Temporary b:* references do not form one complete rooted acyclic graph.; reference_not_found_or_cross_tenant: An agent, department or queue reference is absent from the token company; cross-company existence is not disclosed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "401": { "description": "EMPTY_TOKEN | error_apitokennotfound | client_id_not_found | conflicting_token | token_type_not_allowed | client_disabled | company_not_found | token_company_mismatch: Missing or invalid API token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "403": { "description": "permission_denied | scope_denied | plan_restricted: Token user lacks manageworkflows/workflows scope, workflows are disabled by plan, or a multi-object graph is not allowed. Plan lookup fails closed for multi-object workflows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "409": { "description": "workflow_limit_reached | idempotency_conflict: Company reached 500 workflows, or the same idempotency_key was reused with a different normalized payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "413": { "description": "workflow_definition_too_large | workflow_block_too_large | workflow_graph_too_large: Definition exceeds 512 KiB, one payload exceeds 32 KiB, or the graph exceeds 200 blocks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "500": { "description": "internal_error | insert_failed | transaction_not_committed | idempotency_replay_corrupt: Unexpected persistence failure or an incomplete historical idempotency record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } } }, "x-bridge-status": "shared_transactional_core", "x-shared-core": "workflows_createCore + workflows-core.normalizeBlockForMongo", "x-socket-parity": [ "workflows_createnew", "workflows_editandcreate_block" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token", "fortype" ], "properties": { "token": { "type": "string", "minLength": 1 }, "fortype": { "type": "string", "enum": [ "leads", "companies", "opportunities", "tickets", "calendar", "budgets", "events" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" }, "definition": { "type": "object", "additionalProperties": false, "required": [ "version", "activator", "entry", "blocks" ], "properties": { "version": { "type": "integer", "const": 1 }, "activator": { "type": "object", "additionalProperties": false, "properties": { "conditions": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "required": [ "fortype", "identifier", "op", "text" ], "properties": { "fortype": { "type": "string", "enum": [ "leads", "companies", "opportunities", "tickets", "calendar", "budgets", "payments" ] }, "identifier": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_.-]{0,127}$" }, "op": { "type": "string", "enum": [ "in", "nin", "eq", "ne", "re", "gt", "gte", "lt", "lte" ] }, "text": { "oneOf": [ { "type": [ "string", "number", "boolean", "null" ] }, { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": [ "string", "number", "boolean", "null" ] } } ] } } } } }, "workflow_onevent": { "type": "string", "enum": [ "leadexists", "add_budget", "formreceived", "paymentok", "lleidanet_signed" ] } }, "oneOf": [ { "required": [ "conditions" ] }, { "required": [ "workflow_onevent" ] } ] }, "entry": { "type": "string", "pattern": "^b:[A-Za-z][A-Za-z0-9._-]{0,63}$" }, "blocks": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "additionalProperties": false, "required": [ "key", "block_type", "payload" ], "properties": { "key": { "type": "string", "pattern": "^b:[A-Za-z][A-Za-z0-9._-]{0,63}$" }, "block_type": { "type": "string", "enum": [ "delay", "delaycalendar", "propertyset", "propertyclear", "propertynumber", "settoagent", "propertysetapi", "settoagents", "createopportunity", "createtask", "sendnoti", "sendsms", "sendwhatsapp", "lleidanet", "addtoqueue", "sendemail", "webhook", "bifurcation" ] }, "next": { "type": "string", "pattern": "^b:[A-Za-z][A-Za-z0-9._-]{0,63}$" }, "payload": { "description": "Payload is selected by block_type; unknown fields are rejected.", "anyOf": [ { "title": "Delay payload", "type": "object", "additionalProperties": false, "properties": { "days": { "type": "integer", "minimum": 0, "maximum": 364 }, "hours": { "type": "integer", "minimum": 0, "maximum": 23 }, "minutes": { "type": "integer", "minimum": 0, "maximum": 59 } }, "minProperties": 1 }, { "title": "Property mutation payload", "type": "object", "additionalProperties": false, "required": [ "property_fortype", "property_toidentifier" ], "properties": { "property_fortype": { "type": "string", "enum": [ "leads", "opportunities" ] }, "property_toidentifier": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,127}$" }, "value": { "type": [ "string", "number", "boolean", "null" ] } } }, { "title": "Single-agent assignment payload", "type": "object", "additionalProperties": false, "required": [ "property_fortype", "agent_id" ], "properties": { "property_fortype": { "type": "string", "enum": [ "leads", "opportunities" ] }, "agent_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } }, { "title": "API property payload", "type": "object", "additionalProperties": false, "required": [ "property_toidentifier" ], "properties": { "property_fortype": { "type": "string", "const": "leads" }, "property_toidentifier": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,127}$" }, "api_key": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_-]{0,127}$" } } }, { "title": "Agent-pool assignment payload", "type": "object", "additionalProperties": false, "required": [ "property_fortype" ], "properties": { "property_fortype": { "type": "string", "enum": [ "leads", "opportunities" ] }, "agent_ids": { "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } }, "department_ids": { "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } } }, { "title": "Create opportunity payload", "type": "object", "additionalProperties": false, "required": [ "assignment", "pipeline", "status", "amount", "currency" ], "properties": { "assignment": { "type": "string", "enum": [ "current", "asignto", "without" ] }, "agent_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "pipeline": { "type": "string", "maxLength": 128 }, "status": { "type": "string", "maxLength": 128 }, "amount": { "type": [ "string", "number" ] }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "description": { "type": "string", "maxLength": 5000 }, "send_notification": { "type": "boolean" }, "close_after_days": { "type": "integer", "minimum": 1, "maximum": 365 } } }, { "title": "Create task payload", "type": "object", "additionalProperties": false, "required": [ "subject" ], "properties": { "assignment": { "type": "string", "enum": [ "current", "asignto", "without" ] }, "agent_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "priority": { "type": "integer", "minimum": 0, "maximum": 2 }, "status": { "type": "integer", "minimum": 0, "maximum": 99 }, "subject": { "type": "string", "maxLength": 500 }, "text": { "type": "string", "maxLength": 10000 }, "duration_minutes": { "type": "integer", "minimum": 1, "maximum": 525600 }, "schedule_after_minutes": { "type": "integer", "minimum": 0, "maximum": 525600 } } }, { "title": "Notification payload", "type": "object", "additionalProperties": false, "required": [ "title", "text" ], "properties": { "assignment": { "type": "string", "enum": [ "current", "asignto", "without" ] }, "agent_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "title": { "type": "string", "maxLength": 300 }, "text": { "type": "string", "maxLength": 10000 }, "send_notification": { "type": "boolean" } } }, { "title": "SMS payload", "type": "object", "additionalProperties": false, "required": [ "from", "to", "text" ], "properties": { "from": { "type": "string", "maxLength": 16 }, "to": { "type": "string", "enum": [ "client", "agent" ] }, "text": { "type": "string", "maxLength": 765 } } }, { "title": "WhatsApp template payload", "type": "object", "additionalProperties": false, "required": [ "from", "to", "workflowswhatsappjson" ], "properties": { "from": { "type": "string", "maxLength": 128 }, "to": { "type": "string", "enum": [ "client", "agent" ] }, "workflowswhatsappjson": { "oneOf": [ { "type": "object" }, { "type": "string", "maxLength": 20000 } ] }, "workflowswhatstext": { "type": "string", "maxLength": 10000 } } }, { "title": "Lleida.net payload", "type": "object", "additionalProperties": false, "required": [ "lleidanettemplateid", "lleidaneturl" ], "properties": { "lleidanettemplateid": { "type": "string", "pattern": "^\\d+$" }, "lleidaneturl": { "type": "string", "format": "uri", "pattern": "^https://" } } }, { "title": "Queue payload", "type": "object", "additionalProperties": false, "required": [ "queue_id", "priority" ], "properties": { "queue_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "priority": { "type": "integer", "minimum": 1, "maximum": 5 } } }, { "title": "Email payload", "type": "object", "additionalProperties": false, "required": [ "to", "subject", "text" ], "properties": { "to": { "type": "string", "enum": [ "client", "agent", "email" ] }, "emailto": { "type": "string", "format": "email" }, "from": { "type": "string", "maxLength": 320 }, "subject": { "type": "string", "maxLength": 500 }, "text": { "type": "string", "maxLength": 30000 }, "assignment": { "type": "string", "enum": [ "current", "asignto" ] }, "agent_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "tracking": { "type": "boolean" } } }, { "title": "Webhook payload", "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048, "description": "Must resolve exclusively to public, non-loopback addresses." } } }, { "title": "Bifurcation payload", "type": "object", "additionalProperties": false, "required": [ "conditions", "conditions_next" ], "properties": { "conditions": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "fortype", "identifier", "op", "text" ], "properties": { "fortype": { "type": "string" }, "identifier": { "type": "string" }, "op": { "type": "string", "enum": [ "in", "nin", "eq", "ne", "re", "gt", "gte", "lt", "lte" ] }, "text": {} } } } }, "conditions_next": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "pattern": "^b:[A-Za-z][A-Za-z0-9._-]{0,63}$" } } } } ] } } } } } } }, "oneOf": [ { "title": "Legacy header-only mode", "not": { "required": [ "definition" ] } }, { "title": "Complete version 1 mode", "required": [ "idempotency_key", "definition" ] } ] }, "examples": { "example_1": { "summary": "Complete v1 contact workflow with a branch", "value": { "token": "YOUR_APIKEY", "fortype": "leads", "name": "Qualified lead follow-up", "idempotency_key": "workflow:create:qualified-followup:v1", "definition": { "version": 1, "activator": { "conditions": [ [ { "fortype": "leads", "identifier": "status", "op": "eq", "text": "qualified" } ] ] }, "entry": "b:wait", "blocks": [ { "key": "b:wait", "block_type": "delay", "next": "b:segment", "payload": { "minutes": 5 } }, { "key": "b:segment", "block_type": "bifurcation", "payload": { "conditions": [ [ { "fortype": "leads", "identifier": "leadtypedatal", "op": "eq", "text": "vip" } ], [ { "fortype": "leads", "identifier": "leadtypedatal", "op": "ne", "text": "vip" } ] ], "conditions_next": [ "b:email-vip", "b:notify-owner" ] } }, { "key": "b:email-vip", "block_type": "sendemail", "payload": { "to": "client", "subject": "Your account is ready", "text": "We will contact you shortly.
", "assignment": "current", "tracking": true } }, { "key": "b:notify-owner", "block_type": "sendnoti", "payload": { "assignment": "current", "title": "Qualified lead", "text": "A qualified lead requires follow-up.", "send_notification": true } } ] } } }, "example_2": { "summary": "Legacy header-only workflow", "value": { "token": "YOUR_APIKEY", "fortype": "opportunities", "name": "Opportunity won follow-up" } } } } } } } }, "/api/1.0/workflows/start.json": { "post": { "operationId": "workflows_start", "summary": "Activate an existing workflow after validating its complete tenant-owned graph, connected action paths, branches and stored trigger or conditions. Repeating the request when the workflow is already active is safe and returns an idempotent HTTP 200 response.", "tags": [ "workflows" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "workflow_id", "workflow_status", "changed", "idempotent" ], "properties": { "status": { "type": "string", "const": "ok" }, "workflow_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "workflow_status": { "type": "integer", "const": 1 }, "changed": { "type": "boolean" }, "idempotent": { "type": "boolean" } } }, "example": { "status": "ok", "workflow_id": "69d9d868740030527e460551", "workflow_status": 1, "changed": true, "idempotent": false } } } }, "400": { "description": "invalid_workflow_id | invalid_workflow_status: The workflow identifier or requested status is malformed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "401": { "description": "EMPTY_TOKEN | error_apitokennotfound | client_id_not_found | conflicting_token | token_type_not_allowed | client_disabled | company_not_found | token_company_mismatch: The API token or its tenant binding is invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "403": { "description": "permission_denied | scope_denied: The token user is neither master nor allowed to manage workflows, or the app token lacks workflows scope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "404": { "description": "workflow_not_found: No workflow with this ID exists in the authenticated company.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "413": { "description": "workflow_graph_too_large: The stored graph exceeds the 200-block validation limit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "422": { "description": "workflow_actions_required | workflow_graph_foreign_or_missing_block | workflow_graph_cycle | workflow_graph_too_many_branches | workflow_graph_orphan_blocks | workflow_graph_multiple_parents | workflow_graph_incomplete_branches | workflow_action_path_incomplete | invalid_workflow_block_type | invalid_workflow_trigger | invalid_workflow_conditions | workflow_trigger_index_invalid: Activation was refused because the complete stored graph, action paths, branches, trigger or conditions are not executable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "500": { "description": "internal_error: Unexpected persistence failure; workflow status was not intentionally changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.workflows.setStatus", "x-socket-parity": [ "workflows_set_status" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token", "workflow_id" ], "properties": { "token": { "type": "string", "minLength": 1 }, "workflow_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" } } }, "examples": { "example_1": { "summary": "Activate a validated workflow", "value": { "token": "YOUR_APIKEY", "workflow_id": "69d9d868740030527e460551" } } } } } } } }, "/api/1.0/workflows/countrecords.json": { "post": { "operationId": "workflows_countrecords", "summary": "Count records that match the workflow conditions without executing", "tags": [ "workflows" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.workflows.count", "x-socket-parity": [ "workflows_returnsicumplerequisitos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "idworkflow": { "type": "string", "description": "Workflow ID" }, "from": { "type": "string", "description": "Entity type: leads, opportunities, calendar, budgets, companies", "example": "leads" } }, "required": [ "token", "idworkflow", "from" ] } } } } } }, "/api/1.0/workflows/manualexecute.json": { "post": { "operationId": "workflows_manualexecute", "summary": "Enroll existing records that match an active workflow's stored conditions into its manual execution queue. The operation is tenant-scoped, plan-gated, limited to 5,000 records and transactionally idempotent. Omitted or empty scheduling options mean run now in UTC: 00:00-23:59, every day, up to 100 records per minute.", "tags": [ "workflows" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful idempotent replay", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "workflow_id", "execution_job_id", "total", "from", "schedule", "job_status", "created", "idempotent" ], "properties": { "status": { "type": "string", "const": "ok" }, "workflow_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "execution_job_id": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "total": { "type": "integer", "minimum": 0, "maximum": 5000 }, "from": { "type": "string", "enum": [ "leads", "companies", "opportunities", "calendar", "budgets" ] }, "schedule": { "type": "object", "additionalProperties": false, "required": [ "starttime", "endtime", "execution_days", "maxperminute" ], "properties": { "starttime": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "endtime": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "execution_days": { "type": "array", "minItems": 1, "maxItems": 7, "uniqueItems": true, "items": { "type": "string", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ] } }, "maxperminute": { "type": "integer", "minimum": 1, "maximum": 1000 } } }, "job_status": { "type": "string", "enum": [ "queued", "completed", "expired" ] }, "created": { "type": "boolean" }, "idempotent": { "type": "boolean" } } }, "example": { "status": "ok", "workflow_id": "69d9d868740030527e460551", "execution_job_id": "9d8eb790e1be0e710b319fdc40b2c51f5f24f9c92203e02cd0a4c39b6f1ce427", "total": 42, "from": "leads", "schedule": { "starttime": "00:00", "endtime": "23:59", "execution_days": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ], "maxperminute": 100 }, "job_status": "queued", "created": true, "idempotent": false } } } }, "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "workflow_id", "execution_job_id", "total", "from", "schedule", "job_status", "created", "idempotent" ], "properties": { "status": { "type": "string", "const": "ok" }, "workflow_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "execution_job_id": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "total": { "type": "integer", "minimum": 0, "maximum": 5000 }, "from": { "type": "string", "enum": [ "leads", "companies", "opportunities", "calendar", "budgets" ] }, "schedule": { "type": "object", "additionalProperties": false, "required": [ "starttime", "endtime", "execution_days", "maxperminute" ], "properties": { "starttime": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "endtime": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "execution_days": { "type": "array", "minItems": 1, "maxItems": 7, "uniqueItems": true, "items": { "type": "string", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ] } }, "maxperminute": { "type": "integer", "minimum": 1, "maximum": 1000 } } }, "job_status": { "type": "string", "enum": [ "queued", "completed", "expired" ] }, "created": { "type": "boolean" }, "idempotent": { "type": "boolean" } } }, "example": { "status": "ok", "workflow_id": "69d9d868740030527e460551", "execution_job_id": "9d8eb790e1be0e710b319fdc40b2c51f5f24f9c92203e02cd0a4c39b6f1ce427", "total": 42, "from": "leads", "schedule": { "starttime": "00:00", "endtime": "23:59", "execution_days": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ], "maxperminute": 100 }, "job_status": "queued", "created": true, "idempotent": false } } } }, "400": { "description": "invalid_workflow_id | invalid_workflow_source | idempotency_key_required | invalid_idempotency_key | conflicting_idempotency_key | invalid_starttime | invalid_endtime | invalid_execution_window | invalid_execution_days | invalid_maxperminute: A required identifier, source, retry key or UTC scheduling option is missing or malformed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "401": { "description": "EMPTY_TOKEN | error_apitokennotfound | client_id_not_found | conflicting_token | token_type_not_allowed | client_disabled | company_not_found | token_company_mismatch: The API token or its tenant binding is invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "403": { "description": "permission_denied | scope_denied | plan_restricted: The actor lacks workflow-management permission/scope, or the company plan does not enable allow_manual_workflow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "404": { "description": "workflow_not_found: No workflow with this ID exists in the authenticated company.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "409": { "description": "workflow_not_active | bulk_in_progress | idempotency_conflict: The workflow must first be active, another queue is already active for it, or this idempotency key was reused with different normalized parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "413": { "description": "bulk_limit_exceeded | workflow_graph_too_large: More than 5,000 records match, or the stored graph exceeds 200 blocks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "422": { "description": "workflow_source_mismatch | workflow_conditions_not_applicable | invalid_workflow_conditions | workflow_actions_required | workflow_graph_foreign_or_missing_block | workflow_graph_cycle | workflow_graph_too_many_branches | workflow_graph_orphan_blocks | workflow_graph_multiple_parents | workflow_graph_incomplete_branches | workflow_action_path_incomplete | invalid_workflow_block_type | invalid_workflow_trigger | workflow_trigger_index_invalid: The stored source, conditions, trigger or complete action graph cannot safely drive a manual execution.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "500": { "description": "queue_commit_failed | internal_error: The transactional job/queue write failed; a retry with the same idempotency key is safe.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "503": { "description": "queue_safety_unavailable: Required unique/TTL queue indexes could not be verified, so no queue was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } } }, "x-bridge-status": "shared_transactional_core", "x-shared-core": "domainBridgeCores.workflows.manualExecute", "x-socket-parity": [ "workflows_returnsicumplerequisitos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token", "workflow_id", "from", "idempotency_key" ], "properties": { "token": { "type": "string", "minLength": 1 }, "workflow_id": { "type": "string", "pattern": "^[a-fA-F0-9]{24}$" }, "from": { "type": "string", "enum": [ "leads", "companies", "opportunities", "calendar", "budgets" ] }, "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" }, "starttime": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "endtime": { "type": "string", "pattern": "^(?:[01][0-9]|2[0-3]):[0-5][0-9]$" }, "maxperminute": { "type": "integer", "minimum": 1, "maximum": 1000 }, "execution_days": { "type": "array", "minItems": 1, "maxItems": 7, "uniqueItems": true, "items": { "type": "string", "enum": [ "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" ] } } } }, "examples": { "example_1": { "summary": "Enroll matching leads for execution now", "value": { "token": "YOUR_APIKEY", "workflow_id": "69d9d868740030527e460551", "from": "leads", "idempotency_key": "workflow:manual:qualified-leads:2026-07-26" } } } } } } } }, "/api/1.0/workflows/viewexecutations.json": { "post": { "operationId": "workflows_viewexecutations", "summary": "View workflow execution history with enriched lead/opportunity/task data", "tags": [ "workflows" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.workflows.history", "x-socket-parity": [ "workflows_verhistorial" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "workflow_id": { "type": "string", "description": "Workflow ID to view history for" } }, "required": [ "token", "workflow_id" ] } } } } } }, "/api/1.0/hrshifts/list.json": { "post": { "operationId": "hrshifts_list", "summary": "List HR shifts for given days with optional agent and status filters", "tags": [ "hrshifts" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "shared_core", "x-shared-core": "domainBridgeCores.hr.shifts", "x-socket-parity": [ "hr_getshifts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "array_days_toshow": { "type": "array", "description": "Array of day strings in dd/mm/yyyy format to filter shifts" }, "agent_id": { "type": "string", "description": "Filter by specific agent ID (optional)" }, "iserro": { "type": "string", "description": "Filter by error status (optional)" }, "saved": { "type": "string", "description": "Filter by saved status (optional)" }, "isholidays": { "type": "string", "description": "Filter by holidays status (optional)" } }, "required": [ "token", "array_days_toshow" ] } } } } } }, "/api/1.0/hrshifts/create.json": { "post": { "operationId": "hrshifts_create", "summary": "Create one or many HR shifts in a single atomic request using the same shared core as the live hrshifts_createshift socket. The token user must be master or admin; admins may only target agents inside their authorized departments. Dates use the existing d/m/yyyy socket format (for example 20/7/2026). Each agent's current workplace/timezone is resolved server-side; an optional workplace must match every selected agent. If starttime is equal to or later than endtime, the shift ends the following day. HTTP API creates shifts as saved='y' (published); the live socket UI keeps drafts saved='n'. New shifts are iserro='n'.", "tags": [ "hrshifts" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "invalid_agents_ids | invalid_days | invalid_time | invalid_comment | invalid_saved | invalid_iserro | invalid_idempotency_key | agent_workplace_not_configured | workplace_not_found | workplace_mismatch | invalid_datetime: Input failed validation or selected agents/workplace are inconsistent", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "401": { "description": "EMPTY_TOKEN | error_apitokennotfound | client_id_not_found: Missing or invalid token", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "403": { "description": "permission_denied | permission_denied_agent | scope_denied: User is not master/admin or targets an agent outside department scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "409": { "description": "duplicate_shift | idempotency_conflict: An identical timeslot already exists or retry key was reused with changed payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "413": { "description": "too_many_shifts: More than 500 agent×day combinations", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } }, "500": { "description": "internal_error | insert_failed: Transactional persistence failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "error": { "type": "string" } } } } } } }, "x-bridge-status": "shared_core", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token. User must be master/admin; scoped app tokens require 'hrshifts'. Required.", "example": "YOUR_APIKEY" }, "agents_ids": { "type": "array", "description": "Unique agent IDs in the same company and authorized department scope. 1-50 required.", "example": [ "689db0a79957d10338d7e60a" ] }, "daystopublish": { "type": "array", "description": "Unique dates in d/m/yyyy or dd/mm/yyyy format. 1-93 required; agent×day combinations max 500.", "example": [ "20/7/2026" ] }, "starttime": { "type": "string", "description": "Start time HH:MM (24-hour). Required.", "example": "05:18" }, "endtime": { "type": "string", "description": "End time HH:MM. Required. Equal/earlier than start means next-day end.", "example": "05:18" }, "workplace": { "type": "string", "description": "Optional compatibility field from modal/hrshifts: must match every selected agent's current workplace. Timezone is always loaded server-side. (optional)", "example": "679383c5e5002a43d9562657" }, "comment": { "type": "string", "description": "Optional plain-text comment, max 500; HTML/control characters rejected. (optional)" }, "idempotency_key": { "type": "string", "description": "Optional stable retry key, 8-128 safe characters. Same key+payload returns original IDs; changed payload returns conflict. (optional)", "example": "hrshift:create:20-7-2026:0518" } }, "required": [ "token", "agents_ids", "daystopublish", "starttime", "endtime" ] }, "examples": { "example_1": { "summary": "Create shift using the live socket-compatible format", "value": { "token": "YOUR_APIKEY", "agents_ids": [ "689db0a79957d10338d7e60a" ], "daystopublish": [ "20/7/2026" ], "starttime": "05:18", "endtime": "05:18", "workplace": "679383c5e5002a43d9562657", "comment": "", "idempotency_key": "hrshift:create:20-7-2026:0518" } } } } } } } }, "/api/1.0/costexplorer/get.json": { "post": { "operationId": "costexplorer_get", "summary": "Get aggregated cost/usage data from the calls_leads collection grouped by configurable dimensions with a date range filter. By default returns only real communication records (answered/received calls, SMS, WhatsApp) grouped by agent_id and type — excludes AI, file, payment, credit and other internal service types unless explicitly overridden via service_type. Date range must be within a single calendar year. Only master/admin users can call this endpoint. Use this to answer questions like 'cost of calls per agent this month', 'total SMS cost by country', or 'which agent spent most credits on callouts'.", "tags": [ "costexplorer" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "datestart_unix": { "type": "number", "description": "Start date as UNIX timestamp in seconds UTC (inclusive). Example: 1767225600 corresponds to 2026-01-01 00:00 UTC." }, "dateend_unix": { "type": "number", "description": "End date as UNIX timestamp in seconds UTC (exclusive). Example: 1769904000 corresponds to 2026-02-01 00:00 UTC." }, "group_by": { "type": "array", "description": "Array of dimensions to group by. Allowed values: type, country, agent_id, month, day, hour, phone, destination. Default when omitted: [\"agent_id\",\"type\"] — aggregates cost per agent and per service type.", "example": "[\"agent_id\",\"type\"]" }, "service_type": { "type": "array", "description": "Filter by call types (optional). Default when omitted: [\"callout\",\"callin\",\"callpush\",\"callai\",\"sms\",\"smsin\",\"whatsapp\"] — aggregates received/answered calls (incl. AI voice), SMS and WhatsApp (excludes ai, aitts, payment, credit, file, etc). Allowed values in DB: callout, callin, callpush (AI push/vozpush call), callai (AI voice call), sms, smsin, whatsapp, ai, aitts, payment, credit, file, calendar, sale, ticket, emailin, emailout, emailreaded, form_completed, budget-status, fbleads, cli2cal, voiceline (monthly subscription fee of each phone line, one record per line and month). Note: callpush and callai are distinct AI voice service types, each grouped and labeled separately (not merged into 'ai').", "example": "[\"callout\",\"callin\",\"callpush\",\"callai\",\"sms\",\"smsin\",\"whatsapp\"]" }, "var_agents_id": { "type": "array", "description": "Filter by agent IDs (optional, admin/master only). Admin users are limited to agents in their department." }, "collapse_by": { "type": "array", "description": "Re-aggregate results by these dimensions after initial grouping (optional). Subset of group_by dimensions." }, "timezone": { "type": "string", "description": "Timezone for date range validation (optional, example: Europe/Madrid). Used to ensure the date range stays within a single calendar year in the user's local timezone. Defaults to UTC if omitted or invalid.", "example": "Europe/Madrid" } }, "required": [ "token", "datestart_unix", "dateend_unix", "group_by" ] } } } } } }, "/api/1.0/costexplorer/getlistcallsleads.json": { "post": { "operationId": "costexplorer_getlistcallsleads", "summary": "Get call records grouped by agent and country with cost calculated from per-credit tariff. Dates in UNIX UTC seconds", "tags": [ "costexplorer" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "datestart_unix": { "type": "number", "description": "Start date as UNIX timestamp UTC seconds (inclusive)" }, "dateend_unix": { "type": "number", "description": "End date as UNIX timestamp UTC seconds (inclusive)" }, "service_type": { "type": "array", "description": "Filter by call types array e.g. ['callout','callin','sms'] (optional, returns all types if empty). callpush (AI push/vozpush call) and callai (AI voice call) are distinct service types." }, "var_agentfilterpayments": { "type": "string", "description": "Filter by single agent ID (optional)" }, "var_agents_id": { "type": "array", "description": "Filter by multiple agent IDs (optional)" }, "timezone": { "type": "string", "description": "Timezone for date filtering (optional, example: Europe/Madrid)" } }, "required": [ "token", "datestart_unix", "dateend_unix" ] } } } } } }, "/api/1.0/costexplorer/calls.json": { "post": { "operationId": "costexplorer_calls", "summary": "Call report: returns a paginated, redacted list of communication records (inbound/outbound calls, AI voice calls, SMS and WhatsApp) for a date range of at most 93 days, plus aggregate stats. Agent RBAC is applied automatically. Recordings, provider internals and non-communication service records are never returned.", "tags": [ "costexplorer" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-bridge-status": "verified_http_read", "x-shared-core": "app-express:costexplorer_calls", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" }, "datestart_unix": { "type": "number", "description": "Required start date as UNIX timestamp UTC seconds (inclusive). Together with dateend_unix it must define a valid range of at most 93 days.", "example": 1767225600 }, "dateend_unix": { "type": "number", "description": "Required end date as UNIX timestamp UTC seconds (inclusive), greater than datestart_unix and at most 93 days later.", "example": 1769817599 }, "service_type": { "type": "array", "description": "Filter by communication type (optional). Allowed values only: callout, callin, callpush, callai, sms, smsin, whatsapp. Defaults to all seven. Non-communication records are rejected.", "example": [ "callout", "callin", "callpush", "callai", "sms", "smsin", "whatsapp" ] }, "status": { "type": "string", "description": "Filter by call status (optional). Common values: ANSWER (answered), NO ANSWER, BUSY, FAILED, CANCEL" }, "phone": { "type": "string", "description": "Filter by phone number substring (optional, case insensitive)" }, "var_agents_id": { "type": "array", "description": "Filter by agent IDs (optional). Ignored for agent-type users (they only see their own calls). Admin users are limited to agents in their department." }, "page": { "type": "number", "description": "Page number, starts at 1 (optional, default 1)", "example": 1 }, "pageSize": { "type": "number", "description": "Records per page, between 10 and 100 (optional, default 50)", "example": 50 }, "timezone": { "type": "string", "description": "Timezone for date filtering context (optional, example: Europe/Madrid).", "example": "Europe/Madrid" } }, "required": [ "token", "datestart_unix", "dateend_unix" ] } } } } } }, "/api/1.0/companyuserdata/myuserdata.json": { "post": { "operationId": "companyuserdata_myuserdata", "summary": "Get the full authenticated agent/user record from the clients collection", "tags": [ "companyuserdata" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token", "example": "YOUR_APIKEY" } }, "required": [ "token" ] } } } } } }, "/api/1.0/calendarwidget/getconfigurationbookingcalendar.json": { "get": { "operationId": "calendarwidget_get_config", "summary": "Get public calendar configuration. Returns availability ranges (per-day, minutes from midnight), duration, timezone and company logo. Calendar must have enabled=true. No authentication required (public endpoint).", "tags": [ "calendarwidget" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "bookingId", "in": "query", "required": true, "description": "Calendar widget ObjectId (query param)", "schema": { "type": "string" } } ] } }, "/api/1.0/calendarwidget/availabilityByDay.json": { "get": { "operationId": "calendarwidget_availability", "summary": "Get available time slots for a specific date. Returns UTC ISO slots filtered by agent availability. How it works: 1) Load calendar config 2) Check enabled=true 3) Get availability ranges for the day of week 4) Generate slots every {duration} minutes within each range 5) Filter out past slots 6) For each slot check if at least ONE assigned agent has no conflicting task in calendar collection 7) Return available slots as UTC ISO strings. No authentication required (public endpoint).", "tags": [ "calendarwidget" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "parameters": [ { "name": "bookingId", "in": "query", "required": true, "description": "Calendar widget ObjectId (query param)", "schema": { "type": "string" } }, { "name": "selectedDay", "in": "query", "required": true, "description": "Date in YYYY-MM-DD format (query param)", "schema": { "type": "string", "example": "2026-03-30" } }, { "name": "timezone", "in": "query", "required": false, "description": "IANA timezone string (optional query param, auto-detected from company country if not sent)", "schema": { "type": "string", "example": "Europe/Madrid" } } ] } }, "/api/1.0/calendarwidget/booking.json": { "post": { "operationId": "calendarwidget_create_booking", "summary": "Create an appointment booking. How it works: 1) Load calendar config, check enabled=true 2) Calculate UTC start/end from start_time + duration 3) Find assigned agents 4) Check which agents already have a task at that date+time 5) Pick first free agent 6) Detect existing lead by phone then by email 7) If no lead found create new lead (source: calendarwidget) 8) Create calendar task via appexpress_modal_addcalendar() 9) Return agent info. No authentication required (public endpoint).", "tags": [ "calendarwidget" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "booking_id": { "type": "string", "description": "Calendar widget ObjectId" }, "start_time": { "type": "string", "description": "ISO 8601 UTC datetime of the chosen slot (e.g. 2026-03-30T09:00:00.000Z)" }, "timezone": { "type": "string", "description": "IANA timezone string (optional, auto-detected from company country if not sent)", "example": "Europe/Madrid" }, "contact": { "type": "object", "description": "Contact info object: { name: string, email: string, phone: string (with intl prefix), country: string (ISO 2-char code), notes: string }", "example": { "name": "John Doe", "email": "john@example.com", "phone": "+34600000000", "country": "es", "notes": "" } } }, "required": [ "booking_id", "start_time", "contact" ] } } } } } }, "/api/1.0/entities/schemas.json": { "post": { "operationId": "entities_get_schemas", "summary": "Discover ALL CRM entities and their complete schemas in one call. This is the mandatory entry point for AI assistants and MCP integrations before reading or writing records. The built-in record entities (leads/contacts, companies, opportunities, tasks, tickets, and — when the deployment enables finance entities — budgets and payments) and every custom entity (cust_...) expose the SAME record contract: properties contains the exact identifiers accepted inside values; direct associations are writable properties of type 'association'; statusgroups tells which value to send for each status field; and record_api contains the same generic endpoints to list, get, create, edit, delete, read activity and add notes. Status value rule: mode='index' -> send legacyIndex, mode='id' -> send id, mode='value' -> send id/value, always under values[statusgroups[].docField]. Properties with read_only=true must not be written. Budgets and payments: check record_api.supported per entity — when true they use the same generic record endpoints (budgets add a 'lineitems' property 'concepts' whose value is an array of row objects following properties.concepts.lineitems.columns, and payments amounts are declared stored_as='string' but always read and written as numbers here); when false they keep their document-specific endpoints listed in record_api. Budgets id_lead/idsale are set at creation and immutable afterwards; payments create is also available via the specific endpoint /api/1.0/payments/create.json (contract unchanged). GET is also supported with token in the query string. EVERY property always includes required:'y'|'n' and unique:'y'|'n' for both system and custom entities; omitted internal flags are normalized to 'n'.", "tags": [ "entities" ], "x-enabled-for-ai-assistant": true, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "API access token of the company. Required.", "example": "YOUR_APIKEY" } }, "required": [ "token" ] }, "examples": { "example_1": { "summary": "Get all entities and schemas", "value": { "token": "YOUR_APIKEY" } } } } } } }, "get": { "operationId": "entities_get_schemas_get", "summary": "Discover ALL CRM entities and their complete schemas in one call. This is the mandatory entry point for AI assistants and MCP integrations before reading or writing records. The built-in record entities (leads/contacts, companies, opportunities, tasks, tickets, and — when the deployment enables finance entities — budgets and payments) and every custom entity (cust_...) expose the SAME record contract: properties contains the exact identifiers accepted inside values; direct associations are writable properties of type 'association'; statusgroups tells which value to send for each status field; and record_api contains the same generic endpoints to list, get, create, edit, delete, read activity and add notes. Status value rule: mode='index' -> send legacyIndex, mode='id' -> send id, mode='value' -> send id/value, always under values[statusgroups[].docField]. Properties with read_only=true must not be written. Budgets and payments: check record_api.supported per entity — when true they use the same generic record endpoints (budgets add a 'lineitems' property 'concepts' whose value is an array of row objects following properties.concepts.lineitems.columns, and payments amounts are declared stored_as='string' but always read and written as numbers here); when false they keep their document-specific endpoints listed in record_api. Budgets id_lead/idsale are set at creation and immutable afterwards; payments create is also available via the specific endpoint /api/1.0/payments/create.json (contract unchanged). GET is also supported with token in the query string. EVERY property always includes required:'y'|'n' and unique:'y'|'n' for both system and custom entities; omitted internal flags are normalized to 'n'.", "tags": [ "entities" ], "x-enabled-for-ai-assistant": false, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-ai-disabled-reason": "http_method_alias_use_post_tool", "x-ai-alias-of": "POST /api/1.0/entities/schemas.json", "parameters": [ { "name": "token", "in": "query", "required": true, "description": "API access token of the company. Required.", "schema": { "type": "string", "example": "YOUR_APIKEY" } } ] } }, "/api/1.0/entities/getrecords.json": { "post": { "operationId": "entities_get_records", "summary": "Search and list records through one POST endpoint for contacts (entitykey 'leads'), companies, opportunities, tasks, tickets and every custom entity (cust_...). Call schemas.json first, then use its property identifiers in filters/orderby. Filters support eq, ne, in, nin, gt, gte, lt, lte and re, including several operators on one field for ranges. The response has one stable shape for system and custom entities: clean records with id, schema properties, assignment fields, epoch-second dates, resolved