← Files DocuSealARCHIVED FILE
skills/docuseal-code/references/api/create-a-submission-from-pdf.md
17.7 KB · Oct 8, 2026 · 00:04 UTC
# Create a submission from PDF
`POST /submissions/pdf`
**Pro / Cloud Sandbox plan required.**
The API endpoint provides the functionality to create one-off submission request from a PDF. Use `{{Field Name;role=Signer1;type=date}}` text tags to define fillable fields in the document. See [https://www.docuseal.com/examples/fieldtags.pdf](https://www.docuseal.com/examples/fieldtags.pdf) for more text tag formats. Or specify the exact pixel coordinates of the document fields using `fields` param.
## Request Body
| Property | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | no | Name of the document submission. Example: `Test Submission Document` |
| `send_email` | `boolean` | no | Set `false` to disable signature request emails sending. Default: `true` |
| `send_sms` | `boolean` | no | Set `true` to send signature request via phone number and SMS. Default: `false` |
| `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. Default: `preserved` Values: `random`, `preserved`. |
| `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. Example: `2024-09-01 12:00:00 UTC` |
| `template_ids` | `array[]` | no | An optional array of template IDs to use in the submission along with the provided documents. This can be used to create multi-document submissions when some of the required documents exist within templates. |
| `documents` | `array[]` | yes | An array of PDF documents to create a submission. |
| `documents[].name` | `string` | yes | Name of the document. |
| `documents[].file` | `string` | yes | Base64-encoded content of the PDF file or downloadable file URL. Example: `base64` |
| `documents[].fields` | `array[]` | no | Fields are optional if you use {{...}} text tags to define fields in the document. |
| `documents[].fields[].name` | `string` | no | Name of the field. |
| `documents[].fields[].type` | `string` | no | Type of the field (e.g., text, signature, date, initials). Values: `heading`, `text`, `signature`, `initials`, `date`, `number`, `image`, `checkbox`, `multiple`, `file`, `radio`, `select`, `cells`, `stamp`, `payment`, `phone`, `verification`, `kba`, `strikethrough`. |
| `documents[].fields[].role` | `string` | no | Role name of the signer. |
| `documents[].fields[].required` | `boolean` | no | Indicates if the field is required. |
| `documents[].fields[].title` | `string` | no | Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown. |
| `documents[].fields[].description` | `string` | no | Field description displayed on the signing form. Supports Markdown. |
| `documents[].fields[].areas` | `array[]` | no | List of areas where the field is located in the document. |
| `documents[].fields[].options` | `array[]` | no | An array of option values for `select` field type. Example: `["Option A", "Option B"]` |
| `documents[].position` | `integer` | no | Document position in the submission. If not specified, the document will be added in the order it appears in the documents array. |
| `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. Example: `First Party` |
| `submitters[].email` | `string` | no | The email address of the submitter. Example: `john.doe@example.com` |
| `submitters[].phone` | `string` | no | The phone number of the submitter, formatted according to the E.164 standard. Example: `+1234567890` |
| `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. Example: `{ "customField": "value" }` |
| `submitters[].send_email` | `boolean` | no | Set `false` to disable signature request emails sending only for this submitter. Default: `true` |
| `submitters[].send_sms` | `boolean` | no | Set `true` to send signature request via phone number and SMS. Default: `false` |
| `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. Default: `false` |
| `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. Default: `false` |
| `submitters[].invite_by` | `string` | no | Set the role name of the previous party that should invite this party via email. |
| `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. Example: `First Name` |
| `submitters[].fields[].default_value` | `string / integer / number / boolean / array` | 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. Example: `Acme` |
| `submitters[].fields[].readonly` | `boolean` | no | Set `true` to make it impossible for the submitter to edit predefined field value. Default: `false` |
| `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[].preferences` | `object` | no | Field display preferences. |
| `submitters[].roles` | `array[]` | no | A list of roles for the submitter. Use this param to merge multiple roles into one submitter. |
| `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}}. |
| `flatten` | `boolean` | no | Remove PDF form fields from the documents. Default: `false` |
| `merge_documents` | `boolean` | no | Set `true` to merge the documents into a single PDF file. Default: `false` |
| `remove_tags` | `boolean` | no | Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing. Default: `true` |
## Code Examples
### cURL
```curl
curl --request POST \
--url https://api.docuseal.com/submissions/pdf \
--header 'X-Auth-Token: API_KEY' \
--header 'content-type: application/json' \
--data '{"name":"Test Submission Document","documents":[{"name":"string","file":"base64","fields":[{"name":"string","areas":[{"x":0,"y":0,"w":0,"h":0,"page":1}]}]}],"submitters":[{"role":"First Party","email":"john.doe@example.com"}]}'
```
### CLI
```shell
docuseal submissions create-pdf --name "Test Submission Document" \
-d "documents[0][name]=string" \
-d "documents[0][file]=/path/to/file" \
-d "documents[0][fields][0][name]=string" \
-d "documents[0][fields][0][areas][0][x]=0" \
-d "documents[0][fields][0][areas][0][y]=0" \
-d "documents[0][fields][0][areas][0][w]=0" \
-d "documents[0][fields][0][areas][0][h]=0" \
-d "documents[0][fields][0][areas][0][page]=1" \
-d "submitters[0][role]=First Party" \
-d "submitters[0][email]=john.doe@example.com"
```
### Node.js (fetch)
```javascript
const fetch = require("node-fetch");
const resp = await fetch("https://api.docuseal.com/submissions/pdf", {
method: "POST",
headers: {
"X-Auth-Token": "API_KEY"
},
body: JSON.stringify({
name: "Test Submission Document",
documents: [
{
name: "string",
file: "base64",
fields: [
{
name: "string",
areas: [
{
x: 0,
y: 0,
w: 0,
h: 0,
page: 1
}
]
}
]
}
],
submitters: [
{
role: "First Party",
email: "john.doe@example.com"
}
]
})
});
const submission = await resp.json();
```
### JavaScript SDK
```javascript
const docuseal = require("@docuseal/api");
docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" });
const submission = await docuseal.createSubmissionFromPdf({
name: "Test Submission Document",
documents: [
{
name: "string",
file: "base64",
fields: [
{
name: "string",
areas: [
{
x: 0,
y: 0,
w: 0,
h: 0,
page: 1
}
]
}
]
}
],
submitters: [
{
role: "First Party",
email: "john.doe@example.com"
}
]
});
```
### TypeScript SDK
```typescript
import docuseal from "@docuseal/api";
docuseal.configure({ key: "API_KEY", url: "https://api.docuseal.com" });
const submission = await docuseal.createSubmissionFromPdf({
name: "Test Submission Document",
documents: [
{
name: "string",
file: "base64",
fields: [
{
name: "string",
areas: [
{
x: 0,
y: 0,
w: 0,
h: 0,
page: 1
}
]
}
]
}
],
submitters: [
{
role: "First Party",
email: "john.doe@example.com"
}
]
});
```
### Python SDK
```python
from docuseal import docuseal
docuseal.key = "API_KEY"
docuseal.url = "https://api.docuseal.com"
docuseal.create_submission_from_pdf({
"name": "Test Submission Document",
"documents": [
{
"name": "string",
"file": "base64",
"fields": [
{
"name": "string",
"areas": [
{
"x": 0,
"y": 0,
"w": 0,
"h": 0,
"page": 1
}
]
}
]
}
],
"submitters": [
{
"role": "First Party",
"email": "john.doe@example.com"
}
]
})
```
### Ruby SDK
```ruby
require "docuseal"
Docuseal.key = ENV["DOCUSEAL_API_KEY"]
Docuseal.url = "https://api.docuseal.com"
Docuseal.create_submission_from_pdf({
name: "Test Submission Document",
documents: [
{
name: "string",
file: "base64",
fields: [
{
name: "string",
areas: [
{
x: 0,
y: 0,
w: 0,
h: 0,
page: 1
}
]
}
]
}
],
submitters: [
{
role: "First Party",
email: "john.doe@example.com"
}
]
})
```
### PHP SDK
```php
$docuseal = new \Docuseal\Api('API_KEY', 'https://api.docuseal.com');
$docuseal->createSubmissionFromPdf([
'name' => 'Test Submission Document',
'documents' => [
[
'name' => 'string',
'file' => 'base64',
'fields' => [
[
'name' => 'string',
'areas' => [
[
'x' => 0,
'y' => 0,
'w' => 0,
'h' => 0,
'page' => 1
]
]
]
]
]
],
'submitters' => [
[
'role' => 'First Party',
'email' => 'john.doe@example.com'
]
]
]);
```
### Go SDK
```go
ds := docuseal.NewClient("API_KEY", docuseal.WithBaseURL("https://api.docuseal.com"))
submission, err := ds.CreateSubmissionFromPdf(context.Background(), &docuseal.CreateSubmissionFromPdfParams{
Name: "Test Submission Document",
Documents: []*docuseal.CreateSubmissionFromPdfDocumentParams{
{
Name: "string",
File: "base64",
Fields: []*docuseal.CreateSubmissionDocumentFieldParams{
{
Name: "string",
Areas: []*docuseal.CreateSubmissionDocumentFieldAreaParams{
{
X: 0,
Y: 0,
W: 0,
H: 0,
Page: 1,
},
},
},
},
},
},
Submitters: []*docuseal.CreateSubmissionSubmitterParams{
{
Role: "First Party",
Email: "john.doe@example.com",
},
},
})
```
### C# SDK
```csharp
var client = new DocusealClient("API_KEY", "https://api.docuseal.com");
var submission = await client.CreateSubmissionFromPdfAsync(new CreateSubmissionFromPdfParams
{
Name = "Test Submission Document",
Documents = [
new CreateSubmissionFromPdfDocumentParams
{
Name = "string",
File = "base64",
Fields = [
new CreateSubmissionDocumentFieldParams
{
Name = "string",
Areas = [
new CreateSubmissionDocumentFieldAreaParams
{
X = 0,
Y = 0,
W = 0,
H = 0,
Page = 1
},
]
},
]
},
],
Submitters = [
new CreateSubmissionSubmitterParams
{
Role = "First Party",
Email = "john.doe@example.com"
},
]
});
```
### Java SDK
```java
var client = new DocusealClient("API_KEY", "https://api.docuseal.com");
var submission = client.createSubmissionFromPdf(CreateSubmissionFromPdfParams.builder()
.documents(List.of(
CreateSubmissionFromPdfDocumentParams.builder()
.name("string")
.file("base64")
.fields(List.of(
CreateSubmissionDocumentFieldParams.builder()
.name("string")
.areas(List.of(
CreateSubmissionDocumentFieldAreaParams.builder()
.x(0)
.y(0)
.w(0)
.h(0)
.page(1)
.build()))
.build()))
.build()))
.submitters(List.of(
CreateSubmissionSubmitterParams.builder()
.role("First Party")
.email("john.doe@example.com")
.build()))
.name("Test Submission Document")
.build());
```
## Response Example
```json
{
"id": 5,
"name": "Test Submission",
"submitters": [
{
"id": 1,
"uuid": "884d545b-3396-49f1-8c07-05b8b2a78755",
"email": "john.doe@example.com",
"slug": "pAMimKcyrLjqVt",
"sent_at": "2025-06-02T15:55:51.310Z",
"opened_at": null,
"completed_at": null,
"declined_at": null,
"created_at": "2025-06-02T15:55:50.320Z",
"updated_at": "2025-06-02T15:55:50.320Z",
"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,
"reply_to": "reply@example.com",
"completed_redirect_url": "https://example.com/"
},
"role": "First Party",
"embed_src": "https://docuseal.com/s/pAMimKcyrLjqVt"
}
],
"source": "api",
"submitters_order": "preserved",
"status": "pending",
"schema": [
{
"name": "Demo PDF",
"attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf"
}
],
"fields": [
{
"name": "Name",
"type": "text",
"required": true,
"uuid": "d0bf3c0c-1928-40c8-80f9-d9f3c6ad4eff",
"submitter_uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7",
"areas": [
{
"page": 1,
"attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf",
"x": 0.403158189124654,
"y": 0.04211750189825361,
"w": 0.100684625476058,
"h": 0.01423690205011389
}
]
}
],
"expire_at": null,
"created_at": "2025-06-02T15:55:50.270Z"
}
```
## Related Guides
- [Use embedded text field tags in the PDF to create a fillable form](use-embedded-text-field-tags-in-the-pdf-to-create-a-fillable-form.md)
SHA-256: 66abad4de8d93bf26d19fc8d984d2466a56265f5028bf895aaee197f3b1a1ea8