REST API Reference

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

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).

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

{
    "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

{
    "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