Formcrafts API v2

Authentication

Formcrafts uses API keys to authenticate users. You can create API keys under Organization → Settings → API Keys.

You can make 10,000 requests per hour. Rate limits are applied to each organization.

Authentication is done via HTTP basic auth. Your API key is the username, and password field should be left empty. A simply ping would return your account email. Use this link in the browser, and use your API key as username and leave the password blank

You can also open this in a browser ↗.

curl https://api.formcrafts.com/v2 -u MYAPIKEY:

{
  "organization_name": "My Organization"
}

Pagination

All list endpoints support limit, which is the number of items to return. The default is 10 and the maximum is 100.

curl https://api.formcrafts.com/v2/forms?limit=20 -u MYAPIKEY:

Additionally all list endpoints support before and after parameters. These are used to paginate through the list of items, based on the created_at field.

curl https://api.formcrafts.com/v2/forms?limit=5&after=2024-02-25 -u MYAPIKEY:

This will return 5 forms created after the date 2024-02-25.

The date format is YYYY-MM-DD, or ISO 8601 format.

Get workspaces

List all workspaces in the organization.

curl https://api.formcrafts.com/v2/workspaces -u MYAPIKEY:

{
  "has_more": false,
  "data": [
    {
      "id": "efgh5678",
      "name": "Marketing",
      "created_at": "2024-02-05T14:29:38.856Z"
    },
    {
      "id": "e132bf87",
      "name": "Sales",
      "created_at": "2023-02-05T14:29:38.558Z"
    }
  ]
}

Get forms

List all forms in the organization.

curl https://api.formcrafts.com/v2/forms -u MYAPIKEY:

{
  "has_more": true,
  "data": [
    {
      "id": "abcd1234",
      "name": "Contact us",
      "workspace_id": "efgh5678",
      "enabled": true,
      "created_at": "2023-01-28T08:59:16.910Z",
      "updated_at": "2024-02-28T10:42:33.021Z"
    }
  ]
}

created_at is the form creation date.
updated_at is the last published date.

Get form details

Get details of a form.

curl https://api.formcrafts.com/v2/forms/[id] -u MYAPIKEY:

{
  "id": "abcd1234",
  "name": "Contact us",
  "workspace_id": "efgh5678",
  "enabled": true,
  "responses": 24,
  "fields": [
    {
      "id": "field1",
      "type": "one_line_input",
      "page": "page1",
      "label": "Name",
      "description": null,
      "required": false
    }
  ],
  "pages": [
    {
      "id": "page1",
      "label": "Personal info"
    }
  ],
  "created_at": "2023-01-28T08:59:16.910Z",
  "updated_at": "2024-02-28T10:42:33.021Z"
}

responses is the current number of responses (in live or test mode).

Get form responses

List all responses for a form. Note that only live form responses are returned by this endpoint.

curl https://api.formcrafts.com/v2/forms/[id]/responses -u MYAPIKEY:

{
  "has_more": false,
  "data": [
    {
      "id": 1,
      "test": false,
      "visitor": {
        "country": "CA",
        "region": "CA-ON",
        "city": "Toronto",
        "time_spent": 8200,
        "url": "https://example.com/contact-us"
      },
      "workflows": [],
      "response": [
        {
          "field_id": "field1",
          "field_type": "one_line_input",
          "value_type": "string",
          "value": "Jane Doe"
        }
      ],
      "created_at": "2024-02-28T12:06:37.122Z",
      "updated_at": "2024-02-28T12:06:37.122Z"
    }
  ]
}

field_type is one of one_line_input, credit_card, phone, file_upload, table_entry, slider, nps, rating, comment, hidden, email, date, calendly, time, rich_text, multiple_choice, dropdown, address

value_type can be string, number, options, files, table, or address

When value_type is options, value is an array of objects:

{
  "field_id": "field1",
  "field_type": "multiple_choice",
  "value_type": "options",
  "value": [
    {
      "label": "Option 1",
      "value": "Option 1"
    },
    {
      "label": "Option 2",
      "value": "Option 2"
    }
  ]
}

When value_type is files, value is an array of file objects:

{
  "field_id": "field1",
  "field_type": "file_upload",
  "value_type": "files",
  "value": [
    {
      "id": "8ed2f42a-2e94-4288-976a-5891d439cde5",
      "name": "picture.png",
      "type": "image/png",
      "size": 32500
    },
    {
      "id": "4ce2a5b0-867c-4835-b19b-d16e06049def",
      "name": "photo-id.jpg",
      "type": "image/jpeg",
      "size": 28100
    }    
  ]
}

When value_type is table, value is an object with headers and rows:

{
  "field_id": "field1",
  "field_type": "table_entry",
  "value_type": "table",
  "value": {
    "headers": [
      "Name",
      "Age",
      "Department"
    ],
    "rows": [
      [
        "Jane",
        "32",
        "Marketing"
      ],
      [
        "John",
        "28",
        "Sales"
      ]
    ]
  }
}

When value_type is address, value is an object with street, city, state, zip, country:

{
  "field_id": "field1",
  "field_type": "address",
  "value_type": "address",
  "value": {
    "full_address": "123 Main St, Toronto, ON M5V 1A1, Canada",
    "line1": "123 Main St",
    "line2": "Unit 101",
    "city": "Toronto",
    "state": "ON",
    "postal_code": "M5V 1A1",
    "country": "Canada"
  }
}

Get files

List all files uploaded in the organization.

curl https://api.formcrafts.com/v2/files -u MYAPIKEY:

{
  "has_more": true,
  "data": [
    {
      "id": "8ed2f42a-2e94-4288-976a-5891d439cde5",
      "name": "picture.png",
      "type": "image/png",
      "size": 32500,
      "created_at": "2024-02-28T12:54:07.961Z",
      "updated_at": "2024-02-28T12:54:07.961Z"
    }
  ]
}

Get file content

Get the content of a file.

curl https://api.formcrafts.com/v2/files/[id]/content -u MYAPIKEY:

This will return the file content.