Microsoft Azure PersonDirectory API

openapi: 3.2.0
info:
  version: 1.0-preview
  title: Microsoft Azure Face Client Person Directory API
  description: An API for face detection, verification, and identification.
security:
- apim_key: []
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 the…
      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…
      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…
      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 the…
      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…
      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…
      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…
      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 note That Persons Are…
      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…
      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…
      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:
    DynamicPersonGroupListPersonsResponse:
      type: object
      properties:
        personIds:
          type: array
          items:
            format: uuid
            type: string
    PersonResponse:
      type: object
      properties:
        personId:
          format: uuid
          type: string
        persistedFaceIds:
          type: array
          items:
            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
    EnrollmentResponse:
      type: object
      properties:
        personId:
          format: uuid
          type: string
        name:
          type: string
        userData:
          type: string
    DynamicPersonGroupGetResponse:
      type: object
      properties:
        dynamicPersonGroupId:
          type: string
        name:
          type: string
        userData:
          type: string
    PersistedFaceResponse:
      type: object
      properties:
        persistedFaceId:
          format: uuid
          type: string
        userData:
          type: string
    PersonDynamicPersonGroupReferenceResponse:
      type: object
      properties:
        personId:
          format: uuid
          type: string
        dynamicPersonGroupIds:
          type: array
          items:
            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.
    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.
    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
    PersistedFaceWithType:
      type: object
      properties:
        detectionModel:
          $ref: '#/components/schemas/DetectionModel'
        faceFeature:
          format: byte
          type: string
        persistedFaceId:
          format: uuid
          type: string
        userData:
          type: string
    PersonCreationResponse:
      type: object
      properties:
        personId:
          format: uuid
          type: string
    EnrollmentPrintResponse:
      type: object
      properties:
        persistedFaceId:
          format: uuid
          type: string
        recognitionModel:
          type: string
        userData:
          type: string
  securitySchemes:
    apim_key:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
x-ms-parameterized-host:
  hostTemplate: '{Endpoint}/face/v1.0-preview'
  useSchemePrefix: false
  parameters:


# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-azure/refs/heads/main/openapi/microsoft-azure-persondirectory-api-openapi.yml