# Forms

## Submit Form

 - [POST /v1/forms/submit](https://developers.withlantern.com/openapi/forms/submit_form_v1_forms_submit_post.md): Accepts form submissions and immediately enriches and dispositions the data.

## Overview
The Form Submit API is designed to accept form submissions directly from marketing
automation platforms or websites. It provides immediate enrichment and disposition of
submitted data with two possible outcomes:
1. Return enriched lead data in the response
2. Push the enriched lead to Salesforce or Marketing Automation (MA) tool

## Authentication
Requires an API key configured per site or system.

## Rate Limits
Designed for near-real-time processing (less than 5 seconds end-to-end) and supports
high-volume campaign bursts.

## Request Body
- name: Contact name
- email: Contact email address (validated)
- company: Company name
- phone: Phone number (validated)
- title: Job title
- additional_fields: Additional form fields as key-value pairs
- form_source: Source of form submission
- enrichment_preferences: Enrichment preferences and configuration
- output_preferences: Output preferences (return data vs push to external system)

## Response Fields
- success: Boolean indicating request success
- status: Processing status (enriched, pushed, failed)
- request_id: Unique request ID for tracking
- processing_time_ms: Processing time in milliseconds
- enriched_lead: Enriched lead data (if requested)
- push_status: Status of push to external system (if applicable)
- credits_consumed: Number of credits used
- credits_remaining: Credits remaining in account
- gdpr_safe: Whether enrichment was GDPR compliant
- cached: Whether result was from cache

## Features
- Input Validation: Email and phone number validation
- GDPR Compliance: Safe enrichment practices
- Real-time Processing: Sub-5 second end-to-end processing
- High Volume Support: Optimized for campaign bursts
- Flexible Output: Return enriched data or push to external systems
- Audit Trail: Complete logging for compliance

## Credit Usage
Form submissions consume credits based on processing:
- Basic Submission: 2 credits per form
- With Enrichment: +3 credits for enrichment processing
- With Push: +1 credit for external system push