Free setup on annual plans

Sign up today!
Book a Demo

Documents

Home

> API Reference >

Endpoints >

Documents

API Reference: Documents endpoints

The Documents API manages static prompt content, reusable knowledge snippets and dynamic data-retrieval definitions for the authenticated customer. The current implementation also exposes document conversion, topic-document links and hook-document prompt retrieval.

Overview

A document can be plain content used in prompts, a realtime instruction source, or a data-retrieval process that calls an external system. All document management endpoints require the ManageSettings policy. Topic and hook document links determine where a document is made available during topic handling, channel-specific flows and workflow hook execution.

Current endpoints

Document records

  • GET /api/Documents – ManageSettings
    Return a paginated list of documents for the authenticated customer. Query supports pageNumber, pageSize, sortBy and sortOrder.
  • POST /api/Documents – ManageSettings
    Create a document or data-retrieval definition. The API sets customerID, creationDate and lastModifiedDate.
  • GET /api/Documents/{id} – ManageSettings
    Return one document. Optional query replacePlaceholders=true replaces special placeholders such as {{TopicList}} in the content.
  • PUT /api/Documents/{id} – ManageSettings
    Update a document and optionally synchronize custom field requirements. A null customFieldRequirements value leaves requirements unchanged; an empty array clears them.
  • DELETE /api/Documents/{id} – ManageSettings
    Delete one document for the authenticated customer.

Convert upload

  • POST /api/Documents/convert – ManageSettings
    Upload a Word or Excel file as multipart/form-data field file. The API converts supported files to markdown and returns { markdown }. Maximum upload size is 50 MB.

TopicDocuments

TopicDocuments link documents to topics, special topics, channels or special channels.

  • GET /api/TopicDocuments – Bearer JWT
    List topic-document links. Filters include topicId, documentId, channelId, hookName, isHook, pageNumber, pageSize, sortBy and sortOrder.
  • POST /api/TopicDocuments – Bearer JWT
    Create one topic-document link. Duplicate combinations return 409 Conflict.
  • POST /api/TopicDocuments/bulk – Bearer JWT
    Create multiple topic-document links. Duplicate existing combinations fail the bulk create.
  • GET /api/TopicDocuments/{id} – Bearer JWT
    Read one topic-document link scoped to the authenticated customer.
  • PUT /api/TopicDocuments/{id} – Bearer JWT
    Update the document link fields for a topic, special topic, channel or special channel combination.
  • DELETE /api/TopicDocuments/{id} – Bearer JWT
    Delete one topic-document link.

HookDocuments

HookDocuments use topic-document records for workflow hook prompt documents.

  • GET /api/HookDocuments/promptDocuments – TicketAccessOrPhoneAuth
    Return prompt documents for a hookName and optional channelId. Phone-auth requests are restricted to the token channel.
  • POST /api/HookDocuments – Bearer JWT
    Create a hook-document link using the same TopicDocumentCreateDTO shape. For hooks, topicID should be null and specialTopic should hold the hook name.

Auth and access

  • Inbound API authentication
    Use JWT Bearer authentication. Document API credentials are not used to authenticate inbound AnswerPal API calls.
  • Outbound API configuration
    overrideApiBaseUrl, overrideApiUsername, overrideApiPassword, overrideApiToken and overrideApiAuthenticationType are used when AnswerPal calls external APIs for data retrieval.
  • Hook document phone auth
    GET /api/HookDocuments/promptDocuments accepts ticket access or phone-auth context. A phone-auth token cannot request documents for a different channel.

Errors

  • 400 Bad Request
    Invalid document DTO, custom field requirement that does not belong to the customer, missing upload file, file over 50 MB, unsupported Office file or failed conversion.
  • 403 Forbidden
    Phone-auth hook document request uses a channel different from the token channel.
  • 404 Not Found
    Document, topic-document link or hook-document link does not exist in the authenticated customer scope.
  • 409 Conflict
    Duplicate topic-document or hook-document combination.
  • 500 Server Error
    Unexpected database error during topic-document creation, bulk creation, update or delete.

Fields and DTOs

Document fields

Core document fields

  • documentID
    Response-only identifier for the document or data-retrieval definition.
  • name
    Required string, max 100. Display name for the document.
  • description, content
    Optional descriptive text and prompt/document content.
  • isDataRetrievalProcess
    Marks the record as a data-retrieval process rather than a static document.
  • includeInRealtimeInstructions
    Allows retrieved content to be retained in phone realtime instructions.
  • creationDate, lastModifiedDate
    Response-only timestamps set by the API.

Outbound API and function-tool fields

  • overrideApiBaseUrl, overrideApiUsername, overrideApiPassword, overrideApiToken, overrideApiAuthenticationType
    Outbound connector overrides for this document/data-retrieval process.
  • apiEndpoint, apiMethod, apiHeaders, apiBodyTemplate
    External API call definition. apiHeaders is JSON text.
  • fieldMapping
    Optional mapping from retrieved data into fields used by prompts or actions.
  • isFunctionTool, functionParametersSchema, toolCallTimeoutSeconds
    Function-tool configuration and timeout.

Custom field fields

  • customFieldDefinitions
    Returned on detailed reads to show available custom field definitions for the customer.
  • customFieldRequirements
    Create/update list of required custom field definitions for this document. Null leaves existing requirements unchanged; empty array clears them.
  • documentCustomFieldRequirementID, customFieldDefinitionID, isRequired, fieldName, displayName, fieldType, description
    Fields on DocumentCustomFieldRequirementDTO.

TopicDocument and prompt fields

TopicDocument fields

  • topicDocumentID, customerID
    Response-only link identifier and customer scope.
  • topicID, specialTopic
    Topic target. topicID can be null; specialTopic supports values such as All or a hook name.
  • documentID
    Required document being linked.
  • channelID, specialChannel
    Optional channel-specific target. specialChannel can be All or a channel type.
  • topicName, documentName, channelName
    Response-only display names.

PromptDocument response fields

  • documentID, name, content, contentType
    Prompt document identity and content.
  • includeInRealtimeInstructions, imageUrls
    Realtime instruction flag and image URLs associated with the prompt content.

Example requests

Create a data-retrieval document

{
  "name": "Order status lookup",
  "description": "Fetches the current order status",
  "content": null,
  "isDataRetrievalProcess": true,
  "apiEndpoint": "https://erp.example.com/orders/{{orderNumber}}",
  "apiMethod": "GET",
  "apiHeaders": "{\"Accept\":\"application/json\"}",
  "fieldMapping": "{\"status\":\"$.status\"}",
  "isFunctionTool": true,
  "functionParametersSchema": "{\"type\":\"object\",\"properties\":{\"orderNumber\":{\"type\":\"string\"}}}",
  "toolCallTimeoutSeconds": 30
}

Convert an Office file to markdown

POST /api/Documents/convert
Authorization: Bearer <token>
Content-Type: multipart/form-data

file=@policy.docx

Get hook prompt documents

GET /api/HookDocuments/promptDocuments?hookName=OnPhonePickup&channelId=3
Authorization: Bearer <token>

FAQ

A static document contributes prompt or knowledge content directly. A data-retrieval process sets isDataRetrievalProcess=true and defines outbound API-call fields such as apiEndpoint, apiMethod, headers, body template and field mapping.

Yes. GET /api/Documents/{id}?replacePlaceholders=true replaces special placeholders such as {{TopicList}} before returning content.

Use /api/TopicDocuments for topic/channel links and /api/HookDocuments for hook prompt-document flows. Both use the TopicDocument link model.

Inbound AnswerPal API requests use JWT Bearer authentication. The document fields overrideApiAuthenticationType, overrideApiUsername, overrideApiPassword and overrideApiToken are outbound settings used when AnswerPal calls an external API.

Need help?

Contact Support

Table of Contents

AnswerPal: AI-powered customer service solutions to elevate your support and communication effortlessly.

Quick Links

Contact

For all support, sales, and partnership inquiries, email us at info@answerpal.eu

AnswerPal
Bisschoppenhoflaan 380
2100 Antwerp
Belgium

+32.36416685

BE 0862.692.858

Social Icons