---
title: "Create a submission from HTML"
method: POST
path: "/submissions/html"
tags: ["Submissions"]
---

# Create a submission from HTML

`POST /submissions/html`

This API endpoint allows you to create a one-off submission request document using the provided HTML content, with special field tags rendered as a fillable and signable form.<br><b>Related Guides</b><br><a href="/keyring-guides/create-pdf-document-fillable-form-with-html-api.html" class="link">Create PDF document fillable form with HTML</a>

## Request body

- object
  - `name` string — Name of the document submission.
  - `send_email` boolean — Set `false` to disable signature request emails sending.
  - `send_sms` boolean — Set `true` to send signature request via phone number and SMS.
  - `order` 'preserved' | 'random' — 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 — Specify URL to redirect to after the submission completion.
  - `bcc_completed` string — Specify BCC address to send signed documents to after the completion.
  - `reply_to` string — Specify Reply-To address to use in the notification emails.
  - `expire_at` string — Specify the expiration date and time after which the submission becomes unavailable for signature.
  - `template_ids` integer[] — 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` object[], required — The list of documents built from HTML. Can be used to create a submission with multiple documents.
    - `name` string — Document name. Random uuid will be assigned when not specified.
    - `html` string, required — HTML document content with field tags.
    - `html_header` string — HTML document content of the header to be displayed on every page.
    - `html_footer` string — HTML document content of the footer to be displayed on every page.
    - `size` 'Letter' | 'Legal' | 'Tabloid' | 'Ledger' | 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'A6' — Page size. Letter 8.5 x 11 will be assigned when not specified.
    - `position` integer — Document position in the submission. If not specified, the document will be added in the order it appears in the documents array.
  - `submitters` object[], required — The list of submitters for the submission.
    - `name` string — The name of the submitter.
    - `role` string — The role name or title of the submitter.
    - `email` string, email — The email address of the submitter.
    - `phone` string — The phone number of the submitter, formatted according to the E.164 standard.
    - `values` object — An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param.
    - `external_id` string — Your application-specific unique string key to identify this submitter within your app.
    - `completed` boolean — Pass `true` to mark submitter as completed and auto-signed via API.
    - `metadata` object — Metadata object with additional submitter information.
    - `send_email` boolean — Set `false` to disable signature request emails sending only for this submitter.
    - `send_sms` boolean — Set `true` to send signature request via phone number and SMS.
    - `reply_to` string — Specify Reply-To address to use in the notification emails for this submitter.
    - `completed_redirect_url` string — Submitter specific URL to redirect to after the submission completion.
    - `order` integer — 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.
    - `require_phone_2fa` boolean — Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.
    - `require_email_2fa` boolean — Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.
    - `invite_by` string — Set the role name of the previous party that should invite this party via email.
    - `fields` object[] — A list of configurations for document form fields.
      - `name` string, required — Document field name.
      - `default_value` union — Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.
        - string
        - number
        - boolean
        - union[]
          - union
            - string
            - number
            - boolean
      - `readonly` boolean — Set `true` to make it impossible for the submitter to edit predefined field value.
      - `required` boolean — Set `true` to make the field required.
      - `title` string — Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown.
      - `description` string — Field description displayed on the signing form. Supports Markdown.
      - `validation` object — Field validation rules.
        - `pattern` string — HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.
        - `message` string — A custom error message to display on validation failure.
        - `min` union — Minimum allowed number value or date depending on field type.
          - number
          - string
        - `max` union — Maximum allowed number value or date depending on field type.
          - number
          - string
        - `step` number — Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency.
      - `preferences` object — Field display preferences.
        - `font_size` integer — Font size of the field value in pixels.
        - `font_type` 'bold' | 'italic' | 'bold_italic' — Font type of the field value.
        - `font` 'Times' | 'Helvetica' | 'Courier' — Font family of the field value.
        - `color` 'black' | 'white' | 'blue' — Font color of the field value.
        - `background` 'black' | 'white' | 'blue' — Field box background color.
        - `align` 'left' | 'center' | 'right' — Horizontal alignment of the field text value.
        - `valign` 'top' | 'center' | 'bottom' — Vertical alignment of the field text value.
        - `format` string — The data format for different field types.<br>- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).<br>- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.<br>- Number field: accepts currency formats such as usd, eur, gbp.
        - `price` number — Price value of the payment field. Only for payment fields.
        - `currency` 'USD' | 'EUR' | 'GBP' | 'CAD' | 'AUD' — Currency value of the payment field. Only for payment fields.
        - `mask` union — Set `true` to make sensitive data masked on the document.
          - integer
          - boolean
        - `reasons` string[] — An array of signature reasons to choose from.
    - `roles` string[] — A list of roles for the submitter. Use this param to merge multiple roles into one submitter.
  - `message` object — Custom signature request email message.
    - `subject` string — Custom signature request email subject.
    - `body` string — Custom signature request email body. Can include the following variables: {{submission.name}}, {{submitter.link}}, {{account.name}}.
  - `merge_documents` boolean — Set `true` to merge the documents into a single PDF file.

## Response `200`

OK

- object
  - `id` integer, required — Submission unique ID number.
  - `name` string — Submission name.
  - `submitters` object[], required — The list of submitters.
    - `id` integer, required — Submitter unique ID number.
    - `uuid` string, required — Submitter UUID.
    - `email` string, nullable, required — The email address of the submitter.
    - `slug` string, required — Unique key to be used in the form signing link and embedded form.
    - `sent_at` string, nullable, required — The date and time when the signing request was sent to the submitter.
    - `opened_at` string, nullable, required — The date and time when the submitter opened the signing form.
    - `completed_at` string, nullable, required — The date and time when the submitter completed the signing form.
    - `declined_at` string, nullable, required — The date and time when the submitter declined the signing form.
    - `created_at` string, required — The date and time when the submitter was created.
    - `updated_at` string, required — The date and time when the submitter was last updated.
    - `name` string, nullable, required — The name of the submitter.
    - `phone` string, nullable, required — The phone number of the submitter.
    - `external_id` string, nullable — Your application-specific unique string key to identify this submitter within your app.
    - `status` 'completed' | 'declined' | 'opened' | 'sent' | 'awaiting', required — The status of signing request for the submitter.
    - `values` object[] — An array of pre-filled values for the submitter.
      - `field` string, required — Document template field name.
      - `value` union, required — Pre-filled value of the field.
        - string
        - number
        - boolean
        - union[]
          - union
            - string
            - number
            - boolean
    - `role` string, required — The role of the submitter in the signing process.
    - `metadata` object, required — Metadata object with additional submitter information.
    - `preferences` object, required — Submitter preferences.
    - `embed_src` string — The `src` URL value to embed the signing form or sign via a link.
  - `source` 'invite' | 'bulk' | 'api' | 'embed' | 'link', required — The source of the submission.
  - `submitters_order` 'random' | 'preserved', required — The order of submitters.
  - `status` 'completed' | 'declined' | 'expired' | 'pending', required — The status of the submission.
  - `schema` object[] — The one-off submission document files.
    - `attachment_uuid` string — The attachment UUID.
    - `name` string — The attachment name.
  - `fields` object[] — List of fields to be filled in the one-off submission.
    - `uuid` string, required — Unique identifier of the field.
    - `submitter_uuid` string, required — Unique identifier of the submitter that filled the field.
    - `name` string, required — Field name.
    - `type` 'heading' | 'text' | 'signature' | 'initials' | 'date' | 'number' | 'image' | 'checkbox' | 'multiple' | 'file' | 'radio' | 'select' | 'cells' | 'stamp' | 'payment' | 'phone' | 'verification' | 'kba' | 'strikethrough', required — Type of the field (e.g., text, signature, date, initials).
    - `required` boolean, required — Indicates if the field is required.
    - `preferences` object — Field display preferences.
      - `font_size` integer — Font size of the field value in pixels.
      - `font_type` string — Font type of the field value.
      - `font` string — Font family of the field value.
      - `color` string — Font color of the field value.
      - `background` string — Field box background color.
      - `align` string — Horizontal alignment of the field text value.
      - `valign` string — Vertical alignment of the field text value.
      - `format` string — The data format for different field types.
      - `price` number — Price value of the payment field. Only for payment fields.
      - `currency` string — Currency value of the payment field. Only for payment fields.
      - `mask` boolean — Indicates if the field is masked on the document.
      - `reasons` string[] — An array of signature reasons to choose from.
    - `areas` object[], required — List of areas where the field is located in the document.
      - `x` number, required — X coordinate of the area where the field is located in the document.
      - `y` number, required — Y coordinate of the area where the field is located in the document.
      - `w` number, required — Width of the area where the field is located in the document.
      - `h` number, required — Height of the area where the field is located in the document.
      - `attachment_uuid` string, required — Unique identifier of the attached document where the field is located.
      - `page` integer, required — Page number of the attached document where the field is located.
  - `expire_at` string, required — Specify the expiration date and time after which the submission becomes unavailable for signature.
  - `created_at` string, required — The date and time when the submission was created.

---

[API](https://skmtc.dev/keyring-network/apis/keyring-docsign-api.md) · [All operations](https://skmtc.dev/keyring-network/apis/keyring-docsign-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/keyring-network/keyring-docsign-api/revisions/5381dc74855a/schema)