Forms

The Forms API lets you retrieve forms in your workspace and the responses that have been gathered for those forms.

Forms

Get Forms

GET https://api.developer.useforms.com/v1/forms

Returns the list of the forms in your workspace.

Query Parameters

Name	Type	Description
name	string	Used to filter form using the exact name of the form
startDate	string	Used to retrieve all forms created after the specified date
endDate	string	Used to retrieve all forms created before the specified date
folder	string	Used to filter forms using the id of the folder the form belongs to
page	number	Page number to return Default: 1
perPage	number	Number of records to return per page Default: 50
sortBy	string	Property to use in sorting the forms. Valid: [createdAt, name] Default: createdAt
sortOrder	string	Specify whether to sort records in ascending or descending order. Valid: [asc, desc] Default: desc
includeData	boolean	Specify whether to return the data key in the endpoint response. Valid: [true, false] Default: true
includeMetadata	boolean	Specify whether to return the _metadata key in the endpoint response. Valid: [true, false] Default: true

Headers

Name	Type	Description
Authorization	string	Bearer API_KEY

200

{
    "success": true,
    "data": [
        {
            "id": "6022518865701d3d05b48c71",
            "name": "Sample Form",
            "description": "My sample form",
            "coverImage": null,
            "folder": null,
            "createdBy": {
                "id": "5fa7ebdac9c3dc06f8e17452",
                "firstName": "Test",
                "lastName": "User",
                "email": "[e-mail]",
                "profilePicture": null
            },
            "modifiedBy": null,
            "plugins": {
                "googleSheetsEnabled": false,
                "googleSheetsUrl": null,
                "powerbiEnabled": false,
                "powerbiDashboardUrl": null,
                "powerbiDatasetName": null,
                "webhookEnabled": false,
                "webhookActive": null,
                "webhookUrl": null
            },
            "createdAt": "2021-02-09T09:10:32.126Z",
            "updatedAt": "2021-02-09T09:10:32.126Z"
        }
    ],
    "_metadata": {
        "total": 14,
        "perPage": 1,
        "pageCount": 14,
        "pageLinks": {
            "current": "https://api.developer.useforms.com/v1/forms?perPage=1&page=1",
            "next": "https://api.developer.useforms.com/v1/forms?perPage=1&page=2",
            "previous": null
        }
    }
}

Get Form By Id

GET https://api.developer.useforms.com/v1/forms/:id

Returns a single form using the form's id.

Path Parameters

Name	Type	Description
id	string	Id of the form

Headers

Name	Type	Description
Authorization	string	Bearer API_KEY

200

{
    "success": true,
    "data": {
        "id": "6022518865701d3d05b48c71",
        "name": "Sample Form",
        "description": "My sample form",
        "coverImage": null,
        "folder": null,
        "createdBy": {
            "id": "5fa7ebdac9c3dc06f8e17452",
            "firstName": "Test",
            "lastName": "User",
            "email": "[e-mail]",
            "profilePicture": null
        },
        "modifiedBy": null,
        "plugins": {
            "googleSheetsEnabled": true,
            "googleSheetsUrl": null,
            "powerbiEnabled": false,
            "powerbiDashboardUrl": null,
            "powerbiDatasetName": null,
            "webhookEnabled": false,
            "webhookActive": null,
            "webhookUrl": null
        },
        "createdAt": "2020-11-08T13:26:18.436Z",
        "updatedAt": "2021-03-19T09:52:15.382Z",
        "formData": [
            {
                "label": "Page 1",
                "pos": 1,
                "elements": [
                    {
                        "type": "phoneNumber",
                        "unique_id": "fn_CRte5sFh1qKn3yhXgS",
                        "label": "Phone number",
                        "enabled": true,
                        "hidden": false,
                        "placeholder": "",
                        "description": "",
                        "maxLength": "",
                        "minLength": "",
                        "isMandatory": false
                    }
                ]
            }
        ]
    }
}

Form Responses

Get Form Responses

GET https://api.developer.useforms.com/v1/forms/:id/responses

Returns the list of the responses that have been collected for a particular form.

Path Parameters

Name	Type	Description
id	string	Id of the form to retrieve responses for

Query Parameters

Name	Type	Description
status	string	Used to filter form responses using the status of the response. Valid: [pending, accepted, rejected]
formShare	string	Used to filter form responses using the id of the form share the response belongs to.
country	string	Used to filter form responses using the country the response was submitted in
state	string	Used to filter form responses using the state the response was submitted in
startDate	string	Used to retrieve all form responses submitted after the specified date
endDate	string	Used to retrieve all form responses submitted before the specified date
page	number	Page number to return Default: 1
perPage	number	Number of records to return per page Default: 50
sortBy	string	Property to use in sorting the form responses. Valid: [createdAt, name] Default: createdAt
sortOrder	string	Specify whether to sort records in ascending or descending order. Valid: [asc, desc] Default: desc
includeData	boolean	Specify whether to return the data key in the endpoint response. Valid: [true, false] Default: true
includeMetadata	boolean	Specify whether to return the _metadata key in the endpoint response. Valid: [true, false] Default: true

Headers

Name	Type	Description
Authorization	string	Bearer API_KEY

200

{
    "success": true,
    "data": [
        {
            "id": "5fce0444c3760132f0bafa76",
            "agent": {
                "id": "5fb39b81020a981b2bfa9dfa",
                "firstName": "Survey",
                "lastName": "Participant",
                "email": "[e-mail]",
                "phone": null,
                "profilePicture": null
            },
            "form": {
                "id": "5fc55f3ae741f90dba0beee4",
                "name": "Sample Form",
                "description": "My sample form",
                "createdAt": "2020-11-30T21:08:10.616Z",
                "updatedAt": "2021-03-19T13:04:52.037Z"
            },
            "formShare": {
                "id": "5fc55fd0e741f90dba0beee6",
                "name": "January batch",
                "isSuspended": false,
                "dueDate": null,
                "createdAt": "2020-11-30T21:10:40.269Z",
                "updatedAt": "2021-01-18T13:32:33.422Z"
            },
            "status": "pending",
            "rejectionMessage": null,
            "location": {
                "latitude": 37.09024,
                "longitude": -95.712891,
                "country": "UNITED STATES",
                "state": "KANSAS",
                "lga": "INDEPENDENCE",
                "city": null,
                "address": "5000 Estate Enighed, Independence, KS 67301, USA"
            },
            "responses": [
                {
                    "page": "Page 1",
                    "answers": [
                        {
                            "question": "What is your email?",
                            "answer": "[e-mail]",
                            "type": "email"
                        },
                        {
                            "question": "Leave a note for us",
                            "answer": null,
                            "type": "longText"
                        },
                        {
                            "question": "What is your phone number?",
                            "answer": null,
                            "type": "phoneNumber"
                        }
                    ]
                }
            ],
            "createdAt": "2020-12-07T10:30:28.867Z",
            "duration": 35
        }
    ],
    "_metadata": {
        "total": 3,
        "perPage": 1,
        "pageCount": 3,
        "pageLinks": {
            "current": "https://api.developer.useforms.com/v1/forms/5fc55f3ae741f90dba0beee4/responses?perPage=1&page=1",
            "next": "https://api.developer.useforms.com/v1/forms/5fc55f3ae741f90dba0beee4/responses?perPage=1&page=2",
            "previous": null
        }
    }
}

Get Form Response By Id

GET https://api.developer.useforms.com/v1/forms/:id/responses/:responseId

Returns a single form response using the the form id and the response id.

Path Parameters

Name	Type	Description
responseId	string	Id of the response to retrieve
id	string	Id of the form the response belongs to

Headers

Name	Type	Description
Authorization	string	Bearer API_KEY

200

{
    "success": true,
    "data": {
        "id": "5fce0444c3760132f0bafa76",
        "agent": {
            "id": "5fb39b81020a981b2bfa9dfa",
            "firstName": "Survey",
            "lastName": "Participant",
            "email": "[e-mail]",
            "phone": null,
            "profilePicture": null
        },
        "form": {
            "id": "5fc55f3ae741f90dba0beee4",
            "name": "Sample Form",
            "description": "My sample form",
            "createdAt": "2020-11-30T21:08:10.616Z",
            "updatedAt": "2021-03-19T13:08:42.208Z"
        },
        "formShare": {
            "id": "5fc55fd0e741f90dba0beee6",
            "name": "January batch",
            "isSuspended": false,
            "dueDate": null,
            "createdAt": "2020-11-30T21:10:40.269Z",
            "updatedAt": "2021-01-18T13:32:33.422Z"
        },
        "status": "pending",
        "rejectionMessage": null,
        "location": {
            "latitude": 37.09024,
            "longitude": -95.712891,
            "country": "UNITED STATES",
            "state": "KANSAS",
            "lga": "INDEPENDENCE",
            "city": null,
            "address": "5000 Estate Enighed, Independence, KS 67301, USA"
        },
        "responses": [
            {
                "page": "Page 1",
                "answers": [
                    {
                        "question": "What is your email?",
                        "answer": "[e-mail]",
                        "type": "email"
                    },
                    {
                        "question": "Leave a note for us",
                        "answer": null,
                        "type": "longText"
                    },
                    {
                        "question": "What is your phone number?",
                        "answer": null,
                        "type": "phoneNumber"
                    }
                ]
            }
        ],
        "createdAt": "2020-12-07T10:30:28.867Z",
        "duration": 35
    }
}