5. Handling Handoff Responses

After calling the agent session creation endpoint, the API will return a JSON response.

You must inspect:

• status
• next_action
• Additional fields depending on the status

Your system must take the correct action based on the response.

Response Structure

Example base response:

{
  "status": "success",
  "next_action": "continue_handoff",
  "agent_session_id": "as_123456",
  "handoff_uri": "https://app.docendorse.com/agent/xyz"
}

Status: success

Example Response:

{
  "status": "success",
  "next_action": "continue_handoff",
  "agent_session_id": "as_123456",
  "handoff_uri": "https://app.docendorse.com/agent/xyz"
}

What This Means

• The agent session was successfully created.
• The AI agent is ready.
• The user must now be redirected.

Required Action:

Redirect the user to handoff_uri

Status: require_subscription

Example Response

{
  "status": "require_subscription",
  "next_action": "subscribe",
  "subscription_url": "https://app.docendorse.com/subscribe/plan_xyz"
}

What This Means

• The user does not have an active subscription.
• They must subscribe before using the AI agent.

Required Action

Redirect the user to subscription_url. After successful subscription, the user will be redirected to the AI agent automatically.

Status: verify_email

Example Response

{
  "status": "verify_email",
  "next_action": "verify"
}

What This Means

• The user’s email address is not verified.
• A verification email has been sent automatically.

Required Action

• Inform the user to check their inbox.
• The user must verify their email.
• After verification, retry the handoff request.

Status: register

Example Response

{
  "status": "register",
  "next_action": "register_account"
}

What This Means

• The user must complete registration.
• This is uncommon because users are typically auto-registered.

Required Action

Redirect the user to the registration page provided in the response (if included), then retry the handoff after registration.

Status: error

Example Response

{
  "status": "error",
  "next_action": "none",
  "description": "Invalid file URL provided."
}

What This Means

• The request could not be processed.
• The description field explains the issue.

Required Action

• Log the error internally.
• Display a safe, user-friendly message.
• Fix the issue and retry if appropriate.