List forms

GET

/v1/forms

const url = 'https://platform.fomr.io/v1/forms?is_template=true&status=draft&sort=updated_at&order=asc&limit=25';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://platform.fomr.io/v1/forms?is_template=true&status=draft&sort=updated_at&order=asc&limit=25' \
  --header 'Authorization: Bearer <token>'

Lists the forms of the organization, most recently changed first. Set is_template to true to list Private Templates instead. Read further pages by passing next_cursor back as cursor until it comes back null. Needs forms:read or templates:read. Costs 1 API credit.

Authorizations

bearerAuth

Parameters

Query Parameters

is_template

string

default: false

Allowed values: true false

List Private Templates instead of forms.

status

string

Allowed values: draft published archived

Keep only forms in this state. Omit for every state.

workspace_public_id

string

>= 4 characters <= 4 characters

Keep only forms in this workspace. Omit for every workspace.

string

<= 100 characters

Keep only forms whose name contains this fragment, ignoring case.

sort

string

default: updated_at

Allowed values: updated_at created_at name

The field the page is ordered by.

order

string

default: desc

Allowed values: asc desc

The direction of the sort.

limit

integer

default: 25 >= 1 <= 100

How many forms one page holds.

cursor

string

The next_cursor of the previous page. Opaque: pass it back exactly as received.

Responses

200

Default Response

application/json

object

data

required

One page of forms, ordered by the requested sort.

Array<object>

object

public_id

required

The public ID of the form. Use it in every other form call.

string

>= 10 characters <= 10 characters /^[A-Za-z0-9_-]+$/

name

required

Form name shown in the app.

string

is_template

required

Whether the resource is a Private Template rather than a form.

boolean

status

required

Lifecycle state: draft while nothing is published, published once a version is live, archived when the form is no longer editable.

string

Allowed values: draft published archived

has_unpublished_changes

required

Whether publishing would change what respondents see. True for a form that has never been published.

boolean

published_version

required

Any of:

integer
null

integer

>= -9007199254740991 <= 9007199254740991

published_at

required

Any of:

string
null

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))$/

source_template_public_id

required

Any of:

string
null

string

>= 10 characters <= 10 characters /^[A-Za-z0-9_-]+$/

workspace_public_id

required

The workspace the form belongs to. Change it with the move operation.

string

>= 4 characters <= 4 characters

access

required

Whether the form takes submissions.

object

is_closed

required

Whether the form was closed by hand.

boolean

close_at

required

Any of:

string
null

string format: date-time

open_at

required

Any of:

string
null

string format: date-time

accepting_submissions

required

Whether the form takes a submission right now. Derived from is_closed, the schedule, and whether a version is published.

boolean

duplicate_response_rule

required

Any of:

object
null

One of:

One completed response per respondent IP address.

object

type

required

The matching method: ip_address, submission_id, or component.

string

Allowed value: ip_address

submissions

required

How many submissions the form holds.

object

completed_count

required

Submissions the respondent finished.

integer

>= -9007199254740991 <= 9007199254740991

partial_count

required

Partial responses captured before the respondent finished.

integer

>= -9007199254740991 <= 9007199254740991

urls

required

Where to open the form.

object

editor

required

The form in the fomr editor. Always present; opening it needs an app session, not a token.

string format: uri

share

required

Any of:

string
null

string format: uri

domain

required

Any of:

object
null

object

host

required

The custom domain of the share link, such as forms.example.com.

string

>= 4 characters <= 55 characters /^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$/

slug

required

The path after the host, starting with a slash.

string

>= 1 characters <= 100 characters /^[a-zA-Z0-9-_/-]+$/

status

required

Verification state of the domain: verified, pending, or failed.

string

Allowed values: verified pending failed

is_active

required

Whether the plan of the organization keeps the domain serving forms.

boolean

url

required

The link on the custom domain. It becomes urls.share once the domain is verified and active and a version is published.

string format: uri

preview_image_url

required

Any of:

string
null

string

created_at

required

When the form was created.

string format: date-time

updated_at

required

When the form was last changed.

string format: date-time

next_cursor

required

Any of:

string
null

string

Example

{
  "data": [
    {
      "status": "draft",
      "access": {
        "duplicate_response_rule": {
          "type": "ip_address"
        }
      },
      "domain": {
        "status": "verified"
      }
    }
  ]
}

400

Default Response

application/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
number

string

Example

{
  "code": "INVALID_INPUT"
}

401

Default Response

application/json

object

code

required

The stable code to branch on.

string

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

Default Response

application/json

object

code

required

The stable code to branch on.

string

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
null

string

Example

{
  "code": "INVALID_INPUT"
}

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.

application/json

Any of:

object
object

object

code

required

The stable code to branch on.

string

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
null

string format: date-time

resets_at

required

When the window that rejected the call ends.

string format: date-time

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
null

string

Example

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

500

Default Response

application/json

object

code

required

The stable code to branch on.

string

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

List forms

Authorizations

Parameters

Query Parameters

Responses

200

Example

400

Example

401

Example

403

Example

429

Example

500

Example

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