REST API Reference

Version 4.15.1 Updated November 7, 2026

Core Forms exposes a comprehensive REST API under the cf/v1 namespace. All endpoints require the edit_forms capability (WordPress administrator by default).

Access is additionally limited to the caller’s assigned form scope. Authoring reads return draft definitions. Starting with 4.11.0, every mutation of an existing form requires its current fingerprint from GET /cf/v1/forms/{id}. Include it in the JSON body, including field/schema edits and deletion. Use the response fingerprint for the next request. Missing or stale versions return HTTP 409 without modifying the definition. Native wp/v2/core-form writes return HTTP 405; use this versioned API. See Drafts and Revisions and Rehearsal for publishing and rehearsal.

Authentication

Use standard WordPress REST API authentication:

Cookie + Nonce (for admin AJAX): Include X-WP-Nonce header
Application Passwords (for external apps): HTTP Basic Auth
OAuth or other authentication plugins

Forms

List All Forms

GET /wp-json/cf/v1/forms

Returns all forms as an array of form objects.

Get a Single Form

GET /wp-json/cf/v1/forms/{id}

Create a Form

POST /wp-json/cf/v1/forms

{
    "title": "Contact Form",
    "slug": "contact",
    "markup": "<p><label>Name</label><input type="text" name="name" required /></p>",
    "settings": {},
    "messages": {}
}

Update a Form

PATCH /wp-json/cf/v1/forms/{id}

Accepts any subset of form fields (title, markup, settings, messages). Also include "fingerprint": "the-current-value".

Delete a Form

DELETE /wp-json/cf/v1/forms/{id}

Schema

Get Form Schema

GET /wp-json/cf/v1/forms/{id}/schema

Returns the structured FormSchema JSON, or null if no schema exists.

Update Form Schema

PUT /wp-json/cf/v1/forms/{id}/schema

{
    "fingerprint": "the-current-value",
    "version": 1,
    "fields": [
        { "name": "email", "type": "email", "label": "Email", "required": true, "position": 0 }
    ],
    "layout": { "type": "single" },
    "form_settings": {}
}

Generate Schema from HTML

POST /wp-json/cf/v1/forms/{id}/schema/generate

Parses the form’s HTML markup and generates a structured schema. Useful for migrating existing HTML forms to the schema system.

Fields

List Fields

GET /wp-json/cf/v1/forms/{id}/fields

Returns the fields array from the form schema.

Add a Field

POST /wp-json/cf/v1/forms/{id}/fields

{
    "fingerprint": "the-current-value",
    "name": "phone",
    "type": "tel",
    "label": "Phone Number",
    "required": false,
    "placeholder": "+1 (555) 000-0000"
}

Update a Field

PATCH /wp-json/cf/v1/forms/{id}/fields/{name}

{
    "required": true,
    "validation": { "pattern": "^+?[0-9-s]+$" }
}

Delete a Field

DELETE /wp-json/cf/v1/forms/{id}/fields/{name}

Submissions

List Submissions

GET /wp-json/cf/v1/submissions
GET /wp-json/cf/v1/forms/{form_id}/submissions

Parameters: per_page (default 20), page, status, search.

Get a Submission

GET /wp-json/cf/v1/submissions/{id}

Update a Submission

PATCH /wp-json/cf/v1/submissions/{id}

{ "status": "archived" }

Delete a Submission

DELETE /wp-json/cf/v1/submissions/{id}

Analytics

Funnel Metrics

GET /wp-json/cf/v1/analytics/{form_id}/funnel

Parameters: date_from, date_to.

Daily Stats

GET /wp-json/cf/v1/analytics/{form_id}/daily

Parameters: date_from (required), date_to (required).

Field Drop-off

GET /wp-json/cf/v1/analytics/{form_id}/field-dropoff

Attribution

GET /wp-json/cf/v1/analytics/{form_id}/attribution

Spam Trends

GET /wp-json/cf/v1/analytics/{form_id}/spam-trends

Parameters: days (default 30).

Recommendations

GET /wp-json/cf/v1/analytics/{form_id}/recommendations

Overview (All Forms)

GET /wp-json/cf/v1/analytics/overview

Returns summary data for up to 50 forms.

Workflows

Action Logs

GET /wp-json/cf/v1/action-logs

Parameters: form_id, submission_id, status, per_page (default 20), page.

Log Statistics

GET /wp-json/cf/v1/action-logs/stats

Parameters: form_id (optional).

Recent Failures

GET /wp-json/cf/v1/action-logs/failures

Queue Statistics

GET /wp-json/cf/v1/action-queue/stats

Retry a Failed Action

POST /wp-json/cf/v1/action-queue/{id}/retry

Test an Action

POST /wp-json/cf/v1/actions/test

{
    "action_type": "email",
    "form_id": 123,
    "settings": {
        "to": "test@example.com",
        "subject": "Test",
        "message": "[all]"
    },
    "test_data": {
        "name": "Test User",
        "email": "test@example.com"
    }
}

Error Responses

All endpoints return standard WordPress REST API errors:

{
    "code": "rest_forbidden",
    "message": "Sorry, you are not allowed to do that.",
    "data": { "status": 403 }
}

Common error codes:

rest_forbidden (403): Missing edit_forms capability
rest_no_route (404): Invalid endpoint
missing_type (400): Required parameter missing
retry_failed (400): Action not in failed state