Ironclad Public API

openapi: 3.1.0
info:
  title: Ironclad Public API
  description: Documentation for Ironclad's REST API.
  contact:
    name: Ironclad Support
    email: support@ironcladapp.com
  version: '1'
servers:
- url: https://na1.ironcladapp.com/public/api/v1
  description: Production server
- url: https://eu1.ironcladapp.com/public/api/v1
  description: EU Production server
- url: https://demo.ironcladapp.com/public/api/v1
  description: Demo server
paths:
  /workflows:
    post:
      summary: Create a Workflow Synchronously
      description: "Launch a new Workflow synchronously. \n\n**OAuth Scope required:** `public.workflows.createWorkflows`"
      operationId: launch-a-new-workflow
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/UseDefaultValuesOnLaunch'
      requestBody:
        $ref: '#/components/requestBodies/WorkflowLaunch'
      security:
      - sec0: []
        OAuth2:
        - public.workflows.createWorkflows
      responses:
        '200':
          $ref: '#/components/responses/WorkflowLaunchResponse200'
        '400':
          $ref: '#/components/responses/WorkflowLaunchResponse400'
      tags:
      - Workflows
    get:
      summary: List All Workflows
      description: "List all workflows in your Ironclad account. \n\n**OAuth Scope required:** `public.workflows.readWorkflows`"
      operationId: list-all-workflows
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/QueryPageNumber'
      - $ref: '#/components/parameters/QueryPageSize'
      - $ref: '#/components/parameters/HydrateEntitiesFlag'
      - name: status
        in: query
        description: Filter the workflows that are listed based on their status. If this parameter is omitted, `active` workflows
          will be returned. Active workflows include workflows in the Create, Review, Sign, and Archive stages. Also accepts
          multiple comma-separated statuses to get workflows in more than one status.
        schema:
          type: array
          items:
            type: string
            enum:
            - active
            - paused
            - completed
            - cancelled
      - name: template
        in: query
        description: Filter workflows to a specific Template ID.
        schema:
          type: string
      - name: lastUpdated
        in: query
        description: Retrieve workflows that have been updated since a UTC date.
        schema:
          type: string
      - $ref: '#/components/parameters/WorkflowFilter'
      security:
      - sec0: []
        OAuth2:
        - public.workflows.readWorkflows
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: integer
                    example: 0
                    default: 0
                  pageSize:
                    type: integer
                    example: 20
                    default: 0
                  count:
                    type: integer
                    example: 1234
                    default: 0
                  list:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkflowResponseModel'
      tags:
      - Workflows
  /workflows/async:
    post:
      summary: Create a Workflow Asynchronously
      description: "Launch a new Workflow asynchronously for non-blocking performance, which is helpful when/if you provide\
        \ files to the Workflow. \n\n**OAuth Scope required:** `public.workflows.createWorkflows`"
      operationId: create-a-new-workflow-async
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/UseDefaultValuesOnLaunch'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowLaunchModel'
      security:
      - sec0: []
        OAuth2:
        - public.workflows.createWorkflows
      responses:
        '200':
          $ref: '#/components/responses/AsyncWorkflowLaunchResponse200'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties: {}
      tags:
      - Workflows
  /workflows/async/{asyncJobId}:
    get:
      summary: Retrieve the Status of an Async Workflow Create Job
      description: "Check the status of a Workflow you created while using the [Create a Workflow Async](https://developer.ironcladapp.com/reference/create-a-workflow-sync-vs-async#create-a-new-workflow-async)\
        \ route. \n\n**OAuth Scope required:** `public.workflows.createWorkflows`"
      operationId: retrieve-asynchronous-workflow-status
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - name: asyncJobId
        in: path
        description: The identifier provided in the response of creating a Workflow asynchronously.
        schema:
          type: string
        required: true
      security:
      - sec0: []
        OAuth2:
        - public.workflows.createWorkflows
      responses:
        '200':
          $ref: '#/components/responses/AsyncWorkflowStatusResponse200'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: NOT_FOUND
                  message:
                    type: string
                    example: not found
                  param:
                    type: string
                    example: parameter identifier
      tags:
      - Workflows
  /workflows/{id}:
    get:
      summary: Retrieve a Workflow
      description: "View the data associated with a specific workflow. \n\n**OAuth Scope required:** `public.workflows.readWorkflows`"
      operationId: retrieve-a-workflow
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/HydrateEntitiesFlag'
      - $ref: '#/components/parameters/WorkflowOrIroncladId'
      security:
      - sec0: []
        OAuth2:
        - public.workflows.readWorkflows
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponseModel'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties: {}
      tags:
      - Workflows
  /workflows/{id}/approvals:
    get:
      summary: List All Workflow Approvals
      description: "Returns a list of approvals for the workflow. The `approvalGroups` property will display only triggered\
        \ approvals (i.e. conditional approvals that have not been triggered will not appear). \n\n**OAuth Scope required:**\
        \ `public.workflows.readApprovals`"
      operationId: list-all-workflow-approvals
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/WorkflowOrIroncladId'
      security:
      - sec0: []
        OAuth2:
        - public.workflows.readApprovals
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  workflowId:
                    type: string
                    example: 5f595f76c4fc9b3571413c3ac
                  title:
                    type: string
                    example: Consulting Agreement with Michael Scott Paper Company
                  approvalGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        reviewers:
                          type: array
                          items:
                            type: object
                            properties:
                              role:
                                type: string
                                example: finance
                              displayName:
                                type: string
                                example: Finance
                              reviewerType:
                                type: string
                                example: role
                              status:
                                type: string
                                enum:
                                - pending
                                - approved
                                description: The status of the reviewer. If the status is `approved`, the reviewer has approved.
                                  If the status is `pending`, the reviewer has not yet approved.
                                example: pending
                        status:
                          type: string
                          enum:
                          - pending
                          - approved
                          - active
                          description: The status of the approval group. If the status is `active`, the approval group is
                            currently reviewing and its reviewers may approve. If the status is `approved`, all reviewers
                            in the approval group have approved. If the status is `pending`, the approval group is waiting
                            for prior groups to approve and its reviewers cannot approve.
                          example: pending
                        order:
                          type: integer
                          description: The order in which the approval group is executed. Only relevant if there is more than
                            one approval group and sequential approvals are enabled.
                          example: 1
                  roles:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: legal
                        displayName:
                          type: string
                          example: Legal
                        assignees:
                          type: array
                          items:
                            type: object
                            properties:
                              userName:
                                type: string
                                example: Boba Fett
                              userId:
                                type: string
                                example: 63d415e0dd0d828c3a878548
                              email:
                                type: string
                                example: bobafett@exmaple.com
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties: {}
      tags:
      - Workflows
  /workflows/{id}/approval-requests:
    get:
      summary: Retrieve the Approval Requests on a Workflow
      description: "Returns a list of approval requests that have taken place on the workflow. \n\n**OAuth Scope required:**\
        \ `public.workflows.readApprovals`"
      operationId: approval-requests
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/WorkflowOrIroncladId'
      - $ref: '#/components/parameters/QueryPageNumber'
      - $ref: '#/components/parameters/QueryPageSize'
      - name: actorDetails
        in: query
        description: An optional boolean parameter that adds additional information about the actor to each item in the response.
          Defaults to false.
        schema:
          type: boolean
          example: false
          default: false
        required: false
      - name: requestType
        in: query
        description: An optional string parameter that specifies the type of approval requests and returns approval requests
          by `role` or `user`.
        schema:
          type: string
          enum:
          - role
          - user
          default: user
        required: false
      security:
      - sec0: []
        OAuth2:
        - public.workflows.readApprovals
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: integer
                    example: 0
                    default: 0
                  pageSize:
                    type: integer
                    example: 20
                    default: 20
                  count:
                    type: integer
                    example: 42
                  list:
                    type: array
                    description: Approval requests on a workflow
                    items:
                      type: object
                      properties:
                        startTime:
                          type: string
                          description: Timestamp when the approval request became available for review
                          example: '2024-12-20T20:23:41.335Z'
                        endTime:
                          type: string
                          description: Timestamp when the approval request was approved or interrupted by workflow actions
                          example: '2024-12-20T20:23:43.036Z'
                        status:
                          type: string
                          description: Current state of an approval request that indicates whether the request is approved,
                            in progress, or affected by workflow actions.
                          enum:
                          - Approved
                          - Pending
                          - Workflow Paused
                          - Workflow Canceled
                          - Approver Removed
                          - Approver Reassigned
                          example: Approved
                        actorId:
                          type: string
                          description: User ID to whom the approval request is assigned to
                          example: 6334b636b9fb1eb6e76ada97
                        actorType:
                          type: string
                          example: User
                          enum:
                          - User
                        actorDetails:
                          type: object
                          properties:
                            userName:
                              type: string
                              example: Cave Johnson
                            userEmail:
                              type: string
                              example: cave@aperturescience.com
                        role:
                          type: string
                          description: Role ID of the role assigned to the user for the approval request
                          example: approver58348a760b354ab3a986f56a74656c86
                        roleName:
                          type: string
                          description: Display name of the role assigned to the user for the approval request
                          example: CEO
                        duration:
                          type: integer
                          description: 'Duration of the completed approval request in milliseconds '
                          example: 1701
                        aggregateDuration:
                          type: integer
                          description: Total duration of the completed approval request, obtained by adding the duration of
                            the approved request with the durations of preceding requests (if any) where the approver was
                            able to review but interrupted by a workflow pause.
                          example: 1500
                        approvalType:
                          type: string
                          example: Workflow
                          enum:
                          - Workflow
        '403':
          description: '403'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: FORBIDDEN
                  message:
                    type: string
                    example: access forbidden
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: NOT_FOUND
                  message:
                    type: string
                    example: workflow does not exist
                  param:
                    type: string
                    example: workflowId
      tags:
      - Workflows
  /workflows/{id}/approvals/{roleId}:
    patch:
      summary: Update Approval Status on a Workflow
      description: "Updates the status of an approval to the specified value. Approval statuses can only be updated during\
        \ the Review step and when a given approval group is active (when it is that group's turn to approve). \n\n**OAuth\
        \ Scope required:** `public.workflows.updateApprovals`"
      operationId: update-workflow-approval
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/WorkflowOrIroncladId'
      - name: roleId
        in: path
        description: The unique identifier of the approver role whose status should be changed. This identifier can be retrieved
          using the `GET /workflows/{id}/approvals` endpoint.
        schema:
          type: string
        required: true
      security:
      - sec0: []
        OAuth2:
        - public.workflows.updateApprovals
      requestBody:
        content:
          application/json:
            schema:
              description: Note that `user` is required when approving with a legacy bearer token but will be ignored when
                approving via an OAuth token. If the token was generated with the Authorization Code grant, the associated
                token user will be used. If the token was generated with the Client Credentials grant, the required `x-as-user-id`
                or 'x-as-user-email` header will be used.
              type: object
              required:
              - status
              properties:
                user:
                  type: object
                  description: The Ironclad user approving the workflow. The user must be currently assigned as the approver.
                  properties:
                    email:
                      type: string
                      description: The Ironclad user's email address.
                      example: fett@intergalactic.com
                    type:
                      type: string
                      description: The mechanism of identifying the Ironclad user's account.
                      default: email
                status:
                  type: string
                  enum:
                  - approved
                  - pending
                  description: The new approval status.
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: boolean
                example: true
        '400':
          description: '400'
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    code:
                      type: string
                      enum:
                      - INVALID_PARAM
                      example: INVALID_PARAM
                    message:
                      type: string
                      enum:
                      - This role does not exist in this workflow
                      - invalid user for user attribute
                      - This approval either was not requested or this user was not assigned to this approval
                      example: This role does not exist in this workflow
                    param:
                      type: string
                      enum:
                      - approval
                      example: approval
                - type: object
                  properties:
                    code:
                      type: string
                      enum:
                      - INVALID_STATE
                      example: INVALID_STATE
                    message:
                      type: string
                      enum:
                      - This approval cannot be approved out of order
                      example: This approval cannot be approved out of order
                    param:
                      type: string
                      enum:
                      - approval
                      example: approval
      tags:
      - Workflows
  /workflows/{id}/turn-history:
    get:
      summary: Retrieve the Turn History on a Workflow
      description: "An array of objects for each turn on a workflow. \n\n**OAuth Scope required:** `public.workflows.readTurnHistory`"
      operationId: turn-history
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/WorkflowOrIroncladId'
      - $ref: '#/components/parameters/QueryPageNumber'
      - $ref: '#/components/parameters/QueryPageSize'
      security:
      - sec0: []
        OAuth2:
        - public.workflows.readTurnHistory
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: integer
                    example: 0
                    default: 0
                  pageSize:
                    type: integer
                    example: 20
                    default: 20
                  count:
                    type: integer
                    example: 42
                  list:
                    type: array
                    items:
                      type: object
                      properties:
                        turnParty:
                          type: string
                          example: internal
                        turnStartTime:
                          type: string
                          example: '2022-09-20T15:51:54.156Z'
                        turnLocation:
                          type: string
                          example: manual change
                        turnUserId:
                          type: string
                          example: 5f89b6a5eed2cc6e0b2735d4
                        turnEndTime:
                          type: string
                          example: '2022-09-28T19:21:05.034Z'
                        turnNumber:
                          type: integer
                          example: 1
                        turnUserEmail:
                          type: string
                          example: baldwin@ironcladhq.com
        '403':
          description: '403'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: FORBIDDEN
                  message:
                    type: string
                    example: access forbidden
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: NOT_FOUND
                  message:
                    type: string
                    example: workflow does not exist
                  param:
                    type: string
                    example: workflowId
      tags:
      - Workflows
  /workflows/{id}/sign-status:
    get:
      summary: Retrieve Sign Step Status
      description: "Returns information about a workflow in the sign step. \n\n**OAuth Scope required:** `public.workflows.readSignStatus`\
        \ \n\n**NOTE:** The workflow must be in the sign step to access this route."
      operationId: get-sign-status
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/WorkflowOrIroncladId'
      security:
      - sec0: []
        OAuth2:
        - public.workflows.readSignStatus
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignStatusModel'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_STATE
                  message:
                    type: string
                    example: This workflow is not at the Sign step, and is currently at the Review step
        '401':
          $ref: '#/components/responses/UnauthorizedError401'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: FORBIDDEN
                  message:
                    type: string
                    example: access forbidden
        '404':
          $ref: '#/components/responses/WorkflowNotFoundResponse404'
      tags:
      - Workflows
  /workflows/{id}/sign-status/send-signature-request:
    post:
      summary: Send Signature Request
      description: "Send a signature request.\n\n**OAuth Scope required:** `public.workflows.sendSignatureRequests`\n\n **Note**:\
        \ You can only send a packet out for signature if all signers have an associated signature or initials tag (tag requirements\
        \ are dependent on the signature provider)."
      operationId: send-signature-request
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/WorkflowOrIroncladId'
      security:
      - sec0: []
        OAuth2:
        - public.workflows.sendSignatureRequests
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignStatusModel'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotOnSignStep400'
        '401':
          $ref: '#/components/responses/UnauthorizedError401'
        '404':
          $ref: '#/components/responses/WorkflowNotFoundResponse404'
      tags:
      - Workflows
  /workflows/{id}/sign-status/scheduled-send:
    post:
      summary: Schedule Send Signature Request
      description: 'Schedule a signature request to be sent out for signature. The workflow must be on the Sign step and not
        yet out for signature.


        **OAuth Scope required:** `public.workflows.scheduleSendSignatureRequest`


        '
      operationId: schedule-send-signature-request
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/WorkflowOrIroncladId'
      security:
      - sec0: []
        OAuth2:
        - public.workflows.scheduleSendSignatureRequest
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - notifyAt
              properties:
                notifyAt:
                  type: string
                  format: date-time
                  description: The ISO8601 timestamp for when the signature request should be sent out for signature.
                  example: '2026-03-01T12:00:00Z'
                reminder:
                  type: object
                  description: Optional reminder email to the Signature Coordinator before the scheduled send.
                  properties:
                    daysBefore:
                      type: integer
                      minimum: 1
                      maximum: 7
                      description: Number of days before the scheduled send to send the reminder email (1-7).
                  required:
                  - daysBefore
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignStatusModel'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotOnSignStep400'
        '401':
          $ref: '#/components/responses/UnauthorizedError401'
        '404':
          $ref: '#/components/responses/WorkflowNotFoundResponse404'
      tags:
      - Workflows
    patch:
      summary: Update Scheduled Signature Request
      description: 'Update a scheduled signature request. The workflow must be on the Sign step and not yet out for signature.


        **OAuth Scope required:** `public.workflows.updateScheduledSignatureRequest`


        '
      operationId: update-scheduled-signature-request
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/WorkflowOrIroncladId'
      security:
      - sec0: []
        OAuth2:
        - public.workflows.updateScheduledSignatureRequest
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                notifyAt:
                  type: string
                  format: date-time
                  description: The ISO8601 timestamp for when the signature request should be sent out for signature.
                  example: '2026-03-01T12:00:00Z'
                reminder:
                  description: Set to an object to add/update reminder, null to remove, or omit to leave unchanged.
                  nullable: true
                  type: object
                  properties:
                    daysBefore:
                      type: integer
                      minimum: 1
                      maximum: 7
                      description: Number of days before the scheduled send to send the reminder email (1-7).
                  required:
                  - daysBefore
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignStatusModel'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotOnSignStep400'
        '401':
          $ref: '#/components/responses/UnauthorizedError401'
        '404':
          $ref: '#/components/responses/WorkflowNotFoundResponse404'
      tags:
      - Workflows
    delete:
      summary: Delete Scheduled Signature Request
      description: 'Delete a scheduled signature request. The workflow must 

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