Microsoft Azure PersonDirectory API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector PersonDirectory API
schemes:
- https
tags:
- name: PersonDirectory
paths:
  /persons:
    get:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Retrieve List Of Person Information In Person Directory
      operationId: microsoftAzurePersondirectoryGetpersons
      produces:
      - application/json
      parameters:
      - in: query
        name: start
        format: uuid
        description: List persons from the least personId greater than the "start". It contains no more than 64 characters. Default is empty.
        type: string
      - in: query
        name: top
        description: The number of persons to list, ranging in [1, 1000]. Default is 1000.
        type: string
      responses:
        '200':
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/EnrollmentResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/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
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: body
        name: body
        required: true
        x-ms-client-flatten: true
        schema:
          $ref: '#/definitions/EnrollmentRequest'
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of person creation.
              type: string
          schema:
            $ref: '#/definitions/PersonCreationResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Create person in person directory example:
          $ref: ./examples/CreateNewPersonDirectoryPerson.json
      description: Needs a more full description created.
  /persons/{personId}:
    patch:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Update Name Or Userdata Of A Person
      operationId: microsoftAzurePersondirectoryUpdateperson
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: path
        name: personId
        description: Person id to update.
        required: true
        format: uuid
        type: string
      - in: body
        name: body
        required: true
        x-ms-client-flatten: true
        schema:
          $ref: '#/definitions/EnrollmentRequest'
      responses:
        '200':
          description: Success
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Create person in person directory example:
          $ref: ./examples/UpdatePersonDirectoryPerson.json
      description: Needs a more full description created.
    delete:
      tags:
      - PersonDirectory
      summary: "Microsoft Azure Delete An Existing Person From Person Directory \r\nthe Persistedfaceid, Userdata, Person Name And Face Feature S In The Person Entry Will All Be Deleted"
      operationId: microsoftAzurePersondirectoryDeleteperson
      produces:
      - application/json
      parameters:
      - in: path
        name: personId
        description: Person id to delete.
        required: true
        format: uuid
        type: string
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of person creation.
              type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/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
      produces:
      - application/json
      parameters:
      - in: path
        name: personId
        description: Person id.
        required: true
        format: uuid
        type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/EnrolledPerson'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/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
      produces:
      - application/json
      parameters:
      - in: path
        name: personId
        description: Person id.
        required: true
        format: uuid
        type: string
      - in: path
        name: recognitionModel
        description: Recognition model string.
        required: true
        type: string
      - in: query
        name: detectionModel
        description: Detection model string.
        type: string
      - in: query
        name: userData
        description: User data of person face.
        type: string
      - in: query
        name: targetFace
        description: Target face.
        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.
              type: string
          schema:
            $ref: '#/definitions/EnrollmentPrintResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/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
      produces:
      - application/json
      parameters:
      - in: path
        name: personId
        description: Target person to get persistedFaceIds from.
        required: true
        format: uuid
        type: string
      - in: path
        name: recognitionModel
        description: The 'recognitionModel' associated with this persisted face.
        required: true
        type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/PersonResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/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 \r\nthe Persistedfaceid, Userdata, And Face Feature In The Person Entry Will All Be Deleted"
      operationId: microsoftAzurePersondirectoryDeletepersonface
      produces:
      - application/json
      parameters:
      - in: path
        name: personId
        description: Person id.
        required: true
        format: uuid
        type: string
      - in: path
        name: recognitionModel
        description: Recognition model string.
        required: true
        type: string
      - in: path
        name: persistedFaceId
        description: Persisted face id to delete.
        required: true
        format: uuid
        type: string
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of person creation.
              type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/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
      produces:
      - application/json
      parameters:
      - in: path
        name: personId
        description: Target person to get face from.
        required: true
        format: uuid
        type: string
      - in: path
        name: recognitionModel
        description: The 'recognitionModel' associated with this persisted face.
        required: true
        type: string
      - in: path
        name: persistedFaceId
        description: Target person face id to get.
        required: true
        format: uuid
        type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/PersistedFaceResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/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
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: path
        name: personId
        description: Target person to update face from.
        required: true
        format: uuid
        type: string
      - in: path
        name: recognitionModel
        description: The 'recognitionModel' associated with this persisted face.
        required: true
        type: string
      - in: path
        name: persistedFaceId
        description: PersistedFaceId created from Person Face Create
        required: true
        format: uuid
        type: string
      - in: body
        name: body
        description: Target person face to update.
        required: true
        x-ms-client-flatten: true
        schema:
          $ref: '#/definitions/PersistedFaceWithType'
      responses:
        '200':
          description: Success
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Update face from person directory person example:
          $ref: ./examples/UpdatePersonDirectoryPersonFace.json
      description: Needs a more full description created.
  /dynamicpersongroups/{dynamicPersonGroupId}:
    put:
      tags:
      - PersonDirectory
      summary: "Microsoft Azure Creates A New Dynamic Person Group With Specified Dynamicpersongroupid, Name, And User Provided Userdata \r\na Dynamic Person Group Is A Container That References Persons \r\nafter Creation, Use \"dynamicpersongroup  Update\" To Add Remove Persons Into The Search Space \r\ndynamicpersongroup And Userdata Will Be Stored On Server Until Dynamicpersongroup Delete Is Called"
      operationId: microsoftAzurePersondirectoryCreatedynamicpersongroup
      consumes:
      - application/json
      produces:
      - application/json
      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
        type: string
      - in: body
        name: body
        description: ''
        required: true
        x-ms-client-flatten: true
        schema:
          $ref: '#/definitions/DynamicPersonGroupCreateRequest'
      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.
              type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Create dynamic person group example:
          $ref: ./examples/CreateNewDynamicPersonGroup.json
      description: Needs a more full description created.
    patch:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Updates An Existing Dynamic Person Group With Specified Dynamicpersongroupid, Name, And User Provided Userdata
      operationId: microsoftAzurePersondirectoryUpdatedynamicpersongroup
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - in: path
        name: dynamicPersonGroupId
        description: User provided dynamic person group Id.
        required: true
        type: string
      - in: body
        name: body
        description: ''
        required: true
        x-ms-client-flatten: true
        schema:
          $ref: '#/definitions/DynamicPersonGroupUpdateRequest'
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of person creation.
              type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        Update dynamic person group example:
          $ref: ./examples/UpdateDynamicPersonGroup.json
      description: Needs a more full description created.
    get:
      tags:
      - PersonDirectory
      summary: Microsoft Azure Get Metadata On A Dynamic Person Group
      operationId: microsoftAzurePersondirectoryGetdynamicpersongroup
      produces:
      - application/json
      parameters:
      - in: path
        name: dynamicPersonGroupId
        description: User provided dynamic person group id
        required: true
        type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/DynamicPersonGroupGetResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/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 \r\nnote That Persons Are Not Deleted With This Operation To Delete Person Call Person Delete"
      operationId: microsoftAzurePersondirectoryDeletedynamicpersongroup
      produces:
      - application/json
      parameters:
      - in: path
        name: dynamicPersonGroupId
        description: User provided dynamic person group Id.
        required: true
        type: string
      responses:
        '202':
          description: Success
          headers:
            Operation-Location:
              description: Operation location with an operation id used to track the progress of person creation.
              type: string
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/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
      produces:
      - application/json
      parameters:
      - in: path
        name: dynamicPersonGroupId
        description: Dynamic person group Id to list persons from
        required: true
        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.
        format: uuid
        type: string
      - in: query
        name: top
        description: The number of persons to list, ranging in [1, 1000]. Default is 1000.
        type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/DynamicPersonGroupListPersonsResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/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
      produces:
      - application/json
      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.
        type: string
      - in: query
        name: top
        description: The number of dynamicPersonGroups to list, ranging in [1, 1000]. Default is 1000.
        type: string
      responses:
        '200':
          description: Success
          schema:
            type: array
            items:
              $ref: '#/definitions/DynamicPersonGroupGetResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/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
      produces:
      - application/json
      parameters:
      - in: path
        name: personId
        description: Valid PersonId created from Person Create.
        required: true
        format: uuid
        type: string
      - 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.
        type: string
      - in: query
        name: top
        description: The number of dynamicPersonGroupId to list, ranging in [1, 1000]. Default is 1000.
        type: string
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/PersonDynamicPersonGroupReferenceResponse'
        default:
          description: Response entity accompanying non-successful responses containing additional details about the error.
          schema:
            $ref: '#/definitions/Error'
      x-ms-examples:
        List dynamic person group references example:
          $ref: ./examples/ListDynamicPersonGroupReferences.json
      description: Needs a more full description created.
definitions:
  PersonCreationResponse:
    type: object
    properties:
      personId:
        format: uuid
        type: string
        x-nullable: false
  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.
  PersonDynamicPersonGroupReferenceResponse:
    type: object
    properties:
      personId:
        format: uuid
        type: string
        x-nullable: false
      dynamicPersonGroupIds:
        type: array
        items:
          type: string
  EnrollmentResponse:
    type: object
    properties:
      personId:
        format: uuid
        type: string
        x-nullable: false
      name:
        type: string
      userData:
        type: string
  DynamicPersonGroupListPersonsResponse:
    type: object
    properties:
      personIds:
        type: array
        items:
          format: uuid
          type: string
          x-nullable: false
  DynamicPersonGroupGetResponse:
    type: object
    properties:
      dynamicPersonGroupId:
        type: string
      name:
        type: string
      userData:
        type: string
  PersonResponse:
    type: object
    properties:
      personId:
        format: uuid
        type: string
        x-nullable: false
      persistedFaceIds:
        type: array
        items:
          format: uuid
          type: string
          x-nullable: false
      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
          x-nullable: false
  EnrolledPerson:
    type: object
    properties:
      personId:
        format: uuid
        type: string
        description: Person id.
        x-nullable: false
      name:
        type: string
        description: User defined name, maximum length is 128.
      userData:
        type: string
        description: User specified data. Length should not exceed 16KB.
  PersistedFaceWithType:
    type: object
    properties:
      detectionModel:
        $ref: '#/definitions/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
  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
          x-nullable: false
      removePersonIds:
        type: array
        description: Person ids to remove from the dynamic person group.
        items:
          type: string
  EnrollmentPrintResponse:
    type: object
    properties:
      persistedFaceId:
        format: uuid
        type: string
        x-nullable: false
      recognitionModel:
        type: string
      userData:
        type: string
  Error:
    type: object
    description: Error body.
    properties:
      code:
        type: string
      message:
        type: string
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'