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
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
Authorization
string
Bearer API_KEY
{
"success": true,
"data": [
{
"id": "6022518865701d3d05b48c71",
"name": "Sample Form",
"description": "My sample form",
"coverImage": null,
"folder": null,
"createdBy": {
"id": "5fa7ebdac9c3dc06f8e17452",
"firstName": "Test",
"lastName": "User",
"email": "testuser@softcom.ng",
"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
id
string
Id of the form
Headers
Authorization
string
Bearer API_KEY
{
"success": true,
"data": {
"id": "6022518865701d3d05b48c71",
"name": "Sample Form",
"description": "My sample form",
"coverImage": null,
"folder": null,
"createdBy": {
"id": "5fa7ebdac9c3dc06f8e17452",
"firstName": "Test",
"lastName": "User",
"email": "testuser@softcom.ng",
"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
id
string
Id of the form to retrieve responses for
Query Parameters
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
Authorization
string
Bearer API_KEY
{
"success": true,
"data": [
{
"id": "5fce0444c3760132f0bafa76",
"agent": {
"id": "5fb39b81020a981b2bfa9dfa",
"firstName": "Survey",
"lastName": "Participant",
"email": "survey-participant@useforms.com",
"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": "testrespondent@gmail.com",
"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
responseId
string
Id of the response to retrieve
id
string
Id of the form the response belongs to
Headers
Authorization
string
Bearer API_KEY
{
"success": true,
"data": {
"id": "5fce0444c3760132f0bafa76",
"agent": {
"id": "5fb39b81020a981b2bfa9dfa",
"firstName": "Survey",
"lastName": "Participant",
"email": "survey-participant@useforms.com",
"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": "testrespondent@gmail.com",
"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
}
}Last updated
Was this helpful?