> For the complete documentation index, see [llms.txt](https://formdr.gitbook.io/formdr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://formdr.gitbook.io/formdr/documentation/submissions/create-submission.md).

# Create Submission

This endpoint is used for creating a submission for your form(s). During onboarding, your administrator will have been informed about field names. Your submission data must match these names. An example has been provided down below.

## Create a new submission

<mark style="color:green;">`POST`</mark> `https://api.formdr.com/api/v1/practice/{practiceId}`

#### Query Parameters

| Name                                                | Type        | Description                               |
| --------------------------------------------------- | ----------- | ----------------------------------------- |
| firstName<mark style="color:red;">\*</mark>         | String      | Patient First Name                        |
| lastName<mark style="color:red;">\*</mark>          | String      | Patient Last Name                         |
| formUuid<mark style="color:red;">\*</mark>          | String      | Form UUID                                 |
| email                                               | String      | Patient Email Address                     |
| phone                                               | String      | Patient Phone Number                      |
| sendForm<mark style="color:red;">\*</mark>          | String      | "email" \| "phone" \| "both"              |
| submissionData<mark style="color:red;">\*</mark>    | JSON String | Stringified JSON data. See example below. |
| appointment<mark style="color:red;">\*</mark>       | String      | Must be in "YYYY-MM-DD hh:mm:ss" format.  |
| securityCode<mark style="color:red;">\*</mark>      | String      | Security code used to open the form.      |
| securityCodeHint<mark style="color:red;">\*</mark>  | String      | Hint provided for the security code.      |
| automaticReminder<mark style="color:red;">\*</mark> | Boolean     | Automatic appointment reminder.           |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{
    "submissionId": number,
    "formId": number,
    "formName": string,
    "name": string,
    "formUuid": string,
    "submissionToken": string,
    "submissionUrl": string, //publicly accessible URL for patient
}
```

{% endtab %}

{% tab title="401: Unauthorized No access token provided." %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

```
You must supply an email when sendform === 'email' and you must supply phone when sendForm === 'phone'. Obviously, supply both when sendForm === 'both'
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
firstName and lastName parameters are used for patient records and will be the same when you're searching for records. **Warning: these differ from firstName and lastName in the submissionData.**
{% endhint %}

The submissionData is a JSON string that maps to each field in the form. During form creation, each field is generated with a unique ID. This ID can be changed to best suit your purposes. Some fields, like the Single-Select Option field, can be given specific values.&#x20;

You will notice below there is a takingMedicineCheckbox which returns a boolean value, but a painYesNo variable that is a string of 'true'. This is because the field is a Single-Select Option field. The default value of which is 'true', but it can be any value that the form creator wants.

{% hint style="danger" %}
This endpoint does not enforce key names. Any typos or extra keys will result in the insertion of this data and may cause display errors or data to not be displayed if it wasn't configured in the form.
{% endhint %}

#### submissionData example

```json
{
  "takingMedicineCheckbox": true,
  "signedDate": "11/07/2022",
  "firstName": "Aaron",
  "lastName": "Jackson",
  "painYesNo": "true"
}
```

{% hint style="info" %}
Use the standard **JSON.stringify()** function to properly send JSON as a string parameter.
{% endhint %}

{% hint style="warning" %}
Once the patient has opened and submitted their form, the submissionUrl is no longer valid and cannot be accessed. Use the [Get Submission](/formdr/documentation/submissions/get-submission.md) endpoint to see their submitted data.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://formdr.gitbook.io/formdr/documentation/submissions/create-submission.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.