openapi: 3.1.0
info:
  title: RelativityOne Legal Hold Communications Custodians API
  description: The Legal Hold API enables matter and project management integration with external systems such as matter management platforms and HR systems. It provides endpoints for custodian management, preservation workflows, task tracking, entity management, and communication configuration. Authentication is handled via Microsoft Graph API.
  version: 1.0.0
  contact:
    url: https://platform.relativity.com/
  license:
    name: Proprietary
    url: https://www.relativity.com/terms-of-service/
servers:
- url: https://relativity.rest/api
  description: RelativityOne REST API
security:
- BearerAuth: []
tags:
- name: Custodians
  description: Operations for managing legal hold custodians
paths:
  /relativity-environment/v1/workspaces/{workspaceId}/legal-hold/projects/{projectId}/custodians:
    get:
      operationId: listProjectCustodians
      summary: List Project Custodians
      description: Retrieves all custodians assigned to a specific legal hold project.
      tags:
      - Custodians
      parameters:
      - name: workspaceId
        in: path
        required: true
        description: The artifact ID of the workspace.
        schema:
          type: integer
      - name: projectId
        in: path
        required: true
        description: The artifact ID of the legal hold project.
        schema:
          type: integer
      responses:
        '200':
          description: List of custodians returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustodianList'
        '404':
          description: Project not found.
    post:
      operationId: addCustodianToProject
      summary: Add Custodian to Project
      description: Adds a custodian to a legal hold project.
      tags:
      - Custodians
      parameters:
      - name: workspaceId
        in: path
        required: true
        description: The artifact ID of the workspace.
        schema:
          type: integer
      - name: projectId
        in: path
        required: true
        description: The artifact ID of the legal hold project.
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCustodianRequest'
      responses:
        '200':
          description: Custodian added successfully.
  /relativity-environment/v1/workspaces/{workspaceId}/legal-hold/active-custodians:
    get:
      operationId: getActiveCustodianSummary
      summary: Get Active Custodian Summary
      description: Retrieves a list of all custodians who are actively on-hold across all projects. Returns up to 1000 records with pagination support.
      tags:
      - Custodians
      parameters:
      - name: workspaceId
        in: path
        required: true
        description: The artifact ID of the workspace.
        schema:
          type: integer
      - name: start
        in: query
        required: false
        description: The starting index for pagination.
        schema:
          type: integer
          default: 0
      - name: length
        in: query
        required: false
        description: Number of records to return (max 1000).
        schema:
          type: integer
          default: 100
          maximum: 1000
      responses:
        '200':
          description: Active custodian summary returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveCustodianSummaryList'
components:
  schemas:
    ActiveCustodianSummaryList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ActiveCustodianSummary'
        totalCount:
          type: integer
          description: Total number of active custodians.
    Custodian:
      type: object
      properties:
        artifactId:
          type: integer
          description: The unique artifact ID of the custodian.
        firstName:
          type: string
          description: First name of the custodian.
        lastName:
          type: string
          description: Last name of the custodian.
        emailAddress:
          type: string
          format: email
          description: Email address of the custodian.
        employeeId:
          type: string
          description: Optional employee identifier from HR system.
        status:
          type: string
          description: Current hold status of the custodian.
    ActiveCustodianSummary:
      type: object
      properties:
        projectId:
          type: integer
          description: The artifact ID of the project.
        projectName:
          type: string
          description: Name of the legal hold project.
        firstName:
          type: string
          description: First name of the custodian.
        lastName:
          type: string
          description: Last name of the custodian.
        emailAddress:
          type: string
          format: email
          description: Email address of the custodian.
        employeeId:
          type: string
          description: Optional employee identifier.
    AddCustodianRequest:
      type: object
      required:
      - emailAddress
      properties:
        emailAddress:
          type: string
          format: email
          description: Email address of the custodian to add.
        employeeId:
          type: string
          description: Optional employee identifier.
    CustodianList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Custodian'
        totalCount:
          type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token obtained via Microsoft Graph API OAuth flow.