Formivo API Documentation

Introduction

Formivo turns submissions from your existing website form into leads in your dashboard. You don't rebuild your form — you point it at your Formivo endpoint and authenticate with your form secret.

Quick Start

Create a form in your Formivo dashboard.
Copy the endpoint URL and form secret.
Submit data to the endpoint.
Open your dashboard — the submission appears as a lead.

await fetch("https://your-formivo-domain.com/api/v1/forms/frm_abc123/submissions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer fmv_live_xxxxxxxxx",
  },
  body: JSON.stringify({
    data: {
      name: "John Doe",
      email: "john@example.com",
      message: "Hello",
    },
  }),
});

// → { "success": true, "leadId": "lead_123", "message": "Submission received." }

Authentication

Every submission request must include your form secret as a Bearer token. Secrets are shown once at creation and can be rotated in the dashboard.

Authorization: Bearer FORM_SECRET

Keep the secret on your server when possible. A secret placed in browser-side JavaScript is visible to anyone using your site.

Request Format

Send a JSON object with a data field containing your form values. Any JSON shape is accepted — Formivo does not force a rigid field schema. An optional metadata object is stored alongside the lead.

curl -X POST "https://your-formivo-domain.com/api/v1/forms/frm_abc123/submissions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fmv_live_xxxxxxxxx" \
  -d '{"data":{"name":"John Doe","email":"john@example.com"}}'

Errors

Errors return structured JSON with a machine-readable code:

INVALID_REQUESTThe request body is malformed or missing a data object.

UNAUTHORIZEDMissing or invalid Bearer secret.

FORM_NOT_FOUNDNo form exists for the given public form ID.

FORM_INACTIVEThe form is archived and no longer accepts submissions.

PAYLOAD_TOO_LARGEThe request body exceeds the allowed size.

RATE_LIMITEDToo many requests. Slow down and retry.

QUOTA_EXCEEDEDThe monthly lead limit for the plan has been reached.

INTERNAL_ERRORSomething went wrong on our side. Try again.

Testing

Use the Test submission tool on your form's integration page to verify the connection without touching your live site. You can also send a real request with curl and expect the lead to appear within seconds.

Security

Never commit your form secret to a public repository.
Rotate your secret if it may have leaked — old integrations stop working immediately.
All authorization is enforced server-side; browser checks are cosmetic.