Get Form Responses
Retrieve responses for a specific form
/api/v1/responsesGet responses for a specific form
Returns responses for a specific form. When filtering by form ID, the API returns a maximum of 10 responses per request.
Request
# Get completed responses only
curl -X GET 'https://forms.withsurface.com/api/v1/responses?formId=your-form-id' \
-H 'x-api-key: your-api-key-here'
# Include partial responses
curl -X GET 'https://forms.withsurface.com/api/v1/responses?formId=your-form-id&returnPartials=true' \
-H 'x-api-key: your-api-key-here'Parameters
formIdquerystringrequiredThe ID of the form to fetch responses for. This parameter is required when querying responses for a specific form.
returnPartialsquerybooleandefault: falseSet to true to include partial/incomplete responses in the results. When set to false (default), only completed responses are returned. Partial responses are those where the user started filling out the form but did not complete the submission.
Response
dataarrayArray of response objects for the specified form. Limited to 10 most recent responses.
›Response object properties
idstringUnique identifier for the response.
createdAtstringISO 8601 timestamp of when the response was created.
updatedAtstringISO 8601 timestamp of when the response was last updated.
dataUpdatedAtstringISO 8601 timestamp of when the response data was last updated.
finishedbooleanWhether the response is complete (true) or partial (false).
statusnumberStatus code of the response.
formIdstringID of the form this response belongs to.
versionstringVersion of the response format.
dataarrayArray of question responses, each containing a response object and questionId. Each response object follows a specific shape based on the component type. See the Component Response Shapes documentation for details on all supported component types.
metaobjectMetadata associated with the response, including leadId.
personAttributesobjectAttributes about the person who submitted the response, including IP address, country, and form visit statistics.
Example Response
{
"data": [
{
"id": "cmasda085pa0018js0barsadxn5b",
"createdAt": "2026-01-20T19:45:59.519Z",
"updatedAt": "2026-01-20T19:46:37.149Z",
"dataUpdatedAt": "2026-01-20T19:46:01.725Z",
"finished": true,
"status": 4,
"formId": "casdkgkufzp0001kw0btrmz1asd",
"version": "2.0",
"data": [
{
"response": {
"type": "IdentityInfo",
"headline": "Identity Info",
"emailAddress": "john.doe@example.com",
"firstName": "John",
"lastName": "Doe",
"companyName": "Example Inc.",
"componentShapeVersion": "2.0"
},
"questionId": "gOyoYYzZRnvo"
},
],
"meta": {
"leadId": "lead_1234567890"
},
"personAttributes": {
"ip": "123.45.67.89",
"country": "United States",
"visitedForm": 1,
"completedForm": 0
}
},
]
}When fetching by formId, the API returns a maximum of 10 responses per request. To retrieve more responses, you may need to implement pagination or use the environment-wide endpoint.