Submissions API

Read your form submissions programmatically — including metadata like user IP address. This is a read-only REST API, separate from the form submission endpoint.

The Submissions API is a PRO feature. Create and manage API keys from your dashboard.

Base URL

https://api.web3forms.com/v1

Authentication

Every request must include a Bearer token in the Authorization header. Your API key looks like w3f_live_….

curl https://api.web3forms.com/v1/forms \
  -H "Authorization: Bearer w3f_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Managing keys

Go to Dashboard → Account → API Keys:

  • Create a key — give it a label (e.g. "Production backend"). The full key is shown once.

  • Revoke a key — takes effect immediately; any request using it returns 401.

  • You can hold up to 10 active keys at a time.

A key is scoped to your account and can read submissions for any form you own.

Rate limits

Requests are throttled at 20 requests/second (burst 50) per account. Exceeding this returns 429 with a Retry-After header (in seconds).


List forms

GET https://api.web3forms.com/v1/forms

Returns all forms you own.

Response


List submissions

GET https://api.web3forms.com/v1/submissions

Returns submissions for a form, newest first.

Query Parameters

Name
Type
Description

form_id*

string

The form to fetch submissions for.

limit

integer

Page size. Default 50, min 1, max 100.

cursor

string

Pagination cursor from a previous response.

Example

Response

Pagination

When has_more is true, pass next_cursor back as the cursor parameter to fetch the next page. Repeat until has_more is false.


Get a submission

GET https://api.web3forms.com/v1/submissions/{id}

Returns a single submission by its id.

Example

Response


Errors

Errors return a non-2xx status and a JSON body:

Status
Code
Meaning

400

bad_request

Missing or invalid parameter (e.g. no form_id)

401

unauthorized

Missing, malformed, or revoked key

403

forbidden

Key not authorized for that form

404

not_found

Form or submission doesn't exist (or isn't yours)

429

rate_limit_exceeded

Too many requests — retry after the header value

500

server_error

Something went wrong on our end

Last updated