4. Handoff Request Schema

This document describes the JSON structure required when calling:

POST | https://docendorse.com/api/v1/agent-sessions/create

Your request body must follow this schema. Some fields are required, while others are optional but recommended.

Top-Level Structure

Example full request:

{
  "handoff_id": "acme-7f3b2d2ca11qiqi",
  "intent": "send_e_sign_request",
  "actor": {
    "external_user_id": "usr_123",
    "display_name": "Sam",
    "email": "sam@example.com"
  },
  "integration": {
    "source": "customer_chat_ui",
    "source_conversation_id": "conv_9981",
    "source_message_id": "msg_555"
  },
  "context": {
    "summary": "User negotiated a UK NDA and wants to send it for signature immediately."
  },
  "facts": {
    "metadata": {
      "title": "UK NDA Agreement",
      "message": "Please review and sign."
    }
  },
  "files": [
    {
      "type": "url",
      "name": "contract.pdf",
      "url": "https://example.com/contract.pdf"
    }
  ]
}

Required Top-Level Fields

The following fields are mandatory:

Field Breakdown

1. handoff_id (Required)

A unique identifier from your system.

Example:

"handoff_id": "acme-7f3b2d2ca11qiqi"

This allows you to correlate the agent session with your internal records.

2. intent (Required)

Defines what action the AI agent should perform.

Allowed values:

• send_e_sign_request
• create_template
• use_template
• self_sign
• send_crm_deal_document_for_signature

Example:

"intent": "send_e_sign_request"

3. actor (Required)

Represents the end user on whose behalf the session is being created.

Structure:

{
  "actor": {
    "external_user_id": "usr_123",
    "display_name": "Sam",
    "email": "sam@example.com"
  }
}

Requirements:

• external_user_id: minimum 3 characters
• email: must be valid email format
• display_name: optional but recommended

4. integration (Required)

Identifies the source system and conversation context.

Structure:

{
  "integration": {
    "source": "customer_chat_ui",
    "source_conversation_id": "conv_9981",
    "source_message_id": "msg_555"
  }
}

Requirements:

• source: Name of your platform
• source_conversation_id: Unique conversation ID
• source_message_id: Message that triggered the handoff

This ensures traceability between your system and the AI agent.

5. context (Required)

Provides the AI agent with sufficient information to understand the request.

Minimum required structure:

{
  "context": {
    "summary": "User negotiated a UK NDA and needs to send it for signature."
  }
}

summary

• Required
• Minimum 1 character
• Maximum 5000 characters

This is critical for AI understanding.

6. facts (Optional)

Structured data to help pre-fill signing details.

Example:

{
  "facts": {
    "metadata": {
      "title": "UK NDA Agreement",
      "message": "Please review and sign."
    },
    "parties": [
      {
        "name": "Jane Doe",
        "email": "janedoe@yahoo.com"
      }
    ],
    "dates": {
      "effective_date": "2026-03-01"
    }
  }
}

metadata (Required if facts provided)

• title (required)
• message (optional)

parties (Optional)

Each party must include:

• name
• email (valid format)
• telephone (optional, E.164 format)

dates (Optional)

• effective_date (ISO date format YYYY-MM-DD)

7. files (Optional)

Attach files for signing.

Example:

{
  "files": [
    {
      "type": "url",
      "name": "contract.pdf",
      "url": "https://example.com/contract.pdf"
    }
  ]
}

Requirements:

• type (required)
• name (required)
• url (must be valid URI)
• File must be accessible by the DocEndorse system

Validation Rules

• Required fields must be present.
• Email fields must be valid.
• Dates must follow ISO format.
• Unknown fields are allowed.
• Strings must respect length limits where defined.

Invalid requests will return:

{
  "status": "error",
  "description": "Validation error explanation"
}