Ironclad Records API

openapi: 3.1.0
info:
  title: Ironclad OAuth 2.0 Authorization Records API
  description: Documentation for Ironclad's OAuth 2.0 Implementation. More details on the [OAuth 2.0 specification](https://datatracker.ietf.org/doc/html/rfc6749).
  version: '1'
  contact:
    name: Ironclad Support
    email: support@ironcladapp.com
servers:
- url: https://na1.ironcladapp.com/oauth
  description: Production server
- url: https://eu1.ironcladapp.com/oauth
  description: EU Production server
- url: https://demo.ironcladapp.com/oauth
  description: Demo server
tags:
- name: Records
  description: Documentation on Ironclad Records.
paths:
  /records:
    get:
      summary: List All Records
      description: "View all records in the company, with filtering available via query parameters. \n\n**OAuth Scope required:** `public.records.readRecords`"
      operationId: list-all-records
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/QueryPageNumber'
      - $ref: '#/components/parameters/QueryPageSize'
      - $ref: '#/components/parameters/HydrateEntitiesFlag'
      - $ref: '#/components/parameters/RecordType'
      - $ref: '#/components/parameters/RecordLastUpdated'
      - $ref: '#/components/parameters/RecordFilter'
      - name: sortField
        in: query
        description: The field to sort Records. Only one field is supported in the sort operation.
        schema:
          type: string
          enum:
          - agreementDate
          - name
          - lastUpdated
          default: agreementDate
      - name: sortDirection
        in: query
        description: The direction the records are sorted by in correlation with the `sortField`.
        schema:
          type: string
          enum:
          - ASC
          - DESC
          default: DESC
      - $ref: '#/components/parameters/addressAsObject'
      security:
      - sec0: []
        OAuth2:
        - public.records.readRecords
      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/RecordModel'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties: {}
      tags:
      - Records
    post:
      summary: Create a Record
      description: "Create a contract record by specifying its intended metadata properties. See [more documentation](https://developer.ironcladapp.com/docs/create-a-record-1) on creating a record. \n\n**OAuth Scope required:** `public.records.createRecords`"
      operationId: create-a-record
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/addressAsObject'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - name
              - properties
              properties:
                type:
                  type: string
                  description: The type of record to be created. You can view available record types by retrieving records metadata.
                name:
                  type: string
                  description: The name of the record.
                properties:
                  type: object
                  description: Object containing key/value pairs of metadata attached to the record. The key you specify must have a value with a supported type as outlined in the Supported Property Types section.
                  properties:
                    agreementDate:
                      type: object
                      description: The date of the agreement.
                      properties:
                        type:
                          type: string
                          default: date
                        value:
                          type: string
                          description: UTC date (e.g. `2018-05-08T00:00:00-07:00`)
                    counterpartyName:
                      type: object
                      description: The name of the counterparty.
                      properties:
                        type:
                          type: string
                          default: string
                        value:
                          type: string
                          description: The name of the counterparty.
                    contractValue:
                      type: object
                      description: The monetary value of the contract.
                      properties:
                        type:
                          type: string
                          default: monetary_amount
                        value:
                          type: object
                          description: The monetary amount value
                          required:
                          - amount
                          - currency
                          properties:
                            currency:
                              type: string
                              description: The currency in ISO 4217 format
                              example: USD
                            amount:
                              type: number
                              description: The monetary amount
                              example: 100000
                links:
                  type: array
                  items:
                    $ref: '#/components/schemas/RecordPropertyLinkModel'
                parent:
                  $ref: '#/components/schemas/RecordParentModel'
                propertiesToAmend:
                  $ref: '#/components/schemas/PropertiesToAmend'
                children:
                  type: array
                  description: List of objects containing the Record IDs or Ironclad IDs of the records to be set as child records of the current record.
                  items:
                    $ref: '#/components/schemas/RecordPropertyLinkModel'
      security:
      - sec0: []
        OAuth2:
        - public.records.createRecords
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordModel'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  param:
                    type: string
              examples:
                invalidRecordType:
                  summary: Unknown record type.
                  value:
                    code: INVALID_PARAM
                    message: unknown record type my_nonexistent_record_type
                    param: type
                invalidRecordProperty:
                  summary: Unknown record property.
                  value:
                    code: INVALID_PARAM
                    message: unknown property my_nonexistent_record_property
                    param: properties.my_non_existent_record_property
        '403':
          description: '403'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
      tags:
      - Records
  /records/attachments/download-urls:
    post:
      summary: Create Attachment Download URLs
      description: 'Request signed download URLs for record attachments in bulk (currently only latest signed copy is supported). Returns a job ID that can be polled for results.


        **OAuth Scope required:** `public.records.readAttachments`'
      operationId: create-attachment-download-urls
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - identifiers
              - type
              properties:
                identifiers:
                  type: array
                  items:
                    type: string
                  maxItems: 100
                  description: An array of record IDs or Ironclad IDs to generate download URLs for.
                type:
                  type: string
                  enum:
                  - latestSignedCopy
                  description: The type of attachment to generate download URLs for.
      security:
      - sec0: []
        OAuth2:
        - public.records.readAttachments
      responses:
        '202':
          description: Job accepted for processing.
          content:
            application/json:
              schema:
                type: object
                required:
                - jobId
                - status
                properties:
                  jobId:
                    type: string
                    description: An opaque job identifier to poll for results.
                  status:
                    type: string
                    enum:
                    - processing
                    description: The current status of the job.
        '400':
          $ref: '#/components/responses/BadRequestError400'
        '401':
          $ref: '#/components/responses/UnauthorizedError401'
        '403':
          $ref: '#/components/responses/ForbiddenError403'
      tags:
      - Records
  /records/attachments/download-urls/{jobId}:
    get:
      summary: Get Attachment Download URLs Status
      description: 'Poll the status of a previously submitted attachment download URLs job.


        **OAuth Scope required:** `public.records.readAttachments`'
      operationId: get-attachment-download-urls-status
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - name: jobId
        in: path
        required: true
        schema:
          type: string
        description: The job ID returned from the create attachment download URLs endpoint.
      security:
      - sec0: []
        OAuth2:
        - public.records.readAttachments
      responses:
        '200':
          description: The current status of the job.
          content:
            application/json:
              schema:
                type: object
                required:
                - jobId
                - status
                properties:
                  jobId:
                    type: string
                    description: The opaque job identifier.
                  status:
                    type: string
                    enum:
                    - processing
                    - complete
                    - failed
                    description: The current status of the job.
                  succeeded:
                    type: array
                    description: Array of objects with successfully generated download URLs. Present when status is complete.
                    items:
                      type: object
                      required:
                      - identifier
                      - ironcladId
                      - recordId
                      - downloadUrl
                      - filename
                      - fileKey
                      - fileHash
                      - expiration
                      properties:
                        identifier:
                          type: string
                          description: The identifier of the record that was passed in the request (record ID or Ironclad ID).
                          example: 17fe582d-e1e0-4000-bf65-3d2ec2c500a4
                        ironcladId:
                          type: string
                          description: The Ironclad ID of the record.
                          example: IC-123
                        recordId:
                          type: string
                          description: The globally unique UUID-based record ID of the record.
                          example: 17fe582d-e1e0-4000-bf65-3d2ec2c500a4
                        downloadUrl:
                          type: string
                          description: The signed download URL for the attachment.
                          example: https://storage.googleapis.com/ic_record_attachments/645aae3352150fe4e59ef90/6f5c8167-81a6-459c-a53c-eec9fa7e91c9/8674ec0992b199f7902d2459fc0f60b34616db93d28568f7003f6f1d1?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=sa-ic-dev%40na1-flex-c34f.iam.gserviceaccount.com%2F20260306%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20260306T230715Z&X-Goog-Expires=1200&X-Goog-SignedHeaders=host&response-content-disposition=attachment%3B%20filename%3D%22nda-with-table.pdf%22&X-Goog-Signature=40c961dd454de9bb1e80e4994643eee746ed0eb23da3482bd54d6570a267203063ed7e9a8c6e3797386144ce76c9d3272d37040e69940a3877afb4f082e179335a6d4995a4afb70aa20c1ec65af9e27b819e16d34e2f6d9b8e7233c9eb8ef7736c5d4e9507ea58ec48407ad7f2e0c46bb8053b989af67c187cea7258f48e26757b11045891ad7a5f114a65f7dec85405f981101ed77a4a3356e92edd113db391b6bc111357f02e5d05e39437b0d3b057cf9666f8318b04bcc31d30706ab7117f282eb64ab27669b522052d3ac24ede1cca1a1ad5e7c604e38f74eb20b3022007fa9186ed1b773177c88ccb54524addeb08a7624db2720041082997
                        filename:
                          type: string
                          description: The filename of the attachment.
                          example: contract.pdf
                        fileKey:
                          type: string
                          description: The key of the attachment.
                          example: signedCopy[1]
                        fileId:
                          type: string
                          description: The ID of the attachment.
                          example: d2079940-3049-4883-8931-2210a3864504
                        fileHash:
                          type: string
                          description: The hash of the attachment.
                          example: 8674ec0992b199f79c5802d2459fc0f60b3461601fcdb93d28568f7003f6f1d1
                        expiration:
                          type: string
                          format: date-time
                          description: The expiration date of the signed download URL in ISO 8601 format.
                          example: '2026-03-07T00:00:00.000Z'
                  failed:
                    type: array
                    description: Array of identifiers that failed to generate a signed download URL. Present when status is complete.
                    items:
                      type: object
                      required:
                      - identifier
                      - errorCode
                      - errorMessage
                      properties:
                        identifier:
                          type: string
                          description: The identifier of the record that was passed in the request (record ID or Ironclad ID).
                          example: 17fe582d-e1e0-4000-bf65-3d2ec2c500a4
                        ironcladId:
                          type: string
                          description: The Ironclad ID of the record, if resolved.
                          example: IC-123
                        recordId:
                          type: string
                          description: The globally unique UUID-based record ID of the record, if resolved.
                          example: 17fe582d-e1e0-4000-bf65-3d2ec2c500a4
                        errorCode:
                          type: string
                          enum:
                          - RECORD_NOT_FOUND
                          - ACCESS_DENIED
                          - NO_ATTACHMENT_FOUND
                          - INTERNAL_ERROR
                          description: The error code that occurred when generating the signed download URL.
                        errorMessage:
                          type: string
                          description: The error message that occurred when generating the signed download URL.
                          example: Access denied
        '401':
          $ref: '#/components/responses/UnauthorizedError401'
        '403':
          $ref: '#/components/responses/ForbiddenError403'
        '404':
          $ref: '#/components/responses/NotFoundError404'
      tags:
      - Records
  /records/smart-import:
    get:
      summary: Retrieve Predictions
      description: "Retrieve status of predictions of specific smart import record or all records in an import, one of Record Id or Import Id is required. \n\n**OAuth Scope required:** `public.records.readSmartImportRecords`"
      operationId: retrieve-import-predictions
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - name: recordId
        in: query
        description: The ID of the Record for prediction status.
        schema:
          type: string
        required: false
      - name: importId
        in: query
        description: The ID of the Import for prediction statuses.
        schema:
          type: string
        required: false
      security:
      - sec0: []
        OAuth2:
        - public.records.readSmartImportRecords
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SmartImportRetrievePredictionsResponseElement'
                  description: If `importId` was not provided, the response will be a single object.
                - title: Array of Prediction Statuses
                  description: If `importId` was provided, the response will be an array of objects.
                  type: array
                  items:
                    $ref: '#/components/schemas/SmartImportRetrievePredictionsResponseElement'
              examples:
                Single Result:
                  value:
                    recordId: df1c2805-f5a3-4a14-9386-c28d950dff49
                    status: ready
                Array Result:
                  value:
                  - recordId: df1c2805-f5a3-4a14-9386-c28d950dff49
                    status: ready
                  - recordId: 9b760581-df10-447a-8782-55b4bd7f2404
                    status: ready
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              examples:
                invalidRecordType:
                  summary: Missing Record Id or Import Id from query.
                  value:
                    code: INVALID_PARAM
                    message: missing required form-data part 'recordId' or 'importId
        '403':
          description: '403'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              examples:
                outOfSmartImportCredits:
                  summary: Smart Imports not enabled for company.
                  value:
                    code: FORBIDDEN
                    message: 'Reading smart import records not allowed for company with id invalid-company-id '
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              examples:
                invalidImportId:
                  summary: Record Id is invalid or does not exist
                  value:
                    code: NOT_FOUND
                    message: 'couldn''t find predictions for the record: invalid-record-id'
      tags:
      - Records
    post:
      summary: Create a Smart Import Record
      description: "Upload a file to create a record with smart import and predictions.  Provide none of recordType, newRecordTypeId, or newRecordTypeDisplayName to default to Imported type. \n\n**OAuth Scope required:** `public.records.createSmartImportRecords`"
      operationId: create-a-smart-import-record
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - attachment
              properties:
                attachment:
                  type: string
                  format: binary
                  description: Must be a binary. Base64 is not accepted at this time.
                recordType:
                  type: string
                  default: imported
                  description: Upload a smart import record as an existing record type.  Cannot provide alongside newRecordTypeId and newRecordTypeDisplayName. Defaults to Imported.
                newRecordTypeId:
                  type: string
                  description: The record type ID for a not-yet-existing record type.  Must be provided along with a newRecordTypeDisplayName
                newRecordTypeDisplayName:
                  type: string
                  description: The display name of the new record type to create.
      security:
      - sec0: []
        OAuth2:
        - public.records.createSmartImportRecords
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  recordId:
                    type: string
                    description: Record ID of the new created record
                    example: 17fe582d-e1e0-4000-bf65-3d2ec2c500a4
                  importId:
                    type: string
                    example: 55ez635d-f2g9-5419-gs34-8h1jx4s733q9
                  remainingCredits:
                    type: number
                    example: 50
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  param:
                    type: string
              examples:
                invalidRecordType:
                  summary: Invalid record type.
                  value:
                    code: INVALID_PARAM
                    message: unknown record type invalid_record_type
                    param: type
                invalidAttachment:
                  summary: Document size is too large.
                  value:
                    code: INVALID_PARAM
                    message: parameter 'attachment' too large, please limit upload files less than 100MB
                    param: attachment
                invalidFileType:
                  summary: Document size is too large.
                  value:
                    code: INVALID_PARAM
                    message: 'filename invalidFile.xyz does not have an accepted extension. Only the following extensions are allowed: .pdf, .docx, .doc, .xls, .xlsx, .eml, .tif, .jpg, .png, .jpeg, .txt, .ppt, .pptx.'
                    param: metadata.filename
        '403':
          description: '403'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              examples:
                outOfSmartImportCredits:
                  summary: No more AI Contract Credits are available
                  value:
                    code: FORBIDDEN
                    message: No more AI Contract Credits available
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              examples:
                invalidImportId:
                  summary: Import Id is invalid or does not exist
                  value:
                    code: NOT_FOUND
                    message: couldn't find a record matching the id invalid-import-id
      tags:
      - Records
  /records/smart-import/{importId}:
    post:
      summary: Upload a Smart Import Record to an existing Import
      description: "Upload a file to an existing import and create a record with smart import and predictions. Provide none of recordType, newRecordTypeId, or newRecordTypeDisplayName to default to Imported type. \n\n**OAuth Scope required:** `public.records.createSmartImportRecords`"
      operationId: create-a-smart-import-record-to-import
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - name: importId
        in: path
        description: 'The Import Id. You can upload a record to an existing import in the repository. '
        schema:
          type: string
        required: true
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - attachment
              - recordType
              type: object
              properties:
                attachment:
                  type: string
                  format: binary
                  description: Must be a binary. Base64 is not accepted at this time.
                recordType:
                  type: string
                  default: imported
                  description: Upload a smart import record as an existing record type.  Cannot provide alongside newRecordTypeId and newRecordTypeDisplayName. Defaults to Imported.
                newRecordTypeId:
                  type: string
                  description: The record type ID for a not-yet-existing record type.  Must be provided along with a newRecordTypeDisplayName
                newRecordTypeDisplayName:
                  type: string
                  description: The display name of the new record type to create.
      security:
      - sec0: []
        OAuth2:
        - public.records.createSmartImportRecords
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  recordId:
                    type: string
                    description: Record ID of the new created record
                    example: 17fe582d-e1e0-4000-bf65-3d2ec2c500a4
                  importId:
                    type: string
                    example: 55ez635d-f2g9-5419-gs34-8h1jx4s733q9
                  remainingCredits:
                    type: number
                    example: 50
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  param:
                    type: string
              examples:
                invalidRecordType:
                  summary: Invalid record type.
                  value:
                    code: INVALID_PARAM
                    message: unknown record type invalid_record_type
                    param: recordType
                invalidAttachment:
                  summary: Document size is too large.
                  value:
                    code: INVALID_PARAM
                    message: parameter 'attachment' too large, please limit upload files less than 100MB
                    param: attachment
                invalidFileType:
                  summary: Document size is too large.
                  value:
                    code: INVALID_PARAM
                    message: 'filename invalidFile.xyz does not have an accepted extension. Only the following extensions are allowed: .pdf, .docx, .doc, .xls, .xlsx, .eml, .tif, .jpg, .png, .jpeg, .txt, .ppt, .pptx.'
                    param: metadata.filename
        '403':
          description: '403'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              examples:
                outOfSmartImportCredits:
                  summary: No more AI Contract Credits are available
                  value:
                    code: FORBIDDEN
                    message: No more AI Contract Credits available
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
              examples:
                invalidImportId:
                  summary: Import Id is invalid or does not exist
                  value:
                    code: NOT_FOUND
                    message: couldn't find a record matching the id invalid-import-id
      tags:
      - Records
  /records/{id}:
    get:
      summary: Retrieve a Record
      description: "View a specific record and its associated data. \n\n**OAuth Scope required:** `public.records.readRecords`"
      operationId: retrieve-a-record
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/HydrateEntitiesFlag'
      - $ref: '#/components/parameters/addressAsObject'
      - name: id
        in: path
        description: The ID or Ironclad ID of the Record.
        schema:
          type: string
        required: true
      security:
      - sec0: []
        OAuth2:
        - public.records.readRecords
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordModel'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties: {}
      tags:
      - Records
    put:
      summary: Replace a Record
      description: "Update an existing record with a new set of metadata. \n\n**OAuth Scope required:** `public.records.updateRecords`"
      operationId: replace-a-record
      parameters:
      - $ref: '#/components/parameters/XAsUserEmail'
      - $ref: '#/components/parameters/XAsUserId'
      - $ref: '#/components/parameters/addressAsObject'
      - name: id
        in: path
        description: The ID or Ironclad ID of the Record.
        schema:
          type: string
        required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              - name
              - properties
              properties:
                type:
                  type: string
     

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