SignWell Document API

openapi: 3.0.1
info:
  title: SignWell Developer API Application Document API
  description: API for creating, managing, and tracking electronic signature workflows.
  version: v1
  termsOfService: https://www.signwell.com/terms/
  contact:
    email: support@signwell.com
servers:
- url: https://www.signwell.com
tags:
- name: Document
  description: Create, send, and manage documents for electronic signing.
paths:
  /api/v1/documents:
    get:
      summary: List Documents
      description: Returns a paginated list of documents for the authenticated account.
      tags:
      - Document
      security:
      - api_key: []
      operationId: listDocuments
      x-internal: true
      parameters:
      - name: page
        in: query
        schema:
          $ref: '#/components/schemas/Page'
        required: false
      - name: limit
        in: query
        schema:
          $ref: '#/components/schemas/Limit'
        required: false
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                documents:
                - id: a83ff091-11fc-4091-8111-6dd2ee8e3393
                  archived: false
                  created_at: '2026-03-31T15:46:45Z'
                  decline_message: null
                  embedded_edit_url: https://www.signwell.com/edit/document/cb858cfc-3bd0-41a8-9b29-abb1da693aac/
                  error_message: null
                  embedded_preview_url: null
                  language: en
                  name: miscarriage-relationship/omnis.mp3
                  requester_email_address: 1_scary_terry@keeling-bahringer.example
                  status: Created
                  test_mode: false
                  updated_at: '2026-03-31T15:46:45Z'
                  allow_decline: true
                  allow_reassign: true
                  api_application_id: null
                  custom_requester_email: null
                  custom_requester_name: null
                  decline_redirect_url: null
                  embedded_signing: false
                  expires_in: 30
                  metadata: {}
                  redirect_url: null
                  reminders: true
                  apply_signing_order: false
                  message: <p>Hey there,</p><p>&nbsp;</p><p>Please review and complete this document. You can click on the document below to get started.</p>
                  subject: Please complete miscarriage-relationship/omnis.mp3
                  labels: []
                  fields: []
                  files: []
                  copied_contacts: []
                  recipients: []
                  checkbox_groups: []
                - id: f9bce8ff-2f98-4959-92e4-c895a1367341
                  archived: false
                  created_at: '2026-03-31T15:46:45Z'
                  decline_message: null
                  embedded_edit_url: https://www.signwell.com/edit/document/302e3717-2a9d-4126-a5f1-b7143b21a018/
                  error_message: null
                  embedded_preview_url: null
                  language: en
                  name: miscarriage-linger/et.mp4
                  requester_email_address: 1_scary_terry@keeling-bahringer.example
                  status: Created
                  test_mode: false
                  updated_at: '2026-03-31T15:46:45Z'
                  allow_decline: true
                  allow_reassign: true
                  api_application_id: null
                  custom_requester_email: null
                  custom_requester_name: null
                  decline_redirect_url: null
                  embedded_signing: false
                  expires_in: 30
                  metadata: {}
                  redirect_url: null
                  reminders: true
                  apply_signing_order: false
                  message: <p>Hey there,</p><p>&nbsp;</p><p>Please review and complete this document. You can click on the document below to get started.</p>
                  subject: Please complete miscarriage-linger/et.mp4
                  labels: []
                  fields: []
                  files: []
                  copied_contacts: []
                  recipients: []
                  checkbox_groups: []
                - id: 1b03215e-f3cc-446b-a9dc-293af294c988
                  archived: false
                  created_at: '2026-03-31T15:46:45Z'
                  decline_message: null
                  embedded_edit_url: https://www.signwell.com/edit/document/28e9b87a-88dd-4f08-a1a2-633649ccfa3c/
                  error_message: null
                  embedded_preview_url: null
                  language: en
                  name: dictate_publish/error.avi
                  requester_email_address: 1_scary_terry@keeling-bahringer.example
                  status: Created
                  test_mode: false
                  updated_at: '2026-03-31T15:46:45Z'
                  allow_decline: true
                  allow_reassign: true
                  api_application_id: null
                  custom_requester_email: null
                  custom_requester_name: null
                  decline_redirect_url: null
                  embedded_signing: false
                  expires_in: 30
                  metadata: {}
                  redirect_url: null
                  reminders: true
                  apply_signing_order: false
                  message: <p>Hey there,</p><p>&nbsp;</p><p>Please review and complete this document. You can click on the document below to get started.</p>
                  subject: Please complete dictate_publish/error.avi
                  labels: []
                  fields: []
                  files: []
                  copied_contacts: []
                  recipients: []
                  checkbox_groups: []
                current_page: 1
                next_page: null
                previous_page: null
                total_count: 3
                total_pages: 1
              schema:
                $ref: '#/components/schemas/DocumentListResponse'
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                message: Missing or invalid authorization key
                meta:
                  error: api_key_unauthorized_error
                  message: Not valid authorization token
                  messages:
                  - Not valid authorization token
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
    post:
      summary: Create Document
      description: Creates and optionally sends a new document for signing. If `draft` is set to true the document will not be sent.
      tags:
      - Document
      security:
      - api_key: []
      operationId: createDocument
      parameters: []
      responses:
        '201':
          description: created
          content:
            application/json:
              example:
                id: 6a8b63de-1885-4ab8-bf0a-77ebd3686c00
                archived: false
                created_at: '2026-03-31T15:46:47Z'
                decline_message: null
                embedded_edit_url: https://www.signwell.com/edit/document/3560287f-49f5-423e-a37a-37cd7403c1c8/
                error_message: null
                embedded_preview_url: null
                language: en
                name: Agreement
                requester_email_address: requester@domain.com
                status: Created
                test_mode: false
                updated_at: '2026-03-31T15:46:47Z'
                allow_decline: true
                allow_reassign: true
                api_application_id: null
                custom_requester_email: requester@domain.com
                custom_requester_name: Requester
                decline_redirect_url: https://www.domain.com/decline_path/
                embedded_signing: false
                expires_in: 365
                metadata:
                  key1: value1
                  key2: value2
                redirect_url: https://www.domain.com/redirect_path/
                reminders: true
                apply_signing_order: false
                message: Normal Body
                subject: Normal subject
                labels:
                - id: 7af3624f-fc72-4f69-bed6-de920ba4f72b
                  name: My First Label
                - id: 00f4b0c6-c24b-4320-9ebf-0a3b068cfc05
                  name: My Second Label
                - id: bd7c048f-dc98-4a32-b84f-46e8a117839e
                  name: My Third Label
                fields:
                - - api_id: DateField_1
                    height: '19.0'
                    page: 1
                    required: true
                    type: date
                    value: 06/05/2021
                    width: '86.0'
                    x: 230.0
                    y: 60.0
                    date_format: DD/MM/YYYY
                    formula: ''
                    lock_sign_date: true
                    recipient_id: recipient_id_1
                  - api_id: DateSigned_1
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_date_signed
                    value: null
                    width: '86.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_1
                  - api_id: Company_1
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_company
                    value: Great Company
                    width: '86.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_1
                  - api_id: Email_1
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_email
                    value: recipient1@domain.com
                    width: '86.0'
                    x: 260.0
                    y: 90.0
                    recipient_id: recipient_id_1
                  - api_id: Name_1
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_name
                    value: Recipient One
                    width: '86.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_1
                  - api_id: FirstName_1
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_name
                    value: Recipient
                    width: '86.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_1
                  - api_id: LastName_1
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_name
                    value: One
                    width: '86.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_1
                  - api_id: Phone_1
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_phone
                    value: '123456789'
                    width: '86.0'
                    x: 260.0
                    y: 100.0
                    recipient_id: recipient_id_1
                  - api_id: Title_1
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_title
                    value: Important Title
                    width: '86.0'
                    x: 260.0
                    y: 100.0
                    recipient_id: recipient_id_1
                - - api_id: DateField_2
                    height: '2.0'
                    page: 1
                    required: true
                    type: date
                    value: 05/06/2021
                    width: '1.0'
                    x: 260.0
                    y: 80.0
                    date_format: MM/DD/YYYY
                    formula: ''
                    lock_sign_date: false
                    recipient_id: recipient_id_2
                  - api_id: Signature_1
                    height: '32.0'
                    page: 2
                    required: true
                    type: signature
                    value: null
                    width: '112.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_2
                  - api_id: Signature_2
                    height: '2.0'
                    page: 1
                    required: true
                    type: signature
                    value: null
                    width: '1.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_2
                  - api_id: CheckBox_1
                    height: '13.0'
                    page: 1
                    required: true
                    type: checkbox
                    value: t
                    width: '13.0'
                    x: 260.0
                    y: 80.0
                    name: null
                    recipient_id: recipient_id_2
                  - api_id: CheckBox_2
                    height: '2.0'
                    page: 1
                    required: true
                    type: checkbox
                    value: t
                    width: '1.0'
                    x: 260.0
                    y: 80.0
                    name: Checkbox name
                    recipient_id: recipient_id_2
                  - api_id: Initials_1
                    height: '32.0'
                    page: 2
                    required: true
                    type: initials
                    value: null
                    width: '44.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_2
                  - api_id: Initials_2
                    height: '2.0'
                    page: 1
                    required: true
                    type: initials
                    value: null
                    width: '1.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_2
                  - api_id: TextField_1
                    height: '19.0'
                    page: 1
                    required: true
                    type: text
                    value: '123456'
                    width: '86.0'
                    x: 260.0
                    y: 80.0
                    fixed_width: true
                    label: label
                    validation: numbers
                    recipient_id: recipient_id_2
                  - api_id: TextField_2
                    height: '2.0'
                    page: 1
                    required: true
                    type: text
                    value: '123456'
                    width: '1.0'
                    x: 260.0
                    y: 80.0
                    fixed_width: true
                    label: label
                    validation: numbers
                    recipient_id: recipient_id_2
                  - api_id: TextField_3
                    height: '20.0'
                    page: 1
                    required: true
                    type: text
                    value: '123456'
                    width: '100.0'
                    x: 260.0
                    y: 80.0
                    fixed_width: true
                    label: label
                    validation: numbers
                    recipient_id: recipient_id_2
                  - api_id: TextField_4
                    height: '20.0'
                    page: 1
                    required: true
                    type: text
                    value: '123456'
                    width: '100.0'
                    x: 260.0
                    y: 80.0
                    fixed_width: true
                    label: label
                    validation: numbers
                    recipient_id: recipient_id_2
                  - api_id: Company_2
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_company
                    value: Great Company
                    width: '86.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_1
                  - api_id: Email_2
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_email
                    value: recipient1@domain.com
                    width: '86.0'
                    x: 260.0
                    y: 90.0
                    recipient_id: recipient_id_1
                  - api_id: Name_2
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_name
                    value: Recipient One
                    width: '86.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_1
                  - api_id: FirstName_2
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_name
                    value: Recipient
                    width: '86.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_1
                  - api_id: LastName_2
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_name
                    value: One
                    width: '86.0'
                    x: 260.0
                    y: 80.0
                    recipient_id: recipient_id_1
                  - api_id: Phone_2
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_phone
                    value: '123456789'
                    width: '86.0'
                    x: 260.0
                    y: 100.0
                    recipient_id: recipient_id_1
                  - api_id: Title_2
                    height: '19.0'
                    page: 1
                    required: true
                    type: autofill_title
                    value: Important Title
                    width: '86.0'
                    x: 260.0
                    y: 100.0
                    recipient_id: recipient_id_1
                files:
                - name: filename1.pdf
                  pages_number: 0
                - name: filename2.pdf
                  pages_number: 0
                copied_contacts:
                - name: CC one
                  email: cc1@domain.com
                recipients:
                - email: recipient1@domain.com
                  id: recipient_id_1
                  message: This is a message
                  name: Recipient One
                  passcode: '123'
                  send_email: false
                  send_email_delay: 0
                  status: created
                  subject: Hi, please sign this contract
                  signing_order: 1
                  signing_url: https://www.signwell.com/docs/d549fd60a0/
                  bounced: null
                  bounced_details: null
                  attachment_requests:
                  - name: normal name
                    required: true
                    url: https://www.signwell.com/document_attachments/boe984aG7RUlK6YP2jZrInX6ywR/?access=2dd579d0-5e1d-4fd5-abd4-ebe5a228284d
                - email: recipient2@domain.com
                  id: recipient_id_2
                  message: null
                  name: Recipient 2
                  passcode: null
                  send_email: false
                  send_email_delay: 0
                  status: created
                  subject: null
                  signing_order: 2
                  signing_url: https://www.signwell.com/docs/bf45f2dad5/
                  bounced: null
                  bounced_details: null
                  attachment_requests:
                  - name: Driver License
                    required: false
                    url: https://www.signwell.com/document_attachments/LgbPkXRrZDTdzzNRGLkXSplYMMJ/?access=2dd579d0-5e1d-4fd5-abd4-ebe5a228284d
                checkbox_groups:
                - id: 6f69b18a-5fd7-4d74-8829-e7cc707a34f3
                  group_name: Group 1
                  recipient_id: null
                  checkbox_ids:
                  - CheckBox_1
                  - CheckBox_2
                  validation: minimum
                  required: true
                  min_value: 1
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '400':
          description: bad request
          content:
            application/json:
              example:
                errors:
                  message: The request contains invalid key values.
                  invalid_keys:
                  - name
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '422':
          description: unprocessable entity
          content:
            application/json:
              example:
                errors:
                  custom_requester_email:
                  - is invalid
                  custom_requester_name:
                  - is too long (maximum is 100 characters)
                  decline_redirect_url:
                  - is not a valid URL
                  redirect_url:
                  - is not a valid URL
                  expires_in:
                  - must be less than or equal to 365
                  metadata:
                  - The key/value pairs must not exceed 50
                  - 'Check the following keys: [qgtxtpsnyxjwzvbzhnmrjziscxsmgcugpqanuygve], length needs to be less than 40 characters'
                  - 'Check the value of the following keys: [ke50], length needs to be less than 500 characters and must be a string'
                  api_application_id:
                  - The provided API application id is invalid
                  subject:
                  - is too long (maximum is 255 characters)
                  message:
                  - is too long (maximum is 4000 characters)
                  recipients:
                    duplicated_ids: 'These ids are duplicated: recipient_id_1.'
                    duplicated_emails: 'These emails are duplicated: recipient1domain.com.'
                    recipient_1:
                      name:
                      - is too long (maximum is 255 characters)
                      email:
                      - format is invalid.
                    recipient_2:
                      email:
                      - format is invalid.
                  copied_contacts:
                    copied_contact_1:
                      name:
                      - is too long (maximum is 255 characters)
                      email:
                      - format is invalid.
                    copied_contact_2:
                      email:
                      - format is invalid.
                      - is already a recipient
                  attachment_requests:
                    invalid_ids: 'These recipient ids are not present in the recipients array: [recipient_id_3]'
                  fields:
                    duplicated_api_ids: 'These api ids are duplicated: CheckBox_2.'
                    invalid_ids: 'These recipient ids are not present in the recipients array: [recipient_id_2, recipient_id_3]'
                    file_1:
                      field_1:
                        date_format:
                        - Not allowed for text.
                        lock_sign_date:
                        - Not allowed for text.
                    file_2:
                      field_1:
                        date_format:
                        - Not allowed for checkbox.
                        fixed_width:
                        - Not allowed for checkbox.
                        validation:
                        - Not allowed for checkbox.
                        label:
                        - Not allowed for checkbox.
                        lock_sign_date:
                        - Not allowed for checkbox.
                      field_2:
                        invalid_date_value: DateField value must be in Iso8601 format.
                        fixed_width:
                        - Not allowed for date.
                        validation:
                        - Not allowed for date.
                        label:
                        - Not allowed for date.
                        date_format:
                        - 'Allowed formats for date fields are: MM/DD/YYYY | DD/MM/YYYY | YYYY/MM/DD | Month DD, YYYY | MM/DD/YYYY hh:mm:ss a'
                      field_3:
                        date_format:
                        - Not allowed for initials.
                        fixed_width:
                        - Not allowed for initials.
                        validation:
                        - Not allowed for initials.
                        label:
                        - Not allowed for initials.
                        lock_sign_date:
                        - Not allowed for initials.
                      field_4:
                        date_format:
                        - Not allowed for signature.
                        fixed_width:
                        - Not allowed for signature.
                        validation:
                        - Not allowed for signature.
                        label:
                        - Not allowed for signature.
                        lock_sign_date:
                        - Not allowed for signature.
                  checkbox_groups:
                    min_value_negative: The min value must be greater than or equal to 0 in the checkbox group Group 1
                  files:
                    file_1:
                      file_data:
                      - At least one of file_url or file_base64 should be present
                    file_2:
                      file_data:
                      - Only one of file_url or file_base64 should be present, not both
                    file_3:
                      file_url:
                      - is not a valid URL
                    file_4:
                      file_base64:
                      - 'the file type is unsupported, we support the following formats: application/msword, application/pdf, application/octet-stream, application/x-ole-storage, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/x-iwork-keynote-sffkey, application/x-iwork-numbers-sffnumbers, application/x-iwork-pages-sffpages, image/jpeg, image/png, image/tiff, image/webp, text/html'
                    file_5:
                      name:
                      - The file extension is invalid.
                    file_6:
                      name:
                      - can't be blank
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '429':
          description: rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentRequest'
        required: true
  /api/v1/documents/{id}:
    get:
      summary: Get Document
      description: Returns a document and all associated document data. Supply the unique document ID from either a document creation request or Document page URL.
      tags:
      - Document
      security:
      - api_key: []
      operationId: getDocument
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/DocumentId'
        required: true
      responses:
        '200':
          description: successful
          content:
            application/json:
              example:
                id: 2707ac1d-5dd3-4d95-8ae9-f0ac55f51203
                archived: false
                created_at: '2026-03-31T15:46:45Z'
                decline_message: null
                embedded_edit_url: https://www.signwell.com/edit/document/bf0ff8a4-50ec-42d7-8167-72fb404a5276/
                error_message: null
                embedded_preview_url: null
                language: en
                name: diagram_arena/architecto.mp3
                requester_email_address: jerry.smith.2@yundt-weber.test
                status: Created
                test_mode: false
                updated_at: '2026-03-31T15:46:45Z'
                allow_decline: false
                allow_reassign: true
                api_application_id: null
                custom_requester_email: rosalia_fisher@lehner.test
                custom_requester_name: Bendu
                decline_redirect_url: http://bosco.example/shani
                embedded_signing: false
                expires_in: 10
                metadata:
                  ut: quam
                  itaque: cumque
                redirect_url: http://bogan.example/eldora.kiehn
                reminders: false
                apply_signing_order: false
                message: <p>Hey there,</p><p>&nbsp;</p><p>Please review and complete this document. You can click on the document below to get started.</p>
                subject: Please complete diagram_arena/architecto.mp3
                labels:
                - id: 915b493e-8ba3-44aa-9e8b-ceb4044ac294
                  name: Frances Goodwin
                - id: 9acee41c-ee12-452d-bf40-f6645ee4b6ce
                  name: Gov. Roy Kohler
                fields:
                - - api_id: CheckBox_2
                    height: '13.0'
                    page: 1
                    required: true
                    type: checkbox
                    value: null
                    width: '13.0'
                    x: 1.1
                    y: 1.1
                    name: null
                    recipient_id: null
                    signing_elements_group_id: 6cd1fb22-417c-48e9-8674-d95c9613ff73
                  - api_id: CheckBox_3
                    height: '13.0'
                    page: 1
                    required: true
                    type: checkbox
                    value: null
                    width: '13.0'
                    x: 1.1
                    y: 1.1
                    name: null
                    recipient_id: null
                  - api_id: Signature_1
                    height: '32.0'
                    page: 1
                    required: true
                    type: signature
                    value: null
                    width: '112.0'
                    x: 1.1
                    y: 1.1
                    recipient_id: e052eeae-0706-4dd9-8ec2-68a918290223
                files:
                - name: velit.numbers
                  pages_number: 1
                copied_contacts:
                - name: Jon Auer
                  email: david@cummings-dicki.example
                recipients:
                - email: kimbery_kreiger@hoeger-littel.example
                  id: e052eeae-0706-4dd9-8ec2-68a918290223
                  message: null
                  name: Rodolfo Daniel
                  passcode: null
                  send_email: null
                  send_email_delay: null
                  status: created
                  subject: null
                  signing_order: 1
                  signing_url: https://www.signwell.com/docs/05791040ca/
                  bounced: null
                  bounced_details: null
                  attachment_requests:
                  - name: introduction_premium/vitae.html
                    required: true
             

# --- truncated at 32 KB (136 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/signwell/refs/heads/main/openapi/signwell-document-api-openapi.yml