Microsoft Azure PersonDirectory API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Person Directory API
tags:
- name: PersonDirectory
paths:
  /persons:
    get:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Retrieve List Of Person Information In Person Directory
      operationId: microsoftAzurePersondirectoryGetpersons
      parameters:
      - in: query
        name: start
        description: List persons from the least personId greater than the "start". It contains no more than 64 characters. Default is empty.
        schema:
          type: string
          format: uuid
      - in: query
        name: top
        description: The number of persons to list, ranging in [1, 1000]. Default is 1000.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EnrollmentResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Get person directory persons example:
          $ref: ./examples/GetPersonDirectoryPersons.json
      description: Needs a more full description created.
    post:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Creates A New Person In Person Directory
      operationId: microsoftAzurePersondirectoryCreateperson
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of person creation.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonCreationResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Create person in person directory example:
          $ref: ./examples/CreateNewPersonDirectoryPerson.json
      description: Needs a more full description created.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollmentRequest'
        required: true
  /persons/{personId}:
    patch:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Update Name Or Userdata Of A Person
      operationId: microsoftAzurePersondirectoryUpdateperson
      parameters:
      - in: path
        name: personId
        description: Person id to update.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Create person in person directory example:
          $ref: ./examples/UpdatePersonDirectoryPerson.json
      description: Needs a more full description created.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollmentRequest'
        required: true
    delete:
      tags:
      - PersonDirectory
      summary: "Microsoft Azure Delete An Existing Person From Person Directory \nthe Persistedfaceid, Userdata, Person Name And Face Feature S In The Person Entry Will All Be Deleted"
      operationId: microsoftAzurePersondirectoryDeleteperson
      parameters:
      - in: path
        name: personId
        description: Person id to delete.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of person creation.
              schema:
                type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Delete person from person directory example:
          $ref: ./examples/DeletePersonDirectoryPerson.json
      description: Needs a more full description created.
    get:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Retrieve A Person S Name And Userdata, And The Persisted Faceids Representing The Registered Person Face Feature S
      operationId: microsoftAzurePersondirectoryGetperson
      parameters:
      - in: path
        name: personId
        description: Person id.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrolledPerson'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Get person from person directory example:
          $ref: ./examples/GetPersonDirectoryPerson.json
      description: Needs a more full description created.
  /persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces:
    post:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Add A New Face To Person
      operationId: microsoftAzurePersondirectoryAddpersonfacefromurl
      parameters:
      - in: path
        name: personId
        description: Person id.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: recognitionModel
        description: Recognition model string.
        required: true
        schema:
          type: string
      - in: query
        name: detectionModel
        description: Detection model string.
        schema:
          type: string
      - in: query
        name: userData
        description: User data of person face.
        schema:
          type: string
      - in: query
        name: targetFace
        description: Target face.
        schema:
          type: string
      - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of person creation.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrollmentPrintResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Add face to person in person directory example:
          $ref: ./examples/AddPersonDirectoryPersonFaceFromUrl.json
      description: Needs a more full description created.
    get:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Retrieve Person Face Information The Persisted Person Face Is Specified By Its Personid And Persistedfaceid
      operationId: microsoftAzurePersondirectoryGetpersonfaces
      parameters:
      - in: path
        name: personId
        description: Target person to get persistedFaceIds from.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: recognitionModel
        description: The 'recognitionModel' associated with this persisted face.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Get person face in person directory example:
          $ref: ./examples/GetPersonDirectoryPersonFaces.json
      description: Needs a more full description created.
  /persons/{personId}/recognitionModels/{recognitionModel}/persistedFaces/{persistedFaceId}:
    delete:
      tags:
      - PersonDirectory
      summary: "Microsoft Azure Delete An Existing Person Face From Person Directory \nthe Persistedfaceid, Userdata, And Face Feature In The Person Entry Will All Be Deleted"
      operationId: microsoftAzurePersondirectoryDeletepersonface
      parameters:
      - in: path
        name: personId
        description: Person id.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: recognitionModel
        description: Recognition model string.
        required: true
        schema:
          type: string
      - in: path
        name: persistedFaceId
        description: Persisted face id to delete.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of person creation.
              schema:
                type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Delete face from person directory person example:
          $ref: ./examples/DeletePersonDirectoryPersonFace.json
      description: Needs a more full description created.
    get:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Retrieve Person Face Information The Persisted Person Face Is Specified By Its Personid And Persistedfaceid
      operationId: microsoftAzurePersondirectoryGetpersonface
      parameters:
      - in: path
        name: personId
        description: Target person to get face from.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: recognitionModel
        description: The 'recognitionModel' associated with this persisted face.
        required: true
        schema:
          type: string
      - in: path
        name: persistedFaceId
        description: Target person face id to get.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersistedFaceResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Get person directory person face example:
          $ref: ./examples/GetPersonDirectoryPersonFace.json
      description: Needs a more full description created.
    patch:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Update The Data Of A Person Face
      operationId: microsoftAzurePersondirectoryUpdatepersonface
      parameters:
      - in: path
        name: personId
        description: Target person to update face from.
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: recognitionModel
        description: The 'recognitionModel' associated with this persisted face.
        required: true
        schema:
          type: string
      - in: path
        name: persistedFaceId
        description: PersistedFaceId created from Person Face Create
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Update face from person directory person example:
          $ref: ./examples/UpdatePersonDirectoryPersonFace.json
      description: Needs a more full description created.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersistedFaceWithType'
        description: Target person face to update.
        required: true
  /dynamicpersongroups/{dynamicPersonGroupId}:
    put:
      tags:
      - PersonDirectory
      summary: "Microsoft Azure Creates A New Dynamic Person Group With Specified Dynamicpersongroupid, Name, And User Provided Userdata \na Dynamic Person Group Is A Container That References Persons \nafter Creation, Use \"dynamicpersongroup  Update\" To Add Remove Persons Into The Search Space \ndynamicpersongroup And Userdata Will Be Stored On Server Until Dynamicpersongroup Delete Is Called"
      operationId: microsoftAzurePersondirectoryCreatedynamicpersongroup
      parameters:
      - in: path
        name: dynamicPersonGroupId
        description: User provided dynamic person group Id. Valid format should be a string composed by numbers, English letters in lower case, '-', '_', and no longer than 64 characters.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
        '202':
          description: Success
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of person creation.
              schema:
                type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Create dynamic person group example:
          $ref: ./examples/CreateNewDynamicPersonGroup.json
      description: Needs a more full description created.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DynamicPersonGroupCreateRequest'
        required: true
    patch:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Updates An Existing Dynamic Person Group With Specified Dynamicpersongroupid, Name, And User Provided Userdata
      operationId: microsoftAzurePersondirectoryUpdatedynamicpersongroup
      parameters:
      - in: path
        name: dynamicPersonGroupId
        description: User provided dynamic person group Id.
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of person creation.
              schema:
                type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Update dynamic person group example:
          $ref: ./examples/UpdateDynamicPersonGroup.json
      description: Needs a more full description created.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DynamicPersonGroupUpdateRequest'
        required: true
    get:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Get Metadata On A Dynamic Person Group
      operationId: microsoftAzurePersondirectoryGetdynamicpersongroup
      parameters:
      - in: path
        name: dynamicPersonGroupId
        description: User provided dynamic person group id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DynamicPersonGroupGetResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Get dynamic person group example:
          $ref: ./examples/GetDynamicPersonGroup.json
      description: Needs a more full description created.
    delete:
      tags:
      - PersonDirectory
      summary: "Microsoft Azure Delete An Existing Dynamic Person Group \nnote That Persons Are Not Deleted With This Operation To Delete Person Call Person Delete"
      operationId: microsoftAzurePersondirectoryDeletedynamicpersongroup
      parameters:
      - in: path
        name: dynamicPersonGroupId
        description: User provided dynamic person group Id.
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of person creation.
              schema:
                type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        Delete dynamic person group example:
          $ref: ./examples/DeleteDynamicPersonGroup.json
      description: Needs a more full description created.
  /dynamicpersongroups/{dynamicPersonGroupId}/persons:
    get:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Retrieve List Of Persons Referenced In A Given Dynamicpersongroup Person Directory
      operationId: microsoftAzurePersondirectoryListdynamicpersongrouppersons
      parameters:
      - in: path
        name: dynamicPersonGroupId
        description: Dynamic person group Id to list persons from
        required: true
        schema:
          type: string
      - in: query
        name: start
        description: List persons from the least personId greater than the "start". It contains no more than 64 characters. Default is empty.
        schema:
          type: string
          format: uuid
      - in: query
        name: top
        description: The number of persons to list, ranging in [1, 1000]. Default is 1000.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DynamicPersonGroupListPersonsResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        List dynamic person group persons example:
          $ref: ./examples/ListDynamicPersonGroupPersons.json
      description: Needs a more full description created.
  /dynamicpersongroups:
    get:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Retrieve List Of Dynamic Person Groups In Person Directory
      operationId: microsoftAzurePersondirectoryListdynamicpersongroups
      parameters:
      - in: query
        name: start
        description: List dynamicPersonGroupId from the least dynamicPersonGroupId greater than the "start". It contains no more than 64 characters. Default is empty.
        schema:
          type: string
      - in: query
        name: top
        description: The number of dynamicPersonGroups to list, ranging in [1, 1000]. Default is 1000.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DynamicPersonGroupGetResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        List dynamic person groups example:
          $ref: ./examples/ListDynamicPersonGroups.json
      description: Needs a more full description created.
  /persons/{personId}/dynamicPersonGroupReferences:
    get:
      tags:
      - PersonDirectory
      summary: Microsoft Azure List The Dynamic Person Groups That A Person Has Been Referenced In
      operationId: microsoftAzurePersondirectoryListdynamicpersongrouppersonreferences
      parameters:
      - in: path
        name: personId
        description: Valid PersonId created from Person Create.
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: start
        description: List dynamic person group id from the least dynamicPersonGroupId greater than the "start". It contains no more than 64 characters. Default is empty.
        schema:
          type: string
      - in: query
        name: top
        description: The number of dynamicPersonGroupId to list, ranging in [1, 1000]. Default is 1000.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonDynamicPersonGroupReferenceResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-ms-examples:
        List dynamic person group references example:
          $ref: ./examples/ListDynamicPersonGroupReferences.json
      description: Needs a more full description created.
components:
  schemas:
    PersonResponse:
      type: object
      properties:
        personId:
          format: uuid
          type: string
        persistedFaceIds:
          type: array
          items:
            format: uuid
            type: string
        name:
          type: string
        userData:
          type: string
    DynamicPersonGroupUpdateRequest:
      type: object
      properties:
        name:
          type: string
          description: User defined name, maximum length is 128.
        userData:
          type: string
          description: User specified data. Length should not exceed 16KB.
        addPersonIds:
          type: array
          description: Person ids to add to the dynamic person group.
          items:
            format: uuid
            type: string
        removePersonIds:
          type: array
          description: Person ids to remove from the dynamic person group.
          items:
            type: string
    EnrollmentResponse:
      type: object
      properties:
        personId:
          format: uuid
          type: string
        name:
          type: string
        userData:
          type: string
    DynamicPersonGroupCreateRequest:
      type: object
      properties:
        name:
          type: string
          description: User defined name, maximum length is 128.
        userData:
          type: string
          description: User specified data. Length should not exceed 16KB.
        addPersonIds:
          type: array
          description: Person ids to add to the dynamic person group.
          items:
            format: uuid
            type: string
    Error:
      type: object
      description: Error body.
      properties:
        code:
          type: string
        message:
          type: string
    DynamicPersonGroupListPersonsResponse:
      type: object
      properties:
        personIds:
          type: array
          items:
            format: uuid
            type: string
    EnrolledPerson:
      type: object
      properties:
        personId:
          format: uuid
          type: string
          description: Person id.
        name:
          type: string
          description: User defined name, maximum length is 128.
        userData:
          type: string
          description: User specified data. Length should not exceed 16KB.
    DynamicPersonGroupGetResponse:
      type: object
      properties:
        dynamicPersonGroupId:
          type: string
        name:
          type: string
        userData:
          type: string
    PersistedFaceWithType:
      type: object
      properties:
        detectionModel:
          $ref: '#/components/schemas/DetectionModel'
        faceFeature:
          format: byte
          type: string
        persistedFaceId:
          format: uuid
          type: string
        userData:
          type: string
    PersistedFaceResponse:
      type: object
      properties:
        persistedFaceId:
          format: uuid
          type: string
        userData:
          type: string
    EnrollmentRequest:
      type: object
      properties:
        name:
          type: string
          description: User defined name, maximum length is 128.
        userData:
          type: string
          description: User specified data. Length should not exceed 16KB.
    DetectionModel:
      enum:
      - detection_01
      - detection_02
      - detection_03
      - detection_preview_1904
      - ir_detection_01
      - expression_01
      type: string
      description: Detection model used when extracting the face.
    PersonCreationResponse:
      type: object
      properties:
        personId:
          format: uuid
          type: string
    PersonDynamicPersonGroupReferenceResponse:
      type: object
      properties:
        personId:
          format: uuid
          type: string
        dynamicPersonGroupIds:
          type: array
          items:
            type: string
    EnrollmentPrintResponse:
      type: object
      properties:
        persistedFaceId:
          format: uuid
          type: string
        recognitionModel:
          type: string
        userData:
          type: string
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'