Forms API

Docs

Forms API

Manage external forms and form submissions with tracking capabilities.

The Forms API enables you to create form sessions, submit form data, and track conversions across multiple platforms including Facebook, TikTok, Snapchat, and Everflow.

Create Form Session

Create a new form session to start tracking form interactions.

Endpoint

POST /api/forms/session

Headers

X-API-Key: your_api_key_here
Content-Type: application/json

Request Body

{
  "formId": "550e8400-e29b-41d4-a716-446655440000",
  "formTitle": "Weight Management",
  "formDescription": "TrimRx Weight Management Form",
  "locale": "EN_US",
  "link": "https://example.com/form"
}

Parameters

Field	Type	Required	Description
`formId`	string (UUID)	No	Existing form ID to use
`formTitle`	string	No	Form title (default: "Weight Management")
`formDescription`	string	No	Form description (default: "TrimRx Weight Management Form")
`locale`	string	No	Language locale (default: "EN_US")
`link`	string	No	External form link

Success Response

{
  "success": true,
  "data": {
    "sessionId": "uuid-of-session",
    "formId": "uuid-of-form",
    "submissionId": "uuid-of-submission",
    "form": {
      "id": "uuid-of-form",
      "title": "Weight Management",
      "description": "TrimRx Weight Management Form",
      "locale": "EN_US",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  }
}

Example Request

curl -X POST "https://dev.api.evoncrm.com/api/forms/session" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "formTitle": "Lead Capture Form",
    "formDescription": "Marketing campaign lead form",
    "locale": "EN_US",
    "link": "https://mysite.com/contact"
  }'

Get Form Session

Retrieve details of an existing form session.

Endpoint

GET /api/forms/session/{sessionId}

Parameters

Field	Type	Required	Description
`sessionId`	string (UUID)	Yes	Session ID from URL path

Success Response

{
  "success": true,
  "data": {
    "id": "uuid-of-session",
    "formId": "uuid-of-form",
    "submissionId": "uuid-of-submission",
    "form": {
      "id": "uuid-of-form",
      "title": "Weight Management",
      "description": "TrimRx Weight Management Form",
      "locale": "EN_US"
    },
    "submission": {
      "id": "uuid-of-submission",
      "status": "PENDING",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  }
}

Example Request

curl -X GET "https://dev.api.evoncrm.com/api/forms/session/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

Submit Form Data

Submit form data and trigger conversion tracking across platforms.

Endpoint

POST /api/forms/data

Headers

X-API-Key: your_api_key_here
Content-Type: application/json

Request Body

{
  "sessionId": "uuid-of-session",
  "data": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-123-4567",
    "age": 35,
    "weight": "180 lbs",
    "goal": "Weight Loss"
  },
  "eventName": "form_submit",
  "conversionValue": 49.99,
  "currency": "USD",
  "userAgent": "Mozilla/5.0...",
  "ipAddress": "192.168.1.1",
  "fbp": "fb.1.1234567890.123456789",
  "fbc": "fb.1.1234567890.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890"
}

Parameters

Field	Type	Required	Description
`sessionId`	string (UUID)	Yes	Session ID from form creation
`data`	object	Yes	Form field data
`eventName`	string	No	Conversion event name (default: "form_submit")
`conversionValue`	number	No	Value of the conversion
`currency`	string	No	Currency code (default: "USD")
`userAgent`	string	No	User's browser user agent
`ipAddress`	string	No	User's IP address
`fbp`	string	No	Facebook browser pixel
`fbc`	string	No	Facebook click ID

Success Response

{
  "success": true,
  "data": {
    "submissionId": "uuid-of-submission",
    "status": "COMPLETED",
    "conversionResults": {
      "facebook": {
        "success": true,
        "eventId": "fb-event-123"
      },
      "tiktok": {
        "success": true,
        "eventId": "tt-event-456"
      },
      "snapchat": {
        "success": true,
        "eventId": "snap-event-789"
      },
      "everflow": {
        "success": true,
        "clickId": "ef-click-012"
      }
    }
  }
}

Example Request

curl -X POST "https://dev.api.evoncrm.com/api/forms/data" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "data": {
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@example.com",
      "phone": "+1-555-987-6543"
    },
    "eventName": "lead_generation",
    "conversionValue": 25.00,
    "currency": "USD"
  }'

Conversion Tracking

The Forms API automatically tracks conversions across multiple platforms:

Supported Platforms

Facebook Conversions API: Tracks events to Facebook Pixel
TikTok Conversions API: Sends conversion data to TikTok
Snapchat Conversions API: Reports conversions to Snapchat
Everflow: Tracks affiliate network conversions

Event Types

Common event names for conversion tracking:

form_submit - General form submission
lead_generation - Lead capture forms
sign_up - Registration forms
contact - Contact forms
quote_request - Quote/pricing requests

Error Responses

400 Bad Request

{
  "error": "Datos inválidos",
  "details": [
    {
      "code": "invalid_string",
      "message": "sessionId must be a valid UUID",
      "path": ["sessionId"]
    }
  ]
}

404 Not Found

{
  "error": "Session not found"
}

Use Cases

Lead Generation: Capture and track marketing leads
Contact Forms: Track contact form submissions
Multi-platform Tracking: Unified conversion tracking
A/B Testing: Compare form performance across campaigns
Affiliate Tracking: Monitor affiliate conversion performance

Best Practices

Session Management: Create sessions before showing forms to users
Data Validation: Validate form data before submission
Conversion Values: Include meaningful conversion values for ROI tracking
Error Handling: Handle conversion tracking failures gracefully
Privacy Compliance: Ensure user consent for tracking pixels

Conversions API Leads API