# Create a submission

`POST /submissions`

This API endpoint allows you to create signature requests (submissions) for a document template and send them to the specified submitters (signers).  
**Related Guides**  
[Send documents for signature via API](https://www.docuseal.com/guides/send-documents-for-signature-via-api.md)  
[Pre-fill PDF document form fields with API](https://www.docuseal.com/guides/pre-fill-pdf-document-form-fields-with-api.md)


## Request body

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| template_id | integer | Yes | The unique identifier of the template. Document template forms can be created via the Web UI, [PDF and DOCX API](https://www.docuseal.com/guides/use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form.md), or [HTML API](https://www.docuseal.com/guides/create-pdf-document-fillable-form-with-html-api.md). |
| send_email | boolean | No | Set `false` to disable signature request emails sending. |
| send_sms | boolean | No | Set `true` to send signature request via phone number and SMS. |
| order | string | No | Pass `random` to send signature request emails to all parties right away. The order is `preserved` by default so the second party will receive a signature request email only after the document is signed by the first party. |
| completed_redirect_url | string | No | Specify URL to redirect to after the submission completion. |
| bcc_completed | string | No | Specify BCC address to send signed documents to after the completion. |
| reply_to | string | No | Specify Reply-To address to use in the notification emails. |
| expire_at | string | No | Specify the expiration date and time after which the submission becomes unavailable for signature. |
| variables | object | No | Dynamic content variables object. Variable values can be strings, numbers, arrays, objects, or HTML content used to generate styled text, paragraphs, and tables in dynamic template documents. |
| message | object | No | Custom signature request email message. |
| message.subject | string | No | Custom signature request email subject. |
| message.body | string | No | Custom signature request email body. Can include variables such as {{template.name}}, {{submission.name}}, {{submitter.link}}, {{account.name}}. |
| submitters | array | Yes | The list of submitters for the submission. |
| submitters.name | string | No | The name of the submitter. |
| submitters.role | string | No | The role name or title of the submitter. |
| submitters.email | string | No | The email address of the submitter. |
| submitters.phone | string | No | The phone number of the submitter, formatted according to the E.164 standard. |
| submitters.values | object | No | An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param. |
| submitters.external_id | string | No | Your application-specific unique string key to identify this submitter within your app. |
| submitters.completed | boolean | No | Pass `true` to mark submitter as completed and auto-signed via API. |
| submitters.metadata | object | No | Metadata object with additional submitter information. |
| submitters.send_email | boolean | No | Set `false` to disable signature request emails sending only for this submitter. |
| submitters.send_sms | boolean | No | Set `true` to send signature request via phone number and SMS. |
| submitters.reply_to | string | No | Specify Reply-To address to use in the notification emails for this submitter. |
| submitters.completed_redirect_url | string | No | Submitter specific URL to redirect to after the submission completion. |
| submitters.order | integer | No | The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array. |
| submitters.require_phone_2fa | boolean | No | Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents. |
| submitters.require_email_2fa | boolean | No | Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents. |
| submitters.message | object | No | Custom signature request email message for the submitter. |
| submitters.message.subject | string | No | Custom signature request email subject for the submitter. |
| submitters.message.body | string | No | Custom signature request email body for the submitter. Can include variables such as {{template.name}}, {{submission.name}}, {{submitter.link}}, {{account.name}}. |
| submitters.fields | array | No | A list of configurations for template document form fields. |
| submitters.fields.name | string | Yes | Document template field name. |
| submitters.fields.default_value | string | No | Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields. |
| submitters.fields.readonly | boolean | No | Set `true` to make it impossible for the submitter to edit predefined field value. |
| submitters.fields.required | boolean | No | Set `true` to make the field required. |
| submitters.fields.title | string | No | Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown. |
| submitters.fields.description | string | No | Field description displayed on the signing form. Supports Markdown. |
| submitters.fields.validation | object | No | Field validation rules. |
| submitters.fields.validation.pattern | string | No | HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification. |
| submitters.fields.validation.message | string | No | A custom error message to display on validation failure. |
| submitters.fields.validation.min | string | No | Minimum allowed number value or date depending on field type. |
| submitters.fields.validation.max | string | No | Maximum allowed number value or date depending on field type. |
| submitters.fields.validation.step | number | No | Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency. |
| submitters.fields.preferences | object | No | Field display preferences. |
| submitters.fields.preferences.font_size | integer | No | Font size of the field value in pixels. |
| submitters.fields.preferences.font_type | string | No | Font type of the field value. |
| submitters.fields.preferences.font | string | No | Font family of the field value. |
| submitters.fields.preferences.color | string | No | Font color of the field value. |
| submitters.fields.preferences.background | string | No | Field box background color. |
| submitters.fields.preferences.align | string | No | Horizontal alignment of the field text value. |
| submitters.fields.preferences.valign | string | No | Vertical alignment of the field text value. |
| submitters.fields.preferences.format | string | No | The data format for different field types. - Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY). - Signature field: accepts drawn, typed, drawn_or_typed (default), or upload. - Number field: accepts currency formats such as usd, eur, gbp. |
| submitters.fields.preferences.price | number | No | Price value of the payment field. Only for payment fields. |
| submitters.fields.preferences.currency | string | No | Currency value of the payment field. Only for payment fields. |
| submitters.fields.preferences.mask | string | No | Set `true` to make sensitive data masked on the document. |
| submitters.fields.preferences.reasons | array | No | An array of signature reasons to choose from. |
| submitters.roles | array | No | A list of roles for the submitter. Use this param to merge multiple roles into one submitter. |

## Code examples

### Node.js

```javascript
const fetch = require("node-fetch");

const resp = await fetch("https://api.docuseal.com/submissions", {
  method: "POST",
  headers: {
    "X-Auth-Token": "API_KEY"
  },
  body: JSON.stringify({
    template_id: 1000001,
    send_email: true,
    submitters: [
      {
        role: "First Party",
        email: "john.doe@example.com"
      }
    ]
  })
});

const submitters = await resp.json();
```

### JavaScript

```javascript
const docuseal = require("@docuseal/api");

docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" });

const submission = await docuseal.createSubmission({
  template_id: 1000001,
  send_email: true,
  submitters: [
    {
      role: "First Party",
      email: "john.doe@example.com"
    }
  ]
});
```

### TypeScript

```typescript
import docuseal from "@docuseal/api";

docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" });

const submission = await docuseal.createSubmission({
  template_id: 1000001,
  send_email: true,
  submitters: [
    {
      role: "First Party",
      email: "john.doe@example.com"
    }
  ]
});
```

### Python

```python
from docuseal import docuseal

docuseal.key = "API_KEY"
docuseal.url = "https://api.docuseal.com"

docuseal.create_submission({
  "template_id": 1000001,
  "send_email": True,
  "submitters": [
    {
      "role": "First Party",
      "email": "john.doe@example.com"
    }
  ]
})
```

### Ruby

```ruby
require "docuseal"

Docuseal.key = ENV["DOCUSEAL_API_KEY"]
Docuseal.url = "https://api.docuseal.com"

Docuseal.create_submission({
  template_id: 1000001,
  send_email: true,
  submitters: [
    {
      role: "First Party",
      email: "john.doe@example.com"
    }
  ]
})
```

### PHP

```php
$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com');

$docuseal->createSubmission([
  'template_id' => 1000001,
  'send_email' => true,
  'submitters' => [
    [
      'role' => 'First Party',
      'email' => 'john.doe@example.com'
    ]
  ]
]);
```

### Go

```go
ds := docuseal.NewClient("API_KEY", docuseal.WithBaseURL("https://api.docuseal.com"))

submission, err := ds.CreateSubmission(context.Background(), &docuseal.CreateSubmissionParams{
	TemplateID: 1000001,
	SendEmail: docuseal.Bool(true),
	Submitters: []*docuseal.CreateSubmissionSubmitterParams{
		{
			Role: "First Party",
			Email: "john.doe@example.com",
		},
	},
})
```

### JSON

```json
{
  "template_id": 1000001,
  "send_email": false,
  "send_sms": false,
  "order": "random",
  "completed_redirect_url": "string",
  "bcc_completed": "string",
  "reply_to": "string",
  "expire_at": "2024-09-01 12:00:00 UTC",
  "variables": {},
  "message": {
    "subject": "string",
    "body": "string"
  },
  "submitters": [
    {
      "name": "string",
      "role": "First Party",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "values": {},
      "external_id": "string",
      "completed": false,
      "metadata": {},
      "send_email": false,
      "send_sms": false,
      "reply_to": "string",
      "completed_redirect_url": "string",
      "order": 0,
      "require_phone_2fa": false,
      "require_email_2fa": false,
      "invite_by": "string",
      "message": {
        "subject": "string",
        "body": "string"
      },
      "fields": [
        {
          "name": "First Name",
          "default_value": null,
          "readonly": false,
          "required": false,
          "title": "string",
          "description": "string",
          "validation": {
            "pattern": "[A-Z]{4}",
            "message": "string",
            "min": null,
            "max": null,
            "step": 0.0
          },
          "preferences": {
            "font_size": 12,
            "font_type": "bold",
            "font": "Times",
            "color": "black",
            "background": "black",
            "align": "center",
            "valign": "top",
            "format": "DD/MM/YYYY",
            "price": 99.99,
            "currency": "EUR",
            "mask": null,
            "reasons": [
              "string"
            ]
          }
        }
      ],
      "roles": [
        "string"
      ]
    }
  ]
}
```

### PHP (cURL)

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.docuseal.com/submissions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'template_id' => 1000001,
    'send_email' => null,
    'submitters' => [
        [
                'role' => 'First Party',
                'email' => 'john.doe@example.com'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "X-Auth-Token: API_KEY",
    "content-type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

### C#

```csharp
var client = new DocusealClient("API_KEY", "https://api.docuseal.com");

var submission = await client.CreateSubmissionAsync(new CreateSubmissionParams
{
    TemplateId = 1000001,
    SendEmail = true,
    Submitters = [
        new CreateSubmissionSubmitterParams
        {
            Role = "First Party",
            Email = "john.doe@example.com"
        },
    ]
});
```

### Java

```java
var client = new DocusealClient("API_KEY", "https://api.docuseal.com");

var submission = client.createSubmission(CreateSubmissionParams.builder()
    .templateId(1000001)
    .submitters(List.of(
      CreateSubmissionSubmitterParams.builder()
        .role("First Party")
        .email("john.doe@example.com")
        .build()))
    .sendEmail(true)
    .build());
```

### cURL

```curl
curl --request POST \
  --url https://api.docuseal.com/submissions \
  --header 'X-Auth-Token: API_KEY' \
  --header 'content-type: application/json' \
  --data '{"template_id":1000001,"send_email":true,"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}'
```

### CLI

```shell
docuseal submissions create --template-id 1000001 --send-email \
  -d "submitters[0][role]=First Party" \
  -d "submitters[0][email]=john.doe@example.com"
```

## Example response

```json
[
  {
    "id": 1,
    "submission_id": 1,
    "uuid": "884d545b-3396-49f1-8c07-05b8b2a78755",
    "email": "john.doe@example.com",
    "slug": "pAMimKcyrLjqVt",
    "sent_at": "2023-12-13T23:04:04.252Z",
    "opened_at": null,
    "completed_at": null,
    "declined_at": null,
    "created_at": "2023-12-14T15:50:21.799Z",
    "updated_at": "2023-12-14T15:50:21.799Z",
    "name": "string",
    "phone": "+1234567890",
    "external_id": "2321",
    "metadata": {
      "customData": "custom value"
    },
    "status": "sent",
    "values": [
      {
        "field": "Full Name",
        "value": "John Doe"
      }
    ],
    "preferences": {
      "send_email": true,
      "send_sms": false
    },
    "role": "First Party",
    "embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt"
  }
]
```