API Reference

Submit Response API

Programmatically submit form responses from your backend. Send free-form text and let NativeForm's AI automatically extract and map the relevant fields. Perfect for chatbots, voice assistants, email parsing, and any integration where structured data needs to be extracted from unstructured input.

For agent-powered intake flows, review Public Fill for safe public ingestion and Agents Auth for server-side key handling.

Authentication

All API calls require an account-level key. Create one below or from any form's Export tab.

Required header

x-nativeform-api-key: nfk_xxxxxx_secret

Request Format

Send a POST request with a JSON body to submit a response.

POSThttps://www.nativeform.app/api/forms/[form_id]/responses

Request Body

textstringRequired

The free-form text to extract fields from. Must be a non-empty string after trimming.

respondentobject

Optional user identification for tracking who submitted the response.

externalIdstring

Your application's user ID

emailstring

User's email address

namestring

User's display name

metadataRecord<string, unknown>

Optional metadata object stored with the response. Use for custom tracking data.

dateContextstring

Optional ISO date string for TIME field context. Helps AI interpret relative dates like 'tomorrow'.

Example with respondent and metadata

Example with date context

Use dateContext when your text contains relative dates to ensure accurate parsing.

Response Format

Successful submissions return a 201 status with the response details.

•responseId — Unique identifier for the submitted response.

•submittedAt — ISO timestamp of when the response was created.

•channel — Always "API" for programmatic submissions.

Error Handling

Descriptive error payloads and status codes.

Status	Description
400	Bad Request The request body failed validation. Check the fieldErrors for details.
401	Unauthorized The API key is missing or invalid. Verify your key in the Export tab.
404	Not Found The form ID doesn't exist or you don't have access to it.
422	Unprocessable Entity Required form fields couldn't be extracted from the text. Returns missingRequiredFields array.

Missing key

Invalid key

Validation errors

Missing required fields

Form not found

Examples

Complete examples in TypeScript and JavaScript with error handling.

Best Practices

Keep your integration resilient.

Server-to-server only

Never expose your API key in frontend code. Always make API calls from your backend server to keep credentials secure.

Include relevant context

Provide as much relevant text as possible. The AI extraction works best with complete sentences and context.

Use respondent identification

When possible, include respondent info to track submissions and enable better analytics.

Handle missing fields gracefully

Check for 422 errors with missingRequiredFields to provide helpful feedback to your users.

Use dateContext for relative dates

When your text contains relative dates like 'tomorrow' or 'next week', provide dateContext to ensure accurate parsing.

Security Warning

Never include your API key in client-side JavaScript, mobile apps, or any code that runs on user devices. API keys should only be used in server-side code where they cannot be inspected or extracted.