# Get a form with its questions

`GET https://api.coach-platform.com/api/public/forms/{formId}`

Get one form including its full question set. Questions are grouped into steps: each entry of steps[] has a title and a fields[] array, and each field carries its label, fieldType, whether it is required, and its options where relevant. This is the endpoint that tells you what a trainee was actually asked; GET /forms only lists metadata.

- Resource: Forms
- Authentication: API key in the `Authorization: Bearer cp_live_...` header
- HTML version: https://www.coach-platform.com/docs/api/reference/get-forms-form-id
- OpenAPI spec: https://www.coach-platform.com/openapi.json

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `formId` | string | Yes |   |

## Responses

| Status | Description |
|---|---|
| `200` OK | Successful response |
| `400` Bad Request |  |
| `401` Unauthorized |  |
| `403` Forbidden |  |
| `404` Not Found |  |
| `409` Conflict |  |
| `429` Too Many Requests |  |
| `500` Internal Server Error |  |

### 200 OK

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `data` | object | A single form including its questions. Questions live under steps[].fields[], not at the top level. |
| `data.id` | string |   |
| `data.coach` | string |   |
| `data.title` | string |   |
| `data.description` | string |   |
| `data.type` | string | registration = the join-time intake questionnaire. update = a recurring check-in form. Allowed values: `registration`, `update`. |
| `data.isActive` | boolean |   |
| `data.registrationOrder` | integer | Order this form is presented in during registration, when several registration forms exist. |
| `data.openAt` | object | When and how often the form opens for trainees. |
| `data.openAt.date` | string<date-time> |   |
| `data.openAt.recurrence` | string | How often the form reopens. Allowed values: `weekly`, `bi-weekly`, `tri-weekly`, `monthly`. |
| `data.openAt.openDays` | integer | How many days the form stays open once it opens. |
| `data.target` | string | Who the form is shown to. byLabels targets trainees carrying at least one of targetLabels. Allowed values: `allTrainees`, `males`, `females`, `byLabels`. |
| `data.targetLabels` | object[] | Labels this form targets. Only present when target is byLabels. |
| `data.targetLabels[].id` | string |   |
| `data.targetLabels[].text` | string |   |
| `data.targetLabels[].color` | string |   |
| `data.createdAt` | string<date-time> |   |
| `data.steps` | object[] | The form’s pages, in order. Each holds the questions asked on that page. |
| `data.steps[].fields` | object[] |   |
| `data.steps[].fields[].id` | string |   |
| `data.steps[].fields[].label` | string | The question text shown to the trainee. |
| `data.steps[].fields[].fieldType` | string | How the question is answered, e.g. text, textarea, number, date, dropdown, checkbox, rating, slider, file, signature, weight, height, measurements, bodyFat, gender, dateOfBirth, activityLevel. contentBlock is not a question but static copy shown to the trainee. |
| `data.steps[].fields[].isRequired` | boolean |   |
| `data.steps[].fields[].placeholder` | string |   |
| `data.steps[].fields[].options` | string[] | Selectable values, for dropdown and similar field types. |
| `data.steps[].fields[].multiple` | boolean |   |

Example:

```json
{
  "data": {
    "id": "<string>",
    "coach": "<string>",
    "title": "<string>",
    "description": "<string>",
    "type": "registration",
    "isActive": true,
    "registrationOrder": 123,
    "openAt": {
      "date": "<date-time>",
      "recurrence": "weekly",
      "openDays": 123
    },
    "target": "allTrainees",
    "targetLabels": [
      {
        "id": "<string>",
        "text": "<string>",
        "color": "<string>"
      }
    ],
    "createdAt": "<date-time>",
    "steps": [
      {
        "fields": [
          {
            "id": "<string>",
            "label": "<string>",
            "fieldType": "<string>",
            "isRequired": true,
            "placeholder": "<string>",
            "options": [
              "<string>"
            ],
            "multiple": true
          }
        ]
      }
    ]
  }
}
```

### Error responses 400, 401, 403, 404, 409, 429, 500

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `error` | object |   |
| `error.code` | string |   |
| `error.message` | string |   |
| `error.fix` | string \| null |   |
| `error.details` | object \| null |   |
| `error.retryAfterMs` | number \| null |   |

Example:

```json
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "fix": "<string>",
    "details": {},
    "retryAfterMs": 123
  }
}
```

## Examples

### cURL

```bash
curl --request GET \
  --url 'https://api.coach-platform.com/api/public/forms/<formId>' \
  --header 'Authorization: Bearer cp_live_...'
```

### JavaScript (fetch)

```js
const response = await fetch('https://api.coach-platform.com/api/public/forms/<formId>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer cp_live_...',
  },
});

const data = await response.json();
```

## Related endpoints

- [List forms](https://www.coach-platform.com/docs/api/reference/get-forms/index.md): `GET /api/public/forms`. List forms (questionnaires) created by the coach.
- [List registration form responses](https://www.coach-platform.com/docs/api/reference/get-forms-registration/index.md): `GET /api/public/forms/registration`. List submitted registration (intake) form responses across every registration form, newest first.
- [List check-in responses](https://www.coach-platform.com/docs/api/reference/get-updates/index.md): `GET /api/public/updates`. List submitted update (check-in) form responses across every update form, newest first.
- [Respond to a check-in](https://www.coach-platform.com/docs/api/reference/post-updates-update-id-respond/index.md): `POST /api/public/updates/{updateId}/respond`. Respond to a submitted check-in.
- [Get a form response](https://www.coach-platform.com/docs/api/reference/get-forms-form-id-response-response-id/index.md): `GET /api/public/forms/{formId}/response/{responseId}`. Get a single submitted form response with its answers.
- [List responses to a form](https://www.coach-platform.com/docs/api/reference/get-forms-form-id-responses/index.md): `GET /api/public/forms/{formId}/responses`. List submitted responses for a form, newest first.
- Previous: [Respond to a check-in](https://www.coach-platform.com/docs/api/reference/post-updates-update-id-respond/index.md): `POST /api/public/updates/{updateId}/respond`. Respond to a submitted check-in.
- Next: [Get a form response](https://www.coach-platform.com/docs/api/reference/get-forms-form-id-response-response-id/index.md): `GET /api/public/forms/{formId}/response/{responseId}`. Get a single submitted form response with its answers.