OpenClinica ODM Metadata API

openapi: 3.0.3
info:
  title: OpenClinica REST API
  description: >-
    OpenClinica is a clinical-trial electronic data capture (EDC) and clinical
    data management platform. Its REST web services API lets you programmatically
    add and update participants (single and bulk), schedule and update study
    events, and import and retrieve clinical (case report form) data. Clinical
    data and study metadata are interchanged using the CDISC ODM (Operational
    Data Model) standard as XML or JSON. Access requires an OAuth 2.0 bearer
    token obtained from the OpenClinica user-service token endpoint; the token is
    sent as an Authorization Bearer header on every call. OpenClinica is a
    multi-tenant SaaS - the {subdomain} server variable is your instance
    subdomain. A free, open-source Community Edition (LGPL) is also self-hostable.

    Endpoint accuracy note: the /pages/auth/api/clinicaldata participant, event,
    and clinical-data paths are grounded in OpenClinica 4 documentation. Bulk
    request bodies, the clinical-data import payload, and the ODM metadata path
    are modeled from the documentation and should be reconciled against your
    instance version before production use.
  version: '4.0'
  contact:
    name: OpenClinica
    url: https://www.openclinica.com
  license:
    name: LGPL-2.1 (Community Edition)
    url: https://github.com/OpenClinica/OpenClinica/blob/master/LICENSE.txt
servers:
  - url: https://{subdomain}.build.openclinica.io
    description: OpenClinica hosted instance (replace {subdomain} with your instance subdomain)
    variables:
      subdomain:
        default: your-instance
        description: Your OpenClinica instance subdomain.
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: OAuth 2.0 token acquisition.
  - name: Participants
    description: Study participants (subjects) - add, update, list, and extract contact info.
  - name: Study Events
    description: Scheduling and updating study events (visits) for participants.
  - name: Clinical Data
    description: Import and retrieve CRF data using CDISC ODM.
  - name: Metadata
    description: Read ODM study design metadata.
  - name: Bulk Operations
    description: Bulk participant and event operations plus the bulk actions log.
paths:
  /user-service/api/oauth/token:
    post:
      operationId: getAccessToken
      tags:
        - Authentication
      summary: Obtain an OAuth 2.0 access token
      description: >-
        POST credentials to obtain a bearer access token. The token is then sent
        as an Authorization Bearer header on all subsequent REST API calls.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  example: password
                username:
                  type: string
                password:
                  type: string
      responses:
        '200':
          description: An access token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                    example: bearer
                  expires_in:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pages/auth/api/clinicaldata/studies/{studyOID}/participants:
    get:
      operationId: listStudyParticipants
      tags:
        - Participants
      summary: Get participants at study level
      description: Lists participants enrolled in a study, qualified by study OID.
      parameters:
        - $ref: '#/components/parameters/StudyOID'
      responses:
        '200':
          description: A list of participants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: addStudyParticipant
      tags:
        - Participants
      summary: Add or update a participant at study level
      description: Creates or updates a single participant enrolled directly at the study level.
      parameters:
        - $ref: '#/components/parameters/StudyOID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Participant'
      responses:
        '200':
          description: The created or updated participant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pages/auth/api/clinicaldata/studies/{studyOID}/sites/{siteOID}/participants:
    get:
      operationId: listSiteParticipants
      tags:
        - Participants
      summary: Get participants at site level
      description: Lists participants enrolled at a specific site within a study.
      parameters:
        - $ref: '#/components/parameters/StudyOID'
        - $ref: '#/components/parameters/SiteOID'
      responses:
        '200':
          description: A list of participants for the site.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParticipantList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: addSiteParticipant
      tags:
        - Participants
      summary: Add or update a participant at site level
      description: Creates or updates a single participant enrolled at a specific site.
      parameters:
        - $ref: '#/components/parameters/StudyOID'
        - $ref: '#/components/parameters/SiteOID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Participant'
      responses:
        '200':
          description: The created or updated participant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Participant'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pages/auth/api/clinicaldata/studies/{studyOID}/sites/{siteOID}/participants/extractParticipantsInfo:
    post:
      operationId: extractParticipantsInfo
      tags:
        - Participants
      summary: Extract participant contact information
      description: >-
        Retrieves participant contact information (e.g. for notifications) for a
        study and site. Returns an asynchronous job that produces a contact-info
        extract.
      parameters:
        - $ref: '#/components/parameters/StudyOID'
        - $ref: '#/components/parameters/SiteOID'
      responses:
        '200':
          description: A job accepted to extract participant contact information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pages/auth/api/clinicaldata/studies/{studyOID}/participants/bulk:
    post:
      operationId: addBulkParticipants
      tags:
        - Bulk Operations
      summary: Add or update a bulk list of participants
      description: >-
        Adds or updates a list of participants in a single request. Modeled from
        the OpenClinica bulk participants documentation; reconcile the exact path
        and payload against your instance version.
      parameters:
        - $ref: '#/components/parameters/StudyOID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                participants:
                  type: array
                  items:
                    $ref: '#/components/schemas/Participant'
      responses:
        '200':
          description: A job accepted to process the bulk participant list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pages/auth/api/clinicaldata/studies/{studyOID}/events:
    post:
      operationId: createBulkStudyEvents
      tags:
        - Study Events
      summary: Bulk create or update study events
      description: >-
        Schedules or updates study events for multiple participants in a single
        request. Modeled from the OpenClinica bulk events documentation.
      parameters:
        - $ref: '#/components/parameters/StudyOID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/StudyEvent'
      responses:
        '200':
          description: A job accepted to process the bulk events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pages/auth/api/clinicaldata/studies/{studyOID}/sites/{siteOID}/events:
    post:
      operationId: createStudyEvent
      tags:
        - Study Events
      summary: Create (schedule) a single study event
      description: Schedules a single study event for a participant at a site.
      parameters:
        - $ref: '#/components/parameters/StudyOID'
        - $ref: '#/components/parameters/SiteOID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudyEvent'
      responses:
        '200':
          description: The scheduled study event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyEvent'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateStudyEvent
      tags:
        - Study Events
      summary: Update a single study event
      description: Updates an existing study event for a participant at a site.
      parameters:
        - $ref: '#/components/parameters/StudyOID'
        - $ref: '#/components/parameters/SiteOID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StudyEvent'
      responses:
        '200':
          description: The updated study event.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyEvent'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pages/auth/api/clinicaldata/{studyOID}/{participantOID}/{studyEventOID}/{formOID}:
    get:
      operationId: getClinicalData
      tags:
        - Clinical Data
      summary: Retrieve clinical data as CDISC ODM
      description: >-
        Retrieves participant clinical (CRF) data as a CDISC ODM XML or JSON
        document, scoped by study, participant, study event, and form OID.
        Optional query parameters include audit logs, discrepancy notes
        (queries), and archived-form clinical data.
      parameters:
        - $ref: '#/components/parameters/StudyOID'
        - name: participantOID
          in: path
          required: true
          schema:
            type: string
        - name: studyEventOID
          in: path
          required: true
          schema:
            type: string
        - name: formOID
          in: path
          required: true
          schema:
            type: string
        - name: includeAudits
          in: query
          required: false
          schema:
            type: boolean
        - name: includeDNs
          in: query
          required: false
          description: Include discrepancy notes (queries).
          schema:
            type: boolean
      responses:
        '200':
          description: Clinical data in CDISC ODM format.
          content:
            application/xml:
              schema:
                type: string
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pages/auth/api/clinicaldata:
    post:
      operationId: importClinicalData
      tags:
        - Clinical Data
      summary: Import clinical data (CDISC ODM)
      description: >-
        Imports clinical (CRF) data into a study using a CDISC ODM document.
        Modeled from the OpenClinica clinicaldata import documentation; confirm
        the exact path and payload against your instance version.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: string
              description: A CDISC ODM XML document.
      responses:
        '200':
          description: An import result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAccepted'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pages/auth/api/clinicaldata/metadata/{studyOID}:
    get:
      operationId: getStudyMetadata
      tags:
        - Metadata
      summary: Read ODM study metadata
      description: >-
        Reads the ODM metadata describing a study's design (event definitions,
        forms, item groups, and items), qualified by study OID. The requesting
        user must have read privileges for the study. Path modeled from the OC3
        ODM metadata REST service documentation.
      parameters:
        - $ref: '#/components/parameters/StudyOID'
      responses:
        '200':
          description: Study metadata in CDISC ODM format.
          content:
            application/xml:
              schema:
                type: string
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pages/auth/api/bulkActionsLog:
    get:
      operationId: getBulkActionsLog
      tags:
        - Bulk Operations
      summary: Retrieve the bulk actions log
      description: >-
        Returns the log of asynchronous bulk operations (bulk participants, bulk
        events, extracts) and their status. Path modeled from the OpenClinica
        bulk actions log documentation.
      responses:
        '200':
          description: A list of bulk action log entries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BulkActionLogEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    StudyOID:
      name: studyOID
      in: path
      required: true
      description: The unique study OID.
      schema:
        type: string
        example: S_STUDY01
    SiteOID:
      name: siteOID
      in: path
      required: true
      description: The unique site OID within the study.
      schema:
        type: string
        example: S_SITE01
  responses:
    Unauthorized:
      description: Authentication failed or the bearer token is missing, invalid, or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Participant:
      type: object
      properties:
        subjectKey:
          type: string
          description: The participant (subject) identifier.
        studyOID:
          type: string
        siteOID:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phoneNumber:
          type: string
        enrollmentDate:
          type: string
          format: date
    ParticipantList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Participant'
    StudyEvent:
      type: object
      properties:
        subjectKey:
          type: string
        studyEventOID:
          type: string
          description: The study event definition OID.
        ordinal:
          type: integer
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        status:
          type: string
          example: scheduled
    JobAccepted:
      type: object
      properties:
        uuid:
          type: string
          description: Identifier for the asynchronous job; check status via the bulk actions log.
        status:
          type: string
          example: PENDING
    BulkActionLogEntry:
      type: object
      properties:
        uuid:
          type: string
        actionType:
          type: string
          example: BULK_PARTICIPANT
        status:
          type: string
          example: COMPLETED
        createdDate:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string