Skip to main content
Returns responses for a specific form. When filtering by form ID, the API returns a maximum of 10 responses per request.

​
Request

Learn how to create an API key in the API Keys documentation. 
# 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

​
formId
string
required
The ID of the form to fetch responses for. This parameter is required when querying responses for a specific form.
​
returnPartials
boolean
default:"false"
Set 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

​
data
array
Array of response objects for the specified form. Limited to 10 most recent responses.

​
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": "[email protected]",
            "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.