---
title: "Create a multi-document signing packet"
method: POST
path: "/api/v1/signing-packets"
tags: ["Signing Packets"]
---

# Create a multi-document signing packet

`POST /api/v1/signing-packets`

## Request

- Base URL: `https://api.korala.ai`
- URL: `https://api.korala.ai/api/v1/signing-packets`
- Auth: one of:
  - API key in header `X-API-Key`
  - `bearer` (a scheme the document does not define)

## Request body

- CreateSigningPacketDto
  - `sandbox` boolean: Dashboard mode. API keys always use their authenticated mode.
  - `sourceCollectionId` string, uuid
  - `name` string, required
  - `externalId` string
  - `recipient` SigningPacketRecipientInputDto, required
    - `name` string, required
    - `email` string, required
    - `externalId` string
  - `accessMode` 'email_verification' | 'link'
  - `items` SigningPacketItemInputDto[], required
    - `documentId` string, uuid, required
    - `signerId` string, uuid, required
    - `order` number
    - `representedEntity` string
    - `signingCapacity` string
    - `fieldValues` SigningPacketFieldValueInputDto[]: Values your backend fixes for the item signer before the packet is sent. Each field must belong to the item signer and be unfilled; signature, initials, shared-fill, choose-one group, and already filled fields are refused. Sending the packet writes the values and locks the fields, so the recipient sees them in the hosted ceremony but cannot change them. Other signers and their existing signatures are untouched.
      - `fieldId` string, uuid, required: A field assigned to the item signer on the item document
      - `value` string, required: The value the recipient reviews but cannot change. Trimmed, must not be blank, and validated against the field like a signer-entered value (options, maxLength, inputMask, validationPattern). A checkbox can only be locked checked.
  - `redirectUrl` string
  - `expiresAt` string, date-time

## Response `201`

- SigningPacketDto
  - `sourceCollectionId` string, uuid, nullable
  - `id` string, uuid, required
  - `publicId` string, uuid, required
  - `name` string, required
  - `externalId` string, nullable
  - `sandbox` boolean, required
  - `expiresAt` string, date-time, nullable
  - `senderName` string, required
  - `senderOrganizationName` string, nullable
  - `brand` HostedSigningBrandDto
    - `name` string, required: Partner identity shown in hosted signing
    - `logoUrl` string, uri, nullable, required
    - `primaryColor` string, nullable, required: Accent color used for signing actions
  - `electronicDisclosure` ElectronicDisclosureDto, required
    - `provider` 'korala' | 'partner', required
    - `profileId` string, required
    - `version` string, required
    - `title` string, required
    - `contentHtml` string, required: Restricted, server-sanitized HTML
    - `contentSha256` string, required: SHA-256 of the immutable disclosure snapshot
    - `affirmationText` string, required
  - `status` 'draft' | 'sent' | 'viewed' | 'processing' | 'partially_completed' | 'recipient_completed' | 'voided' | 'expired', required
  - `accessMode` 'email_verification' | 'link', required
  - `recipient` SigningPacketRecipientDto, required
    - `id` string, uuid, required
    - `name` string, required
    - `email` string, required
    - `status` 'pending' | 'viewed' | 'completed', required
    - `consentedAt` string, nullable
  - `items` SigningPacketItemDto[], required
    - `id` string, uuid, required
    - `documentId` string, uuid, required
    - `documentSignerId` string, uuid, required
    - `status` 'pending' | 'signed' | 'invalidated', required
    - `order` number, required
    - `documentName` string, required
    - `documentStatus` 'draft' | 'pending' | 'completing' | 'completed' | 'failed' | 'voided' | 'expired', required
    - `signerStatus` 'pending' | 'viewed' | 'signed' | 'declined', required
    - `documentUrl` string
    - `signedDocumentUrl` string, nullable
    - `certificateUrl` string, nullable
    - `representedEntity` string, nullable
    - `signingCapacity` string, nullable
    - `fieldValues` SigningPacketFieldValueDto[]: Values the sender locked for the item signer; applied to the fields when the packet is sent.
      - `fieldId` string, uuid, required
      - `value` string, required
    - `fields` SigningPacketFieldDto[]
      - `valueKey` string, nullable: Repeated text value key, scoped to the owning signer.
      - `id` string, required
      - `documentId` string, required
      - `signerId` string, required
      - `fieldType` 'signature' | 'initials' | 'date' | 'text' | 'checkbox' | 'dropdown' | 'radio', required
      - `pageNumber` number, required
      - `xPosition` number, required
      - `yPosition` number, required
      - `width` number, required
      - `height` number, required
      - `label` string, nullable: Human-readable label shown to the signer for this field
      - `required` string, required
      - `value` string, nullable
      - `editable` boolean, required: When true, a prefilled value is a suggestion the signer can change before signing.
      - `sharedFill` boolean, required: One signer owns the field, but until they sign any signer able to act may fill or correct it — the employer preparing a part the employee confirms. Never true on signature or initials fields.
      - `signingDate` boolean, nullable: Date fields only. True fills the field with the date the signer signs: the signing page shows today and the signer does not type it. False makes it an ordinary date the signer enters. Refused on any other type. Null on a date made before the flag existed: a date on the signer’s own signature line is then the date of signing.
      - `signatureImageUrl` string, nullable
      - `filledAt` string, date-time, nullable
      - `filledBy` 'sender' | 'signer': Who wrote the current value: the sender (a non-editable template prefill or a signing-packet lock) or the signer (any fill, including bulk signing on their behalf). Null while unfilled.
      - `signingDateChangedAt` string, date-time, nullable: When the signer changed the date beside their signature from the automatic date of signing to one of their own. Null otherwise.
      - `acroFieldName` string, nullable: Embedded AcroForm field this field is linked to; values fill the PDF form field at completion instead of being overlay-stamped.
      - `acroOptionValue` string, nullable: For radio-group AcroForm fields: the option this field selects.
      - `options` string[], nullable: Allowed values for dropdown fields
      - `maxLength` number, nullable: Maximum characters accepted at fill time
      - `inputMask` string, nullable: Input mask where # represents one digit
      - `validationPattern` string, nullable: Regex the filled value must match
      - `validationMessage` string, nullable: Signer-facing error when validationPattern does not match
      - `dateFormat` string, nullable: Date fields only: format the auto-filled date is rendered in, e.g. 'MM-DD-YYYY'
      - `groupKey` string, nullable
      - `groupRequired` boolean, required: Whether at least one member of this group must be selected
      - `requiredWhenFieldId` string, uuid, nullable: Id of the field whose checked/filled state makes this field required (conditional requirement); null when unconditional
      - `requiredWhenValue` string, nullable: Exact controller value the condition triggers on; null means any checked/filled state
      - `fontSize` number, nullable: Point size the value is drawn at, imported from the PDF form field. Null means the size is fitted to the box.
      - `textColor` string, nullable: Color the value is drawn in, as #rrggbb
      - `textAlign` 'left' | 'center' | 'right': Horizontal alignment of the value inside the field box
      - `fontFamily` string, nullable: Base font the value is drawn in, imported from the PDF form field
      - `multiline` boolean, required: Whether the value may contain line breaks (a multiline form field)
      - `createdAt` string, date-time, required
      - `updatedAt` string, date-time, required
  - `signingUrl` string
  - `certificateUrl` string, nullable
  - `auditReportUrl` string, nullable: Deprecated alias for certificateUrl
  - `redirectUrl` string, nullable
  - `savedSignature` SigningPacketSavedSignatureDto
    - `id` string, uuid, required
    - `name` string, required
    - `signatureImageUrl` string, required
    - `kind` 'signature' | 'initials', required
  - `savedInitials` SigningPacketSavedSignatureDto
    - `id` string, uuid, required
    - `name` string, required
    - `signatureImageUrl` string, required
    - `kind` 'signature' | 'initials', required
  - `deliveryStatus` 'not_requested' | 'sent' | 'failed'

---

[API](https://skmtc.dev/korala/apis/korala-public-api.md) · [All operations](https://skmtc.dev/korala/apis/korala-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/korala/apis/korala-public-api/revisions/5c4d7810c507?raw)