openapi: 3.0.3

info:
  title: Contact Documents
  description: "Use this endpoint to manage documents for a contact. For information of how to construct requests utilising fieldsets, sorting, paging, filters, and '*includes*', please refer to the API Developer Portal. E&OE."
  version: "1.0"

paths:
  '/contactdocuments':
    get:
      description: Returns the collection of all contact documents.
      tags:
        - Contact Documents
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedContactDocuments'

    post:
      description: Create a new contact document.
      tags:
        - Contact Documents
      requestBody:
        $ref: '#/components/requestBodies/CreateContactDocument'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactDocument'

  '/contactdocuments/{id}':
    get:
      description: Returns a single contact document.
      tags:
        - Contact Documents
      parameters:
        - name: id
          in: path
          description: Unique identifier for a single contact document.
          required: true
          schema:
            type: integer
            format: integer
          example: 568
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactDocument'

    put:
      description: Updates a single contact document.
      tags:
        - Contact Documents
      parameters:
        - name: id
          in: path
          description: Unique identifier for a single contact document.
          required: true
          schema:
            type: integer
            format: integer
          example: 568
      requestBody:
        $ref: '#/components/requestBodies/UpdateContactDocument'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactDocument'

    delete:
      description: Delete a single contact document
      tags:
        - Contact Documents
      parameters:
        - name: id
          in: path
          description: Unique identifier for a single contact document.
          required: true
          schema:
            type: integer
            format: integer
          example: 568
      responses:
        '204':
          description: Success, No Content.

components:
  schemas:
    PagedContactDocuments:
      type: object
      properties:
        contactdocuments:
          type: array
          items:
            $ref: '#/components/schemas/ContactDocument'
        meta:
          $ref: '#/components/schemas/PageMetaData'

    PageMetaData:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingData'

    PagingData:
      type: object
      properties:
        contactdocuments:
          $ref: '#/components/schemas/ContactDocumentPageData'

    ContactDocumentPageData:
      type: object
      properties:
        recordCount:
          description: The total number of contact documents returned by the underlying query.
          type: integer
          example: 2487
        pageCount:
          description: The total number of pages generated by the underlying query.
          type: integer
          example: 50
        page:
          description: The page number for this page of contact documents.
          type: integer
          example: 2
        pageSize:
          description: Page size.
          type: integer
          example: 50
        prevPage:
          description: A URL to the previous page of contact documents.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/contactdocuments?page=1
        nextPage:
          description: A URL to the next page of contact documents.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/contactdocuments?page=3

    ContactDocument:
      type: object
      properties:
        id:
          description: Unique identifier for a contact document. 
          type: integer
          format: integer
          example: 586
          readOnly: true
        name:
          description: The name given to the document.
          type: string
          format: string
          example: Contract Terms and Conditions
        createdTimestamp:
          description: Timestamp for when the contact document was created. This is not the created date for the underlying document.
          type: string
          format: string
          example: 2025-05-13T14:36:33+12:00
          readOnly: true
        modifiedTimestamp:
          description: Timestamp for when the contact document was last modified. This is not the last modified date for the underlying document.
          type: string
          format: string
          example: 2025-09-17T09:12:32+12:00
          readOnly: true
        status:
          description: Status for the contact document.
          enum:
          - pending
          - generated
          - uploaded
          type: string
          format: string
          example: uploaded
          readOnly: true
        keywords:
          description: List of one of more keywords associated with the contact document.
          type: string
          format: string
          example: AML, KYC
          readOnly: true
        summary:
          description: A textual summary of the document.
          type: string
          format: string
          example: Updated KYC report.
        fileType:
          description: The file type for the contact document.
          type: string
          format: string
          example: image/png
          readOnly: true
        fileSize:
          description: The size (in bytes) of the underlying file.
          type: integer
          format: string
          example: 62739
          readOnly: true
        extension:
          description: Extension of the underlying file.
          type: string
          format: string
          example: png
          readOnly: true
        fileName:
          description: An internal file name assigned to the contact document.
          type: string
          format: string
          example: pid_11_1508314872d144890a7105bde4ec50182fc6.png
          readOnly: true
        sharepointUrl:
          description: A URL to the contact document.
          type: string
          format: string
          example: https://ap-southeast-2.actionstep.com/t/o/redstone/c/master/di/171049652/e/1750203825/u/94/dv/1/h/NTczOWVhYj/cddf/p/41845/d/1/driving%20license%20scan.png
          readOnly: true
        file:
          description: An internal reference for the contact document used for downloading the underlying file.
          type: string
          format: string
          example: CD::Contacts::63727::13
          readOnly: true
        links:
          $ref: '#/components/schemas/ContactDocumentLinks'

    ContactDocumentLinks:
      type: object
      properties:
        participant:
          description: Unique identifier for a contact to which this contact document is associated.
          example: 321845
          type: integer
        folder:
          description: Unique identifier for the containing folder hosting the contact document.
          example: 8263
          type: string
        createdBy:
          description: Unique identifier for the Actionstep user who created the contact document.
          example: 925
          type: integer
          readOnly: true          
        
    CreateContactDocument:
      type: object
      required:
        - file
      properties:
        name:
          description: A name to be given to the document.
          type: string
          format: string
          example: Contract Terms and Conditions
        summary:
          description: A textual summary of the document.
          type: string
          format: string
          example: Updated KYC report.
        file:
          description: The indentifier for the uploaded file used to create the contact document. The format of the file parameter is important. It must include both the unique file id and the file name (including the file extension) in the format {file_id};{file_name_with_extension}
          type: string
          format: string
          example: 1740278677tYhvZ7HgvIzLWKFqnBt9mvyb9grF2mvb;Contract Terms.pdf
        links:
          $ref: '#/components/schemas/CreateContactDocumentLinks'

    CreateContactDocumentLinks:
      type: object
      required:
        - participant
      properties:
        participant:
          description: Unique identifier for a contact to which the contact document is associated.
          example: 321845
          type: integer
        folder:
          description: Unique identifier for a document folder for the contact document.
          example: 8263
          type: string

    UpdateContactDocument:
      type: object
      properties:
        name:
          description: A name to be given to the document.
          type: string
          format: string
          example: Contract Terms and Conditions
        summary:
          description: A textual summary of the document.
          type: string
          format: string
          example: Updated KYC report.
        links:
          $ref: '#/components/schemas/UpdateContactDocumentLinks'

    UpdateContactDocumentLinks:
      type: object
      properties:
        folder:
          description: Unique identifier for a document folder for the contact document.
          example: 8263
          type: string

  requestBodies:
    CreateContactDocument:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateContactDocument'

    UpdateContactDocument:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateContactDocument'