openapi: 3.0.3
info:
  title: HIT Research Portal (Pure) person API
  description: Subset of the Elsevier Pure web services API exposed by the Harbin Institute of Technology research portal (scholar.hit.edu.cn). Covers read access to research outputs (publications) and persons (researchers). Derived faithfully from the live Pure OpenAPI document at /ws/api/openapi.json; deeply nested supporting schemas are simplified to generic objects. Original Pure API version 5.35.3-4.
  version: 5.35.3-4
  contact:
    name: Harbin Institute of Technology Research Portal
    url: https://scholar.hit.edu.cn/en/
servers:
- url: https://scholar.hit.edu.cn/ws/api
  description: HIT Pure web services API
security:
- apiKey: []
tags:
- name: person
paths:
  /persons:
    get:
      summary: Lists all persons
      description: Lists all persons in the Pure instance. If you need to filter the persons returned, see the POST version which supports additional filtering.
      operationId: person_list
      tags:
      - person
      parameters:
      - name: size
        in: query
        description: Number of returned persons per request.
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: The offset for the returned list. 0 or null value is from the start
        schema:
          type: integer
          format: int32
      - name: order
        in: query
        description: The order of the list, must be a value from /persons/orderings
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonListResult'
    put:
      summary: Create person
      description: Create person
      operationId: person_create
      tags:
      - person
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: Bad Request
  /persons/search:
    post:
      summary: Query operation for persons
      description: 'Lists persons in the Pure instance that matches the provided query, similar to the GET version, instead of using parameters to alter the response, an JSON document is posted with the request. The JSON document contains fields for all the parameters available for the GET version, but also additional '
      operationId: person_query
      tags:
      - person
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonListResult'
        '400':
          description: Bad request
  /persons/{uuid}:
    get:
      summary: Get person
      description: Get person with specific UUID.
      operationId: person_get
      tags:
      - person
      parameters:
      - name: uuid
        in: path
        required: true
        description: UUID of the desired person
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '301':
          description: The requested content have changed UUID
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
    put:
      summary: Update person
      description: Update person with specific UUID.
      operationId: person_update
      tags:
      - person
      parameters:
      - name: uuid
        in: path
        required: true
        description: UUID of the person to update
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: Bad Request
        '404':
          description: Resource not found
        '409':
          description: Version conflict
    delete:
      summary: Delete person
      description: Delete person with specific UUID.
      operationId: person_delete
      tags:
      - person
      parameters:
      - name: uuid
        in: path
        required: true
        description: UUID of the person
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Successful operation
        '404':
          description: Resource not found
        '409':
          description: Conflict
  /persons/allowed-main-research-areas:
    get:
      summary: A list of allowed main research areas
      description: Get a list of allowed main research areas associated with the person
      operationId: person_getAllowedMainResearchAreas
      tags:
      - person
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
  /persons/orderings:
    get:
      summary: Lists available orderings
      description: Lists all orderings available to the person endpoint. These values can be used by the order parameter.
      operationId: person_getOrderings
      tags:
      - person
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    Person:
      type: object
      description: An academic professional, student, or other individual attached to the institution.
      properties:
        pureId:
          type: integer
          format: int64
          description: Pure database ID of the object, prefer using the UUID if it is present on the entity
        uuid:
          type: string
          format: uuid
          description: UUID, this is the primary identity of the entity
        createdBy:
          type: string
          description: Username of creator
        createdDate:
          type: string
          format: date-time
          description: Date and time of creation
        modifiedBy:
          type: string
          description: Username of the user that performed a modification
        modifiedDate:
          type: string
          format: date-time
          description: Date and time of last modification
        portalUrl:
          type: string
          description: URL of the content on the Pure Portal
        prettyUrlIdentifiers:
          type: array
          items:
            type: string
        previousUuids:
          type: array
          items:
            type: string
        version:
          type: string
          description: Used to guard against conflicting updates. For new content this is null, and for existing content the current value. The property should never be modified by a client, except in the rare case where th
        personExpertise:
          type: object
        startDateAsResearcher:
          type: string
          format: date
          description: Date that the person entered into the academic profession.
        affiliationNote:
          type: string
          description: Notes regarding affiliations of the person.
        dateOfBirth:
          type: string
          format: date
          description: The person's date of birth.
        employeeStartDate:
          type: string
          format: date
          description: Date of the persons first day of the institution.
        employeeEndDate:
          type: string
          format: date
          description: Date of the persons last day of the institution.
        externalPositions:
          type: array
          items:
            type: object
        keywordGroups:
          type: array
          items:
            type: object
        leavesOfAbsence:
          type: array
          items:
            type: object
        links:
          type: array
          items:
            type: object
        name:
          type: object
        names:
          type: array
          items:
            type: object
        nationality:
          type: object
        orcid:
          type: string
          description: orcid of the person.
        orcidAuthenticated:
          type: boolean
          description: Authentication status of the orcid associated with the person.
        cienciaId:
          type: string
          description: Ciencia ID of the person.
        cienciaIdAuthenticated:
          type: boolean
          description: Authentication status of the Ciencia ID associated with the person.
        honoraryStaffOrganizationAssociations:
          type: array
          items:
            type: object
        staffOrganizationAssociations:
          type: array
          items:
            type: object
        studentOrganizationAssociations:
          type: array
          items:
            type: object
        visitingScholarOrganizationAssociations:
          type: array
          items:
            type: object
        academicQualifications:
          type: array
          items:
            type: object
        profilePhotos:
          type: array
          items:
            type: object
        documents:
          type: array
          items:
            type: object
        privateAddress:
          type: object
        professionalQualifications:
          type: array
          items:
            type: object
        selectedForProfileRefinementService:
          type: boolean
          description: If the person has been profiled.
        profileInformation:
          type: array
          items:
            type: object
        retirementDate:
          type: string
          format: date
          description: Date of retirement for the person
        gender:
          type: object
        titles:
          type: array
          items:
            type: object
        visibility:
          type: object
        willingToTakePhdStudents:
          type: boolean
          description: Boolean to define if the Person is willing to take on Phd Students.
        willingToTakePhdStudentsDescription:
          type: string
          description: Field to describe or list phd projects that the person will participate in.
        identifiers:
          type: array
          items:
            type: object
        user:
          type: object
        customDefinedFields:
          type: object
        workflow:
          type: object
        mainResearchArea:
          type: object
        profiled:
          type: boolean
        systemName:
          type: string
          description: The content system name
    PersonListResult:
      type: object
      properties:
        count:
          type: integer
          format: int64
          description: Total number of items.
        pageInformation:
          type: object
          description: Pagination info.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Person'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: api-key
      description: Pure API key. The HIT instance requires an issued key for API access.