> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getaptly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an eSignature draft

> Saves a new, unsent draft owned by the acting user: the first step of
creating an eSignature document (create, edit, then send). The draft
is built from `templateIds` (v2 builder templates the user can use):
each template's pages are merged against the card's fields and filed
as one package document, in the order given, and the recipients are
bound to the templates' signer slots. Title, message, access and
folder default to the first template's. A complete draft opens in the
app on Review & Send. Needs the `esignature_create` role permission
and access to the card; an API key limited to some boards must give a
`cardId` on one of them.




## OpenAPI

````yaml /openapi.yaml post /api/esignature/drafts
openapi: 3.0.3
info:
  title: Aptly API
  version: '1.1'
  description: |
    The Aptly API lets external systems work with boards, contacts, inboxes,
    tasks, files, and other Aptly resources.

    Most endpoints accept an API key in the `x-token` header. Some endpoints
    also accept a delegate token or partner bearer token, as shown in each
    operation's security requirements, and explicitly public endpoints require
    no credential. API keys are scoped to a company and may be restricted to
    specific boards and read, insert, or update permissions; requests outside
    those restrictions receive a 403 `FORBIDDEN` response.
servers:
  - url: https://core-api.getaptly.com
    description: Production
security:
  - ApiKeyHeader: []
paths:
  /api/esignature/drafts:
    post:
      tags:
        - eSignature
      summary: Create an eSignature draft
      description: |
        Saves a new, unsent draft owned by the acting user: the first step of
        creating an eSignature document (create, edit, then send). The draft
        is built from `templateIds` (v2 builder templates the user can use):
        each template's pages are merged against the card's fields and filed
        as one package document, in the order given, and the recipients are
        bound to the templates' signer slots. Title, message, access and
        folder default to the first template's. A complete draft opens in the
        app on Review & Send. Needs the `esignature_create` role permission
        and access to the card; an API key limited to some boards must give a
        `cardId` on one of them.
      operationId: createEsignatureDraft
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EsignatureDraftInput'
      responses:
        '201':
          description: The new draft.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EsignatureDraft'
        '400':
          description: Invalid body.
        '403':
          description: >-
            Missing `esignature_create` permission, a guest user, or no card on
            a board the API key may use.
        '404':
          description: '`cardId` not found.'
components:
  schemas:
    EsignatureDraftInput:
      type: object
      description: >-
        Body of draft create and edit. Pages, package documents and page
        settings are built from `templateIds`, not sent. Unlisted fields are
        dropped.
      required:
        - cardId
        - templateIds
        - title
        - recipients
        - from
        - expirationDate
      properties:
        userId:
          type: string
          description: The acting user. Required with an API key or partner token.
        cardId:
          type: string
          description: The card the templates are merged against.
        templateIds:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: string
          description: >-
            The v2 builder templates the document is built from, one package
            document each, in this order.
        recipients:
          $ref: '#/components/schemas/EsignatureRecipients'
        from:
          type: string
          description: >-
            Sender email address: one of the acting user's (or their teams')
            email inboxes, from `GET /api/users/{userId}/inboxes`. Recipients'
            replies go to it. Anything else is a 400.
        expirationDate:
          type: string
          format: date-time
          description: When the signing links expire.
        title:
          type: string
          minLength: 1
          description: Document title.
        message:
          type: string
          description: 'Default: the first template''s message, merged.'
        orderEnabled:
          type: boolean
          description: Whether signers sign in order. Default false.
        accessType:
          type: string
          description: >-
            `private` limits the document to `userIds`. Default: the first
            template's, else `public`.
        userIds:
          type: array
          items:
            type: string
          description: 'Default: the first template''s, else the acting user.'
        assignee:
          type: string
        folderId:
          type: string
          description: 'Default: the first template''s.'
        revisionOf:
          type: string
          description: 'Edit & Resend: the sent document this one replaces.'
        leaseDetails: {}
    EsignatureDraft:
      type: object
      additionalProperties: true
      properties:
        _id:
          type: string
        title:
          type: string
        userId:
          type: string
          description: The draft's creator.
        objectId:
          type: string
          description: The card the draft is made from.
        aptletOriginUuid:
          type: string
          description: That card's board.
        status:
          type: string
          description: '`draft` or `review`.'
        reviewerId:
          type: string
        reviewOutcome:
          type: string
          enum:
            - approved
            - rejected
        data:
          type: object
          properties:
            values:
              $ref: '#/components/schemas/EsignatureDocumentValues'
            step:
              type: integer
              description: >-
                The wizard step the app reopens the draft on. API saves set 5
                (Review & Send) for a draft complete enough to send, else 2
                (Recipients).
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    EsignatureRecipients:
      type: array
      minItems: 1
      items:
        type: object
        additionalProperties: true
        required:
          - email
          - name
          - role
        properties:
          slot:
            type: string
            description: >-
              The template signer slot the recipient fills (`signer-0`,
              `countersigner-0`, ...); by signing order when no recipient sets
              one.
          email:
            type: string
            format: email
            description: Where the signing invitation goes.
          name:
            type: string
          role:
            type: string
            description: '`signer`, `counterSigner`, `viewer`, `cc`.'
          order:
            oneOf:
              - type: number
              - type: string
            description: Signing group when `orderEnabled`; blank means 1.
          uuid:
            type: string
            description: >-
              The recipient's uuid, which recipient fields on the pages point
              at.
          _id:
            type: string
            description: The contact behind the recipient, when known.
    EsignatureDocumentValues:
      type: object
      additionalProperties: true
      description: |
        A draft's stored values (`data.values`): what draft create/edit built
        from the templates, plus any changes made in the app. Sending checks
        them against this schema: `cardId`, `title`, `builder: pdf`, v2
        `pages`, `documents`, `recipients`, `from`, `expirationDate`,
        `orderEnabled` and `accessType` must be set.
      properties:
        cardId:
          type: string
          description: The card the document is created from and merged against.
        title:
          type: string
          description: Document title (also the draft's title).
        builder:
          type: string
          enum:
            - pdf
          description: Only `pdf` (v2 builder) documents can be sent here.
        pages:
          type: array
          minItems: 1
          description: >-
            Builder v2 pages; every page carries `renderVersion: 2`. Fields not
            listed are kept and sanitized on save.
          items:
            $ref: '#/components/schemas/EsignaturePage'
        recipients:
          $ref: '#/components/schemas/EsignatureRecipients'
        from:
          type: string
          description: Sender email address shown to recipients.
        expirationDate:
          type: string
          format: date-time
          description: When the signing links expire.
        orderEnabled:
          type: boolean
          description: Whether signers sign in order (by `order`).
        accessType:
          type: string
          description: >-
            `private` limits the document to `userIds`; anything else makes it
            public to the company.
        message:
          type: string
        templateIds:
          type: array
          description: The templates the document was built from, in order.
          items:
            type: string
        documents:
          type: array
          minItems: 1
          description: >-
            Package documents the pages belong to (multi-template documents).
            Unlisted fields are dropped.
          items:
            $ref: '#/components/schemas/EsignaturePackageDocument'
        userIds:
          type: array
          description: >-
            Users and teams a private document is shared with. A private
            document with an empty or omitted list is shared with the sender.
          items:
            type: string
        assignee:
          type: string
        folderId:
          type: string
        revisionOf:
          type: string
          description: Edit & Resend, a sent document the new one replaces.
        leaseDetails: {}
        builderVersion:
          type: number
        documentSettings:
          $ref: '#/components/schemas/EsignatureDocumentSettings'
    EsignaturePage:
      type: object
      description: >-
        A builder v2 page. Geometry is in PDF points (72 per inch), origin
        top-left. Page uuids, and block uuids across all pages, are unique.
      additionalProperties: true
      required:
        - uuid
        - renderVersion
        - source
        - widthPt
        - heightPt
        - blocks
      properties:
        uuid:
          type: string
        renderVersion:
          type: integer
          enum:
            - 2
        source:
          type: string
          enum:
            - pdf
            - blank
          description: '`pdf` pages draw over `url`.'
        widthPt:
          type: number
          minimum: 0
          exclusiveMinimum: true
          description: Page width; a pdf page's native size (Letter is 612).
        heightPt:
          type: number
          minimum: 0
          exclusiveMinimum: true
          description: Page height (Letter is 792).
        url:
          type: string
          description: Background image of a pdf page; required when `source` is `pdf`.
        documentUuid:
          type: string
          description: >-
            The package document (`documents[].uuid`) the page belongs to;
            required unless the page is `loose`.
        loose:
          type: boolean
          description: >-
            A page in no document (sits between documents); has no
            `documentUuid`.
        blocks:
          type: array
          maxItems: 2000
          items:
            $ref: '#/components/schemas/EsignaturePageBlock'
    EsignaturePackageDocument:
      description: >-
        One document of a package; its pages point at it through `documentUuid`,
        and it needs at least one page. Unlisted fields are dropped.
      oneOf:
        - type: object
          title: Template document
          required:
            - uuid
            - name
            - source
            - templateId
          properties:
            uuid:
              type: string
              description: Unique within the package.
            source:
              type: string
              enum:
                - template
            templateId:
              type: string
              description: The template the document came from.
            name:
              type: string
              minLength: 1
            picked:
              type: boolean
              description: Chosen on the wizard's Template step.
        - type: object
          title: Uploaded document
          required:
            - uuid
            - name
            - source
            - fileId
            - fileName
          properties:
            uuid:
              type: string
              description: Unique within the package.
            source:
              type: string
              enum:
                - upload
            fileId:
              type: string
              description: The uploaded PDF.
            fileName:
              type: string
              minLength: 1
              description: The uploaded file's name.
            name:
              type: string
              minLength: 1
            picked:
              type: boolean
              description: Chosen on the wizard's Template step.
      discriminator:
        propertyName: source
    EsignatureDocumentSettings:
      type: object
      description: >-
        Builder v2 page settings; when absent, those of the template that
        supplies the settings. Every field is optional (its default is filled in
        on save); unlisted keys are dropped.
      properties:
        pageSize:
          type: string
          enum:
            - letter
            - legal
            - a4
          description: Default `letter`.
        orientation:
          type: string
          enum:
            - portrait
            - landscape
          description: Default `portrait`.
        margins:
          type: object
          description: In points; default 36 (0.5in) each.
          properties:
            top:
              type: number
              minimum: 0
              maximum: 720
            right:
              type: number
              minimum: 0
              maximum: 720
            bottom:
              type: number
              minimum: 0
              maximum: 720
            left:
              type: number
              minimum: 0
              maximum: 720
        pageNumbers:
          type: object
          properties:
            enabled:
              type: boolean
            position:
              type: string
              enum:
                - bottom-center
                - bottom-right
                - top-right
            format:
              type: string
              enum:
                - 'n'
                - page-n-of-N
            startAt:
              type: integer
              minimum: 0
              maximum: 100000
            skipFirst:
              type: boolean
            fontFamily:
              type: string
            fontSize:
              type: number
              minimum: 0
              exclusiveMinimum: true
              description: Snapped to the type scale.
    EsignaturePageBlock:
      type: object
      description: >-
        A builder v2 block. Fields not listed (value, content, options, ...) are
        kept and sanitized per type.
      additionalProperties: true
      required:
        - uuid
        - type
        - x
        - 'y'
      properties:
        uuid:
          type: string
        type:
          type: string
          enum:
            - input
            - text
            - checkbox
            - radio
            - dropdown
            - date
            - signingDate
            - phone
            - signature
            - initials
            - mergeField
            - richtext
            - image
            - shape
            - video
            - line
            - recipientField
            - documentField
            - link
            - note
            - staticCheckbox
        x:
          type: number
          minimum: 0
        'y':
          type: number
          minimum: 0
        w:
          type: number
          minimum: 0
          description: Width; the type's default when absent.
        h:
          type: number
          minimum: 0
          description: Height; the type's default when absent.
        z:
          type: number
        ownerUuid:
          type: string
          nullable: true
          description: >-
            Fillable blocks: the `uuid` of one of `recipients`, who fills it; a
            template slot (`signer-0`, ...) nobody claimed; null while
            unassigned.
        required:
          type: boolean
        style:
          type: object
          additionalProperties: true
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-token

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.