API Reference

NativeForm API

Stream submissions into your own data stack, power custom dashboards, or trigger automations with a stable REST API.

Building with AI agents? Start from Agents Overview, then continue with Auth, CLI, MCP, and Skills.

Base URL

All API requests are made to this base URL.

https://www.nativeform.app/api/

Authentication

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

Sign in to create an API key. Keys follow the format nfk_prefix_secret

Sign inCreate account

Required header

x-nativeform-api-key: nfk_xxxxxx_secret

Endpoints

All endpoints support cursor-based pagination.

MethodEndpointDescription
GET/forms

Returns paginated list of all forms for the authenticated user with filtering and search.

  • • Supports cursor-based pagination (`cursor` + `limit`).
  • • Filters by `status`, `visibility`, and free-text search across name and slug.
  • • Use `order=asc|desc` for chronological control (defaults to `desc`).
  • • Returns form metadata including response counts.
GET/forms/{formId}/responses

Returns paginated responses for a specific form with filtering, cursor pagination, and search.

  • • Supports cursor-based pagination (`cursor` + `limit`).
  • • Filters by `status`, `channel`, submission timestamps, and free-text search.
  • • Use `order=asc|desc` for chronological control (defaults to `desc`).
  • • Each response includes both `answers` (user-submitted fields) and `smartFields` (AI-evaluated fields).
GEThttps://www.nativeform.app/api/forms

List forms

Filter & search

Cursor pagination

GEThttps://www.nativeform.app/api/forms/{formId}/responses

List responses

Filter & search

Cursor pagination

Query Parameters

Every parameter is optional.

limitnumber

1-200 results per page.

Default: 50

cursorstring

Pass `meta.nextCursor` to fetch the next page.

Default: null

status"SUBMITTED" | "DRAFT" | "ABANDONED"

Filter by submission status.

Default: null

searchstring

Full-text search across respondent info and answers.

Default: null

submittedAfterISO string

Only responses submitted after the timestamp.

Default: null

submittedBeforeISO string

Only responses before the timestamp.

Default: null

order"asc" | "desc"

Sort by submission time.

Default: desc

channel"WEB" | "API"

Filter by submission channel.

Default: null

Response Format

Structure of the API response with types annotated. Each response includes both answers (user-submitted fields) and smartFields (AI-evaluated fields).

Field Types

The value object structure depends on the field type.

Error Handling

Descriptive error payloads and status codes.

Missing key

Validation errors

Best Practices

Keep your integration resilient.

Paginate aggressively

Use `limit` ≤ 200 plus `cursor` to keep requests fast and cacheable.

Validate before storing

Use the provided Zod schema (or your validator) so downstream systems stay type-safe.

Filter at the edge

Push search, status, and date filters into the request instead of filtering in memory.

Rotate API keys

Create scoped keys per integration and rotate them from the Export tab when teammates leave.

Troubleshooting

Common issues and fixes.

401 Unauthorized

Ensure the `x-nativeform-api-key` header is present and the key wasn't rotated.

422 Validation error

Numeric parameters must be numbers. Check `error.fieldErrors` for the offending field.

Empty response set

Double-check the form ID and consider relaxing date/status filters.

Cursor loops

Always stop when `meta.nextCursor` is `null`. Re-using a cursor returns the same page.