University of Groningen externalPerson API

openapi: 3.0.3
info:
  title: Dataverse Access externalPerson API
  description: Open source research data repository software.
  version: '6.9'
servers:
- url: https://dataverse.nl
tags:
- name: externalPerson
paths:
  /external-persons:
    get:
      tags:
      - externalPerson
      summary: Lists all external persons
      description: Lists all external persons in the Pure instance. If you need to filter the external persons returned, see the POST version which supports additional filtering.
      operationId: externalPerson_list
      parameters:
      - name: size
        in: query
        description: Number of returned external persons per request.
        schema:
          maximum: 1000
          type: integer
          format: int32
          default: 10
      - name: offset
        in: query
        description: The offset for the returned list. 0 or null value is from the start
        schema:
          type: integer
          format: int32
          default: 0
      - name: order
        in: query
        description: The order of the list, must be a value from /external-persons/orderings
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalPersonListResult'
    put:
      tags:
      - externalPerson
      summary: Create external person
      description: Create external person
      operationId: externalPerson_create
      requestBody:
        description: The content to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalPerson'
        required: true
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalPerson'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /external-persons/allowed-classified-identifier-types:
    get:
      tags:
      - externalPerson
      summary: A list of allowed classified identifier types
      description: Get a list of allowed classified identifier types that can be used for the 'identifiers.type' attribute of external persons
      operationId: externalPerson_getAllowedClassifiedIdentifierTypes
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationRefList'
  /external-persons/allowed-countries:
    get:
      tags:
      - externalPerson
      summary: A list of allowed countries
      description: Get a list of allowed countries that can be used for the 'countries' attribute of external persons
      operationId: externalPerson_getAllowedCountries
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationRefList'
  /external-persons/allowed-image-types:
    get:
      tags:
      - externalPerson
      summary: A list of allowed image types
      description: Get a list of allowed image types that can be used for the 'images.type' attribute of external persons
      operationId: externalPerson_getAllowedImageTypes
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationRefList'
  /external-persons/allowed-keyword-group-configurations:
    get:
      tags:
      - externalPerson
      summary: A list of keyword group configurations
      description: Get a list of allowed keyword group configurations that can be used when submitting keyword groups.
      operationId: externalPerson_getAllowedKeywordGroupConfigurations
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AllowedKeywordGroupConfigurationList'
  /external-persons/allowed-keyword-group-configurations/{id}/classifications:
    get:
      tags:
      - externalPerson
      summary: A list of allowed classifications for the specified keyword group
      description: Get a list of allowed classifications that can be used when submitting a specified keyword group.
      operationId: externalPerson_getAllowedKeywordGroupConfigurationClassifications
      parameters:
      - name: id
        in: path
        description: Pure id of the keyword group configuration
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationRefList'
  /external-persons/allowed-locales:
    get:
      tags:
      - externalPerson
      summary: A list of allowed locales in localized strings
      description: Get a list of allowed locales that can be used when submitting localized string entities.
      operationId: externalPerson_getAllowedLocales
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocalesList'
  /external-persons/allowed-types:
    get:
      tags:
      - externalPerson
      summary: A list of allowed external person types
      description: Get a list of allowed types that can be used for the 'type' attribute of external persons
      operationId: externalPerson_getAllowedTypes
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassificationRefList'
  /external-persons/allowed-workflow-steps:
    get:
      tags:
      - externalPerson
      summary: A list of allowed workflow steps
      description: Get a list of allowed workflow steps that can be used for the 'workflow' attribute of external persons
      operationId: externalPerson_getAllowedWorkflowSteps
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowListResult'
  /external-persons/disciplines/allowed-discipline-schemes:
    get:
      tags:
      - externalPerson
      summary: A list of allowed discipline schemes
      description: Get a list fo a allowed discipline schemes for external persons
      operationId: externalPerson_getAllowedDisciplineSchemes
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisciplinesDisciplineSchemeListResult'
  /external-persons/disciplines/{discipline-scheme}/allowed-disciplines:
    get:
      tags:
      - externalPerson
      summary: A list of allowed disciplines for a specific discipline scheme
      description: Get a list of a allowed disciplines for specific discipline scheme for external persons
      operationId: getAllowedDisciplines
      parameters:
      - name: discipline-scheme
        in: path
        description: Identifier for the discipline scheme for external persons
        required: true
        schema:
          type: string
      - name: size
        in: query
        description: Number of returned disciplines per request
        schema:
          maximum: 1000
          type: integer
          format: int32
          default: 10
      - name: offset
        in: query
        description: The offset for the returned list. 0 or null value is from the start
        schema:
          type: integer
          format: int32
          default: 0
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisciplinesDisciplineListResult'
  /external-persons/disciplines/{discipline-scheme}/search:
    post:
      tags:
      - externalPerson
      summary: Query operation for disciplines associated with external persons
      description: Lists disciplines from the discipline scheme associated with external persons in the Pure instance that matches the provided query.
      operationId: externalPerson_listDisciplineAssociations
      parameters:
      - name: discipline-scheme
        in: path
        description: Identifier for the discipline scheme
        required: true
        schema:
          type: string
      requestBody:
        description: The query to perform
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisciplinesAssociationsQuery'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisciplinesAssociationListResult'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /external-persons/file-uploads:
    put:
      tags:
      - externalPerson
      summary: Upload file to a specific external person
      description: Uploads file for the external person
      operationId: externalPerson_fileUploads
      parameters:
      - name: Content-Type
        in: header
        description: Set the mime type for the file
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              type: string
              format: binary
        required: true
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadedFile'
            application/xml:
              schema:
                $ref: '#/components/schemas/UploadedFile'
  /external-persons/orderings:
    get:
      tags:
      - externalPerson
      summary: Lists available orderings
      description: Lists all orderings available to the external person endpoint. These values can be used by the order parameter.
      operationId: externalPerson_getOrderings
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderingsList'
  /external-persons/search:
    post:
      tags:
      - externalPerson
      summary: Query operation for external persons
      description: Lists external 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 filtering options.
      operationId: externalPerson_query
      requestBody:
        description: The query to perform
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalPersonsQuery'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalPersonListResult'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /external-persons/{uuid}:
    get:
      tags:
      - externalPerson
      summary: Get external person
      description: Get external person with specific UUID.
      operationId: externalPerson_get
      parameters:
      - name: uuid
        in: path
        description: UUID of the desired external person
        required: true
        schema:
          pattern: .+
          type: string
          format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalPerson'
        '301':
          description: The requested content have changed UUID
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - externalPerson
      summary: Update external persons
      description: Update external persons with specific UUID.
      operationId: externalPerson_update
      parameters:
      - name: uuid
        in: path
        description: UUID of the external person to update
        required: true
        schema:
          pattern: .+
          type: string
          format: uuid
      requestBody:
        description: The content to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalPerson'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalPerson'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Resource not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Version conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictProblemDetails'
    delete:
      tags:
      - externalPerson
      summary: Delete external person
      description: Delete external person with specific UUID.
      operationId: externalPerson_delete
      parameters:
      - name: uuid
        in: path
        description: UUID of the external person
        required: true
        schema:
          pattern: .+
          type: string
          format: uuid
      responses:
        '204':
          description: Successful operation
        '404':
          description: Resource not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictProblemDetails'
  /external-persons/{uuid}/actions/lock:
    post:
      tags:
      - externalPerson
      summary: Lock the content
      description: Mark the content as external (used when content contains synchronised data). This has no effect on interactions with the content through the API.
      operationId: externalPerson_lock
      parameters:
      - name: uuid
        in: path
        description: UUID of the content to lock
        required: true
        schema:
          pattern: .+
          type: string
          format: uuid
      responses:
        '204':
          description: Content marked as locked
        '404':
          description: Resource not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Content already locked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictProblemDetails'
  /external-persons/{uuid}/actions/unlock:
    post:
      tags:
      - externalPerson
      summary: Unlock the content
      description: Remove the external mark on the content (used when content contains synchronised data). This has no effect on interactions with the content through the API.
      operationId: externalPerson_unlock
      parameters:
      - name: uuid
        in: path
        description: UUID of the content to unlock
        required: true
        schema:
          pattern: .+
          type: string
          format: uuid
      responses:
        '204':
          description: Content marked as unlocked
        '404':
          description: Resource not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Content already unlocked
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictProblemDetails'
  /external-persons/{uuid}/dependents:
    get:
      tags:
      - externalPerson
      summary: Lists all dependents to a external person
      description: 'Lists all dependents to a external person with the specified UUID. If the user does not have access to view all the dependent content, an authorization error will be thrown. '
      operationId: externalPerson_dependents
      parameters:
      - name: uuid
        in: path
        description: UUID of the external person
        required: true
        schema:
          pattern: .+
          type: string
          format: uuid
      - name: verbose
        in: query
        description: DEPRECATED - Parameter has no effect.
        deprecated: true
        schema:
          type: boolean
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentRefListResult'
  /external-persons/{uuid}/disciplines/{discipline-scheme}:
    get:
      tags:
      - externalPerson
      summary: Get disciplines from the discipline scheme associated with the external person
      description: Get disciplines from the discipline scheme associated with the external person with specific UUID.
      operationId: externalPerson_getDisciplineAssociation
      parameters:
      - name: uuid
        in: path
        description: UUID of the desired external person
        required: true
        schema:
          pattern: .+
          type: string
          format: uuid
      - name: discipline-scheme
        in: path
        description: Identifier for the discipline scheme
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisciplinesAssociation'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - externalPerson
      summary: Update disciplines from the discipline scheme associated with the external person
      description: Update disciplines from the discipline scheme associated with the external person with specific UUID.
      operationId: externalPerson_putDisciplineAssociation
      parameters:
      - name: uuid
        in: path
        description: UUID of the external person to update
        required: true
        schema:
          pattern: .+
          type: string
          format: uuid
      - name: discipline-scheme
        in: path
        description: Identifier for the discipline scheme
        required: true
        schema:
          type: string
      requestBody:
        description: The disciplines association to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisciplinesAssociation'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisciplinesAssociation'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Resource not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /external-persons/{uuid}/files/{fileId}:
    get:
      tags:
      - externalPerson
      summary: Get file from the external person
      description: Get file from the external person
      operationId: externalPerson_getFile
      parameters:
      - name: uuid
        in: path
        description: UUID of the external person
        required: true
        schema:
          pattern: .+
          type: string
          format: uuid
      - name: fileId
        in: path
        description: 'File id '
        required: true
        schema:
          pattern: .+
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            '*/*':
              schema:
                type: string
                format: binary
  /external-persons/{uuid}/notes:
    get:
      tags:
      - externalPerson
      summary: Lists notes
      description: Lists notes associated with an external person ordered by date (nulls last)
      operationId: externalPerson_listNotes
      parameters:
      - name: uuid
        in: path
        description: UUID of the external person to get notes for
        required: true
        schema:
          pattern: .+
          type: string
          format: uuid
      - name: size
        in: query
        description: Number of returned notes per request
        schema:
          maximum: 1000
          type: integer
          format: int32
          default: 10
      - name: offset
        in: query
        description: The offset for the returned list. 0 or null value is from the start
        schema:
          type: integer
          format: int32
          default: 0
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoteListResult'
        '404':
          description: External person not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    put:
      tags:
      - externalPerson
      summary: Create note
      description: Create note and associate it with an external person
      operationId: externalPerson_createNote
      parameters:
      - name: uuid
        in: path
        description: UUID of the external person to add note to
        required: true
        schema:
          pattern: .+
          type: string
          format: uuid
      requestBody:
        description: The note to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Note'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    PageInformation:
      type: object
      properties:
        offset:
          type: integer
          description: Offset that returned items start at
          format: int32
        size:
          type: integer
          description: The requested number of items. May be higher than the actual number of items in the result if there are fewer items in the store than requested
          format: int32
      description: Information about pages
    ContentRef:
      required:
      - systemName
      - uuid
      type: object
      properties:
        uuid:
          type: string
          description: UUID of the referred content
          format: uuid
        systemName:
          type: string
      nullable: true
      discriminator:
        propertyName: systemName
        mapping:
          AccessDefinition: '#/components/schemas/AccessDefinitionRef'
          Activity: '#/components/schemas/ActivityRef'
          Application: '#/components/schemas/ApplicationRef'
          AuthorCollaboration: '#/components/schemas/AuthorCollaborationRef'
          Award: '#/components/schemas/AwardRef'
          ClassificationScheme: '#/components/schemas/ClassificationSchemeRef'
          ConferenceSeries: '#/components/schemas/ConferenceSeriesRef'
          DataSet: '#/components/schemas/DataSetRef'
          Equipment: '#/components/schemas/EquipmentRef'
          Event: '#/components/schemas/EventRef'
          ExternalOrganization: '#/components/schemas/ExternalOrganizationRef'
          ExternalPerson: '#/components/schemas/ExternalPersonRef'
          Impact: '#/components/schemas/ImpactRef'
          Journal: '#/components/schemas/JournalRef'
          Organization: '#/components/schemas/OrganizationRef'
          Person: '#/components/schemas/PersonRef'
          Publisher: '#/components/schemas/PublisherRef'
          PressMedia: '#/components/schemas/PressMediaRef'
          Prize: '#/components/schemas/PrizeRef'
          Project: '#/components/schemas/ProjectRef'
          ResearchOutput: '#/components/schemas/ResearchOutputRef'
          StudentThesis: '#/components/schemas/StudentThesisRef'
          FundingOpportunity: '#/components/schemas/FundingOpportunityRef'
          EthicalReview: '#/components/schemas/EthicalReviewRef'
          ApplicationCluster: '#/components/schemas/ApplicationClusterRef'
          AwardCluster: '#/components/schemas/AwardClusterRef'
          User: '#/components/schemas/UserRef'
          ERA2018FieldOfResearch: '#/components/schemas/Anzsrc2008FieldOfResearchRef'
          UnitOfAssessmentREF2014: '#/components/schemas/Ref2014UnitOfAssessmentRef'
          UnitOfAssessmentREF2020: '#/components/schemas/Ref2020UnitOfAssessmentRef'
          ANZSRCTypeOfActivity: '#/components/schemas/Anzsrc2020TypeOfActivityRef'
          ANZSRCFieldOfResearch: '#/components/schemas/Anzsrc2020FieldOfResearchRef'
          ANZSRCSocioEconomicObjective: '#/components/schemas/Anzsrc2020SocioEconomicObjectiveRef'
          Semester: '#/components/schemas/SemesterRef'
          Education: '#/components/schemas/EducationRef'
          Course: '#/components/schemas/CourseRef'
          CurriculumVitae: '#/components/schemas/CurriculumVitaeRef'
          CustomDefinedFieldConfiguration: '#/components/schemas/CustomDefinedFieldConfigurationRef'
          KeywordGroupConfiguration: '#/components/schemas/KeywordGroupConfigurationRef'
          Review: '#/components/schemas/ReviewRef'
          GenericContentRef: '#/components/schemas/GenericContentRef'
          UserProfile: '#/components/schemas/UserProfileRef'
          Thesaurus: '#/components/schemas/ThesaurusRef'
          Concept: '#/components/schemas/ConceptRef'
          PersonExpertise: '#/components/schemas/PersonExpertiseRef'
          Contract: '#/components/schemas/ContractRef'
          Milestone: '#/components/schemas/MilestoneRef'
          Fingerprint: '#/components/schemas/FingerprintRef'
          Specialization: '#/components/schemas/SpecializationRef'
          StudentProject: '#/components/schemas/StudentProjectRef'
    LocalizedString:
      type: object
      additionalProperties:
        type: string
        description: 'A set of string values, one for each submission locale. Note: invalid locale values will be ignored.'
        nullable: true
        example: '{"en_GB":"Some text"}'
      description: 'A set of string values, one for each submission locale. Note: invalid locale values will be ignored.'
      nullable: true
      example:
        en_GB: Some text
    DisciplinesAssociation:
      required:
      - disciplineAssignments
      type: object
      properties:
        content:
          $ref: '#/components/schemas/ContentRef'
        disciplineScheme:
          type: string
          description: The discipline scheme these disciplines are assigned from
          readOnly: true
        disciplineAssignments:
          type: array
          description: A collection of assigned disciplines
          items:
            $ref: '#/components/schemas/DisciplinesDisciplineAssignment'
      description: An association between a content and a number of discipline assignments
    DisciplinesDisciplineListResult:
      type: object
      properties:
        count:
          type: integer
          description: The full count, ignoring paging
          format: int32
        pageInformation:
          $ref: '#/components/schemas/PageInformation'
        items:
          type: array
          description: Disciplines
          items:
            $ref: '#/components/schemas/DisciplinesDiscipline'
      description: List of disciplines for a specific discipline scheme
    FormattedLocalizedString:
      type: object
      additionalProperties:
        type: string
        description: A set of localized strings that support formatting. Invalid locale values will be ignored.
        nullable: true
        example: '{"en_GB":"Some text"}'
      description: A set of localized strings that support formatting. Invalid locale values will be ignored.
      nullable: true
      example:
        en_GB: Some text
    Gender:
      type: object
      properties:
        key:
          type: string
          enum:
          - MALE
          - FEMALE
          - UNKNOWN
        value:
          $ref: '#/components/schemas/LocalizedString'
      description: A list of possible genders
      nullable: true
    SystemLocalizedString:
      type: object
      additionalProperties:
        type: string
        description: A set of localized string values each for a specific UI locale.
        nullable: true
        example: '{"en_GB":"Some text"}'
      description: A set of localized string values each for a specific UI locale.
      nullable: true
      example:
        en_GB: Some text
    ContentRefListResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ContentRef'
      description: List of Content Refs
    Note:
      required:
      - text
      type: object
      properties:
        date:
          type: string
          description: Date and time of when the note was created, an event occurred or similar. Can be any point in time, but <now> is normally preferred
          format: date-time
          nullable: true
        username:
          type: string
          description: Username related to the note. Usually a username of the user creating the note. Does not have to be a username of a Pure user
          nullable: true
        text:
          type: string
          description: Note text
      description: A note
    NoteListResult:
      type: object
      properties:
        count:
          type: integer
          description: The full count, ignoring paging
          format: int32
        pageInformation:
          $ref: '#/components/schemas/PageInformation'
        items:
          type: array
          description: Notes
          items:
            $ref: '#/components/schemas/Note'
      description: List of notes
    DisciplinesDiscipline:
      type: object
      properties:
        disciplineId:
          type: string
          description: The discipline identifier
          readOnly: true
        title:
          type: string
          description: The discipline title
          readOnly: true
        description:
          type: string
          description: The discipline description
          readOnly: true
      description: A discipline within a specific discipline scheme
    ImageFile:
      required:
      - fileName
      - mimeType
      type: object
      properti

# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-groningen/refs/heads/main/openapi/university-of-groningen-externalperson-api-openapi.yml