> ## 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.

# List eSignature drafts

> The company's unsent eSignature drafts (up to 200, most recently
updated first), without their pages; get one draft for its full state.
Drafts awaiting review are listed only with `reviewRequired=true`,
which lists the ones awaiting the acting user's review. Needs the
`esignature_create` role permission.




## OpenAPI

````yaml /openapi.yaml get /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:
    get:
      tags:
        - eSignature
      summary: List eSignature drafts
      description: |
        The company's unsent eSignature drafts (up to 200, most recently
        updated first), without their pages; get one draft for its full state.
        Drafts awaiting review are listed only with `reviewRequired=true`,
        which lists the ones awaiting the acting user's review. Needs the
        `esignature_create` role permission.
      operationId: listEsignatureDrafts
      parameters:
        - name: userId
          in: query
          schema:
            type: string
          description: >-
            The acting user. Required with an API key or partner token; a
            delegate token is its own user.
        - name: cardId
          in: query
          schema:
            type: string
          description: Only drafts made from this card.
        - name: reviewRequired
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: The drafts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EsignatureDraft'
        '403':
          description: Missing `esignature_create` permission or a guest user.
components:
  schemas:
    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
    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'
    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.
    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.