Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ansa.so/llms.txt

Use this file to discover all available pages before exploring further.

The Forms API handles form submissions from the widget and provides analytics on form performance.

​
Endpoints

MethodEndpointDescription
POST/form-submissions/submitSubmit a form
POST/form-submissions/client-resultReport client handler result
GET/form-submissions/analyticsGet form analytics

​
Submit Form

POST /form-submissions/submit
Submit form data collected from a user. This endpoint is typically called by the widget.

​
Request Body

{
  "toolId": "tool_abc123",
  "conversationId": "conv_xyz789",
  "formData": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "message": "I'd like to learn more about pricing"
  },
  "fieldsCompleted": ["name", "email", "message"],
  "impressionAt": 1703347200000,
  "startedAt": 1703347205000
}

​
Parameters

FieldTypeRequiredDescription
toolIdstringYesThe form tool ID
conversationIdstringNoAssociated conversation ID
formDataobjectYesKey-value pairs of form field values
fieldsCompletedstring[]YesList of fields that were filled
impressionAtnumberNoTimestamp when form was shown (ms)
startedAtnumberNoTimestamp when user started filling (ms)

​
Response

{
  "success": true,
  "submissionId": "sub_def456",
  "executionMode": "webhook",
  "webhookResult": {
    "success": true,
    "error": null
  },
  "postActionResults": [
    { "type": "slack", "success": true },
    { "type": "email", "success": true }
  ],
  "clientHandler": null
}

​
Response Fields

FieldTypeDescription
successbooleanWhether submission was recorded
submissionIdstringUnique submission ID
executionModestringwebhook, client, or both
webhookResultobjectResult of webhook delivery
postActionResultsarrayResults of post-submission actions
clientHandlerstringName of client handler (if applicable)

​
Errors

StatusDescription
400Invalid request body or file too large
404Tool not found

​
File Uploads

Files are submitted as base64-encoded data URLs: 
{
  "formData": {
    "document": "data:application/pdf;base64,JVBERi0xLjQKJ..."
  }
}
Maximum file size: 5MB per file.

​
Report Client Result

POST /form-submissions/client-result
Report the result of a client-side form handler execution.

​
Request Body

{
  "submissionId": "sub_def456",
  "success": true,
  "message": "Successfully created lead",
  "data": {
    "leadId": "lead_123"
  }
}

​
Parameters

FieldTypeRequiredDescription
submissionIdstringYesThe submission ID
successbooleanYesWhether client handler succeeded
messagestringNoStatus message
dataobjectNoAdditional result data

​
Response

{
  "success": true
}

​
Get Form Analytics

GET /form-submissions/analytics?agentId={agentId}
Get analytics for all forms belonging to an agent.

​
Query Parameters

ParameterTypeRequiredDescription
agentIdstringYesThe agent ID

​
Response

{
  "analytics": [
    {
      "toolId": "tool_abc123",
      "toolName": "contact_form",
      "impressions": 1500,
      "started": 850,
      "submitted": 320,
      "successful": 315,
      "failed": 5,
      "conversionRate": 21.33,
      "completionRate": 37.65,
      "fieldCompletionRates": {
        "name": 98.5,
        "email": 100,
        "phone": 45.2,
        "message": 92.3
      }
    }
  ]
}

​
Analytics Fields

FieldDescription
toolIdForm tool ID
toolNameForm tool name
impressionsTimes form was shown
startedTimes user began filling
submittedTotal submissions
successfulSuccessful submissions
failedFailed submissions
conversionRatesubmitted / impressions × 100
completionRatesubmitted / started × 100
fieldCompletionRatesCompletion % per field

​
Submission Status

Form submissions progress through these statuses:
StatusDescription
pendingJust created, processing
submittedRecorded (client-only mode)
webhook_successWebhook delivered successfully
webhook_failedWebhook delivery failed
client_successClient handler succeeded
client_failedClient handler failed
successAll actions completed
failedOne or more actions failed

​
Execution Modes

ModeBehavior
webhookSend to configured webhook URL only
clientHandle with client-side JavaScript only
bothSend to webhook AND notify client handler

​
Webhook Payload

When execution mode includes webhook, data is sent as: 
{
  "submissionId": "sub_def456",
  "toolId": "tool_abc123",
  "toolName": "contact_form",
  "conversationId": "conv_xyz789",
  "formData": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "message": "Hello!"
  },
  "submittedAt": "2024-12-23T10:30:00.000Z"
}

​
Retry Logic

Failed webhooks are automatically retried:
AttemptDelay
1Immediate
21 minute
35 minutes
Maximum of 3 attempts.

​
Post Actions

After the primary webhook, additional actions are processed:

​
Slack Notification

{
  "type": "slack",
  "webhookUrl": "https://hooks.slack.com/services/...",
  "messageTemplate": "New {{_toolName}} submission!\nEmail: {{email}}"
}

​
Additional Webhook

{
  "type": "webhook",
  "url": "https://your-server.com/api/leads",
  "headers": {
    "Authorization": "Bearer xxx"
  }
}

​
Email Notification

{
  "type": "email",
  "recipientIds": ["user_123", "user_456"],
  "subject": "New Form Submission"
}

​
Examples

​
Submit Contact Form

curl -X POST https://api.ansa.so/form-submissions/submit \
  -H "Content-Type: application/json" \
  -d '{
    "toolId": "tool_contact_form",
    "formData": {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "message": "I would like to schedule a demo"
    },
    "fieldsCompleted": ["name", "email", "message"],
    "impressionAt": 1703347200000,
    "startedAt": 1703347205000
  }'

​
Report Client Handler Success

curl -X POST https://api.ansa.so/form-submissions/client-result \
  -H "Content-Type: application/json" \
  -d '{
    "submissionId": "sub_def456",
    "success": true,
    "message": "Lead created in CRM",
    "data": {
      "crmLeadId": "crm_lead_789"
    }
  }'

​
Get Analytics

curl https://api.ansa.so/form-submissions/analytics?agentId=agent_xyz789 \
  -H "Authorization: Bearer $ANSA_API_KEY"

​
Integration with Widget

The widget handles form submission automatically:
  1. User fills out form in widget
  2. Widget calls /form-submissions/submit
  3. Server processes webhook/post-actions
  4. If executionMode includes client, widget calls registered handler
  5. Widget calls /form-submissions/client-result with handler result
// Register client handler
ansa.registerFormHandler("custom_form", {
  onSubmit: async (context) => {
    // Your custom logic
    await saveToDatabase(context.formData);

    return {
      success: true,
      message: "Saved successfully"
    };
  }
});