3. Creating an AI Agent Session (Handoff)

After obtaining an access token, you can create an AI agent session by calling the handoff endpoint.

This endpoint initializes the e-sign workflow and prepares the AI agent to continue the interaction with your user.

Endpoint

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

Authentication

You must include your OAuth access token in the Authorization header:

Authorization: Bearer ACCESS_TOKEN

You must also include:

Content-Type: application/json

Required Fields

The following fields are required in the request body:

handoff_id
actor
integration
intent
context

Optional fields:

files
facts

Minimal Example (Send E-Sign Request)

Below is a minimal working example using curl.

curl -X POST https://docendorse.com/api/v1/agent-sessions/create \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "handoff_id": "acme-7f3b2d2ca11qiqi",
    "intent": "send_e_sign_request",
    "actor": {
      "external_user_id": "usr_hahua8h7",
      "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."
    }
  }'

Example Including Files

You can attach files using publicly accessible URLs.

curl -X POST https://docendorse.com/api/v1/agent-sessions/create \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "handoff_id": "acme-82h2kdl992",
    "intent": "send_e_sign_request",
    "actor": {
      "external_user_id": "usr_hahua8h7",
      "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 needs to send a rental agreement to Jane Doe."
    },
    "files": [
      {
        "type": "url",
        "name": "rental_agreement.pdf",
        "url": "https://example.com/rental_agreement.pdf"
      }
    ]
  }'

Example Including Structured Facts

Structured facts allow you to pre-fill signing information for the AI agent.

curl -X POST https://docendorse.com/api/v1/agent-sessions/create \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "handoff_id": "acme-structured-001",
    "intent": "send_e_sign_request",
    "actor": {
      "external_user_id": "usr_hahua8h7",
      "display_name": "Sam",
      "email": "sam@example.com"
    },
    "integration": {
      "source": "customer_chat_ui",
      "source_conversation_id": "conv_9981",
      "source_message_id": "msg_555"
    },
    "context": {
      "summary": "Send NDA to contractor Jane Doe."
    },
    "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"
      }
    }
  }'