Skip to content
Fomr LogoFomr Help Center
Join our Slack

Validate a draft without publishing

POST
/v1/forms/{form_public_id}/validate
curl --request POST \
  --url https://platform.fomr.io/v1/forms/example/validate \
  --header 'Authorization: Bearer <token>'

Runs Publish Validation against the stored draft without publishing and without writing anything, and answers 200 whether the draft is ready or not. Every Publish Issue names its code, the path into the Draft Document, and the page and block it sits on. Run it before publish to fix everything in one pass. A Private Template cannot be published, so validating one is refused with 400 INVALID_INPUT at is_template. Needs forms:read or templates:read. Costs 1 API credit.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
form_public_id
required
string
>= 10 characters <= 10 characters /^[A-Za-z0-9_-]+$/

The public ID of the form or Private Template.

Responses

Section titled “Responses”

200

Section titled “200”

Default Response

Media typeapplication/json
object
valid
required

Whether the stored draft would publish right now, including the plan, email, and safety checks publish runs.

boolean
issues
required

Every Publish Issue the stored draft holds. Empty when valid is true.

Array<object>
object
code
required

The stable Publish Issue code to branch on. Besides the draft checks, validate reports FORM_PUBLISH_EMAIL_UNVERIFIED, FORM_SAFETY_REJECTED, and PRO_FEATURE_REQUIRED for what publish would refuse. New codes are added over time.

string
Allowed values: FORM_PUBLISH_DRAFT_INVALID FORM_PUBLISH_BLUEPRINT_INVALID FORM_PUBLISH_BLUEPRINT_TOO_LARGE FORM_PUBLISH_TOO_MANY_PAGES FORM_PUBLISH_TOO_MANY_NODES FORM_PUBLISH_TOO_MANY_PAGE_NODES FORM_PUBLISH_TOO_MANY_OPTIONS FORM_PUBLISH_TOO_MANY_TOTAL_OPTIONS FORM_PUBLISH_TOO_MANY_MATRIX_ROWS FORM_PUBLISH_TOO_MANY_MATRIX_COLUMNS FORM_PUBLISH_MISSING_FINAL_PAGE FORM_PUBLISH_MULTIPLE_FINAL_PAGES FORM_PUBLISH_FINAL_PAGE_POSITION FORM_PUBLISH_FINAL_PAGE_HIDDEN FORM_PUBLISH_ALL_PAGES_HIDDEN FORM_PUBLISH_FINAL_PAGE_NODES FORM_PUBLISH_THANK_YOU_PLACEMENT FORM_PUBLISH_MISSING_QUESTION FORM_PUBLISH_MULTIPLE_ENTRYPOINTS FORM_PUBLISH_ENTRYPOINT_FINAL_PAGE FORM_PUBLISH_ENTRYPOINT_POSITION FORM_PUBLISH_AUTO_JUMP_INVALID FORM_PUBLISH_MISSING_OPTIONS FORM_PUBLISH_MISSING_MATRIX_ROWS FORM_PUBLISH_NUMBER_SETTINGS_INVALID FORM_PUBLISH_DANGLING_PIPE FORM_PUBLISH_EMAIL_UNVERIFIED FORM_SAFETY_REJECTED PRO_FEATURE_REQUIRED
message
required

What to fix, in words. Not part of the contract; never branch on it.

string
path
required

The path into the Draft Document, with property names and numeric array indexes, such as [“pages”, 1, “nodes”, 0, “meta”, “select_options_data”]. Empty when the issue is about the form as a whole.

Array
page_public_id
required
Any of:
string
>= 4 characters <= 4 characters /^[A-Za-z0-9_-]+$/
node_public_id
required
Any of:
string
>= 4 characters <= 4 characters /^[A-Za-z0-9_-]+$/
would_publish_version
required

Point-in-time version number publish would give the form, including when issues must first be fixed. It is the latest published version when the draft has not changed since that publish, and the next number otherwise. A concurrent publish can change it.

integer
>= -9007199254740991 <= 9007199254740991
share_url
required

The configured public link the form would have after publishing. Validation does not publish or activate this link.

string format: uri

Example 

{
  "issues": [
    {
      "code": "FORM_PUBLISH_DRAFT_INVALID"
    }
  ]
}

400

Section titled “400”

Default Response

Media typeapplication/json
object
code
required

The stable code to branch on.

string
Allowed values: INVALID_INPUT UNAUTHORIZED PERSONAL_ACCESS_TOKEN_EXPIRED PERSONAL_ACCESS_TOKEN_REVOKED PLAN_LIMIT_REACHED PRO_FEATURE_REQUIRED FORBIDDEN FORM_PUBLISH_EMAIL_UNVERIFIED ORGANIZATION_MEMBER_BLOCKED PERSONAL_ACCESS_TOKEN_NOT_PERMITTED NOT_FOUND FORM_NOT_PUBLISHED NO_DRAFT_DURING_PUBLISH FORM_ARCHIVED FORM_CONVERSION_BLOCKED FORM_PUBLISH_REVISION_CONFLICT PAYLOAD_TOO_LARGE FORM_PUBLISH_VALIDATION_FAILED FORM_SAFETY_REJECTED TOO_MANY_REQUESTS API_COOLDOWN SERVER AI_SERVICE_UNAVAILABLE SERVICE_UNAVAILABLE
message
required

A human-readable explanation. Not part of the contract; never branch on it.

string
request_id
required

The ID of the failed request, also sent as the X-Request-Id response header.

string
issues
required

Every value the request got wrong.

Array<object>
object
path
required

The path into the request, with property names and numeric array indexes.

Array
message
required

What is wrong with the value at this path.

string
code
required

The stable code for the issue. Branch on it, and use it with params to write your own text.

string
accepted_values

Accepted values when a node type or enum value is rejected.

Array
params

The values the message was built from, keyed by name, for clients that write their own text for each code.

object
key
additional properties
Any of:
string

Example 

{
  "code": "INVALID_INPUT"
}

401

Section titled “401”

Default Response

Media typeapplication/json
object
code
required

The stable code to branch on.

string
Allowed values: INVALID_INPUT UNAUTHORIZED PERSONAL_ACCESS_TOKEN_EXPIRED PERSONAL_ACCESS_TOKEN_REVOKED PLAN_LIMIT_REACHED PRO_FEATURE_REQUIRED FORBIDDEN FORM_PUBLISH_EMAIL_UNVERIFIED ORGANIZATION_MEMBER_BLOCKED PERSONAL_ACCESS_TOKEN_NOT_PERMITTED NOT_FOUND FORM_NOT_PUBLISHED NO_DRAFT_DURING_PUBLISH FORM_ARCHIVED FORM_CONVERSION_BLOCKED FORM_PUBLISH_REVISION_CONFLICT PAYLOAD_TOO_LARGE FORM_PUBLISH_VALIDATION_FAILED FORM_SAFETY_REJECTED TOO_MANY_REQUESTS API_COOLDOWN SERVER AI_SERVICE_UNAVAILABLE SERVICE_UNAVAILABLE
message
required

A human-readable explanation. Not part of the contract; never branch on it.

string
request_id
required

The ID of the failed request, also sent as the X-Request-Id response header.

string

Example 

{
  "code": "INVALID_INPUT"
}

403

Section titled “403”

Default Response

Media typeapplication/json
object
code
required

The stable code to branch on.

string
Allowed values: INVALID_INPUT UNAUTHORIZED PERSONAL_ACCESS_TOKEN_EXPIRED PERSONAL_ACCESS_TOKEN_REVOKED PLAN_LIMIT_REACHED PRO_FEATURE_REQUIRED FORBIDDEN FORM_PUBLISH_EMAIL_UNVERIFIED ORGANIZATION_MEMBER_BLOCKED PERSONAL_ACCESS_TOKEN_NOT_PERMITTED NOT_FOUND FORM_NOT_PUBLISHED NO_DRAFT_DURING_PUBLISH FORM_ARCHIVED FORM_CONVERSION_BLOCKED FORM_PUBLISH_REVISION_CONFLICT PAYLOAD_TOO_LARGE FORM_PUBLISH_VALIDATION_FAILED FORM_SAFETY_REJECTED TOO_MANY_REQUESTS API_COOLDOWN SERVER AI_SERVICE_UNAVAILABLE SERVICE_UNAVAILABLE
message
required

A human-readable explanation. Not part of the contract; never branch on it.

string
request_id
required

The ID of the failed request, also sent as the X-Request-Id response header.

string
required_permission
required
Any of:
string

Example 

{
  "code": "INVALID_INPUT"
}

404

Section titled “404”

Default Response

Media typeapplication/json
object
code
required

Returned for a form that does not exist, is in Trash, or belongs to another organization. The three are not told apart.

string
Allowed value: NOT_FOUND
message
required

A human-readable explanation. Not part of the contract; never branch on it.

string
request_id
required

The ID of the failed request, also sent as the X-Request-Id response header.

string

Example 

{
  "code": "NOT_FOUND"
}

409

Section titled “409”

A form that cannot be published as it stands: it is archived, or it holds no draft. Branch on code.

Media typeapplication/json
Any of:
object
code
required

The form is archived: it has no editable draft, so draft writes, publish, and conversion are refused.

string
Allowed value: FORM_ARCHIVED
message
required

A human-readable explanation. Not part of the contract; never branch on it.

string
request_id
required

The ID of the failed request, also sent as the X-Request-Id response header.

string

Example 

{
  "code": "FORM_ARCHIVED"
}

429

Section titled “429”

A rejected call. The organization budget names the policy it rejected the call under; the request floor that bounds hammering sends the envelope alone.

Media typeapplication/json
Any of:
object
code
required

The stable code to branch on.

string
Allowed values: INVALID_INPUT UNAUTHORIZED PERSONAL_ACCESS_TOKEN_EXPIRED PERSONAL_ACCESS_TOKEN_REVOKED PLAN_LIMIT_REACHED PRO_FEATURE_REQUIRED FORBIDDEN FORM_PUBLISH_EMAIL_UNVERIFIED ORGANIZATION_MEMBER_BLOCKED PERSONAL_ACCESS_TOKEN_NOT_PERMITTED NOT_FOUND FORM_NOT_PUBLISHED NO_DRAFT_DURING_PUBLISH FORM_ARCHIVED FORM_CONVERSION_BLOCKED FORM_PUBLISH_REVISION_CONFLICT PAYLOAD_TOO_LARGE FORM_PUBLISH_VALIDATION_FAILED FORM_SAFETY_REJECTED TOO_MANY_REQUESTS API_COOLDOWN SERVER AI_SERVICE_UNAVAILABLE SERVICE_UNAVAILABLE
message
required

A human-readable explanation. Not part of the contract; never branch on it.

string
request_id
required

The ID of the failed request, also sent as the X-Request-Id response header.

string
policy
required

The policy that rejected the call.

string
Allowed values: minute burst
plan
required

The plan whose numbers were applied.

string
Allowed values: free pro
limit
required

The policy limit in credits.

integer
>= -9007199254740991 <= 9007199254740991
used
required

Credits already spent in the open window.

integer
>= -9007199254740991 <= 9007199254740991
remaining
required

Credits still available under the policy.

integer
>= -9007199254740991 <= 9007199254740991
cost
required

What the rejected call would have cost.

integer
>= -9007199254740991 <= 9007199254740991
window_seconds
required

How long the policy window lasts.

integer
>= -9007199254740991 <= 9007199254740991
cooldown_until
required
Any of:
string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$/
resets_at
required

When the window that rejected the call ends.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$/
retry_after_seconds
required

Seconds to wait before retrying. Also sent as the Retry-After response header.

integer
>= -9007199254740991 <= 9007199254740991
upgrade_url
required
Any of:
string

Example 

{
  "code": "INVALID_INPUT",
  "policy": "minute",
  "plan": "free"
}

500

Section titled “500”

Default Response

Media typeapplication/json
object
code
required

The stable code to branch on.

string
Allowed values: INVALID_INPUT UNAUTHORIZED PERSONAL_ACCESS_TOKEN_EXPIRED PERSONAL_ACCESS_TOKEN_REVOKED PLAN_LIMIT_REACHED PRO_FEATURE_REQUIRED FORBIDDEN FORM_PUBLISH_EMAIL_UNVERIFIED ORGANIZATION_MEMBER_BLOCKED PERSONAL_ACCESS_TOKEN_NOT_PERMITTED NOT_FOUND FORM_NOT_PUBLISHED NO_DRAFT_DURING_PUBLISH FORM_ARCHIVED FORM_CONVERSION_BLOCKED FORM_PUBLISH_REVISION_CONFLICT PAYLOAD_TOO_LARGE FORM_PUBLISH_VALIDATION_FAILED FORM_SAFETY_REJECTED TOO_MANY_REQUESTS API_COOLDOWN SERVER AI_SERVICE_UNAVAILABLE SERVICE_UNAVAILABLE
message
required

A human-readable explanation. Not part of the contract; never branch on it.

string
request_id
required

The ID of the failed request, also sent as the X-Request-Id response header.

string

Example 

{
  "code": "INVALID_INPUT"
}

Your next form could be the best-looking thing on your site.

Free forever. Unlimited responses. No signup to start.

Start building — free
4.9