> ## Documentation Index
> Fetch the complete documentation index at: https://docs.developers.mijnklantportaal.nl/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms

> This page gives instruction for working with Forms and your server. It's also possible to receive the entered data per email or saved it right into MijnKlantportaal, which does not require technical skills.

With Forms, you can bring your own interacting form to your customer portal. You can build whatever you want as long as it can be formatted as a submittable form, like a settings page for hosting settings. To let your form interact with your API, you should know how we call your APIs to send and (optional) retrieve data.

<Warning>
  #### Always respond with a 2xx status code

  If your endpoint does not response with a status code in the 200-range, MijnKlantportaal will consider the request, both sending and retrieving, as failed and so showing your customer an error message.
</Warning>

## <Icon icon="arrow-turn-up" size={25} /> Sending data

When your customer submits the form, we call your API endpoint with the HTTP method which you set yourself. The request will always contain the following headers:

| Header          | Description                                   | Example            |
| --------------- | --------------------------------------------- | ------------------ |
| `X-Customer-Id` | The ID of the customer which submits the form | `cst_123abc456def` |
| `X-Form-Id`     | The ID of the form which is submitted         | `frm_123abc456def` |

The body will contain JSON with your field names and the value entered by your customer. In case of a `GET` method, the request will be query parameters. An example:

**Your form:**

| Field name | Field value |
| ---------- | ----------- |
| `name`     | `John Doe`  |
| `age`      | `20`        |
| `sex`      | `male`      |

**The request body or query parameters to your endpoint:**

<CodeGroup>
  ```json JSON theme={null}
  {
      "name": "John Doe",
      "age": 20,
      "sex": "male"
  }
  ```

  ```txt Query params theme={null}
  ?name=John+Doe&age=20&sex=male
  ```
</CodeGroup>

## <Icon icon="arrow-turn-down" size={25} /> Retrieving data

You can pre-fill your form by setting a retrieving data endpoint. You can choose between a `GET` or `POST` method.
The endpoint should return a JSON-object with the fields which you have specified. **Any missing fields in your response will be considered as `null` and so left empty.** Any extra fields which are not corresponding with any of your form fields, will be discarded.

The request will always contain the following headers:

| Header          | Description                                   | Example            |
| --------------- | --------------------------------------------- | ------------------ |
| `Accept`        | MijnKlantportaal always expects a JSON-object | `application/json` |
| `X-Customer-Id` | The ID of the customer the data is for        | `cst_123abc456def` |
| `X-Form-Id`     | The ID of the form to fill                    | `frm_123abc456def` |

**Your form:**

| Field name |
| ---------- |
| `name`     |
| `sex`      |
| `age`      |

**The response body:**

```json JSON theme={null}
{
  "name": "John Doe",
  "nationality": "Dutch", // Will be ignored since field 'nationality' does not exist
  "sex": "male"
  // 'age' will be left empty in the form, since no data is returned for that field
}
```