openapi: 3.0.3
info:
  title: Verato Person API
  version: 1.0.0
  description: >
    This OpenAPI 3.0 document serves as an **enterprise-level template** for
    REST APIs  published on the Developer Experience Portal and documented with
    Redocly Realm.
  termsOfService: https://example.com/terms-of-service
  contact:
    name: API Support Team
    url: https://developer.example.com/support
    email: api-support@example.com
  license:
    name: Example API License
    url: https://example.com/api-license
  x-logo:
    url: https://example.com/assets/logo.png
    altText: Example Company
    backgroundColor: '#FFFFFF'
    href: https://example.com
security:
  - bearerAuth: []
servers:
  - url: https://sandbox.example.com/{basePath}
    description: Sandbox environment for development and testing.
    variables:
      basePath:
        default: api
        description: Base path for all API endpoints.
  - url: https://api.example.com/{basePath}
    description: Production environment for live integrations.
    variables:
      basePath:
        default: api
        description: Base path for all API endpoints.
tags: []
paths:
  /v2/postIdentity:
    post:
      summary: Add an Identity to the link stack
      description: Used to add a new identity to the link stack
      operationId: postIdentity
      security:
        - bearerAuth: []
      requestBody:
        description: The web service request containing identity data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRequest_postIdentity'
      responses:
        '200':
          description: Successfully added identity to the link stack
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse_postIdentity'
        '400':
          description: Invalid request - malformed identity data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse_postIdentity'
        '500':
          description: Internal server error
  /v2/demographicsSearch:
    post:
      operationId: demographicsSearch
      summary: Search Using Demographic Information
      description: >-
        Search link database using provided demographic information, return
        multiple matches ordered by match score
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRequest_v2_demographicsSearch'
      responses:
        '200':
          description: Successfully searched demographics database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse_v2_demographicsSearch'
        '400':
          description: Bad request - invalid demographic search parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
        '500':
          description: Server error during demographic search
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  retryableError:
                    type: boolean
  /v2/demographicsQuery:
    post:
      operationId: demographicsQuery
      summary: Query Using Demographic Information
      description: >-
        Search link database using provided demographic information to find
        matching identities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRequest_v2DemographicsQuery'
      responses:
        '200':
          description: Successfully queried demographics database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse_v2DemographicsQuery'
        '400':
          description: Bad request - invalid demographics query parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
        '500':
          description: Server error during demographics query
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  retryableError:
                    type: boolean
  /v2/identityIdQuery:
    post:
      summary: Query Using an Id
      description: >-
        Search link database for Identity with supplied ID (linkId or external
        entity ID)
      operationId: queryIdentityById
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceRequest_v2IdentityIdQuery'
            example:
              auditId: audit-123
              customerId: customer-456
              auditLogMap:
                action: query_identity
                timestamp: '2025-12-16T10:30:00Z'
              content:
                linkId: link-789
                includeEnrichData: true
                responseIdentityFormatNames:
                  - DEFAULT
              trackingId: track-101112
      responses:
        '200':
          description: Successful identity query response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse_v2IdentityIdQuery'
              example:
                auditId: audit-123
                success: true
                message: OK
                trackingId: track-101112
                content:
                  linkId: link-789
                  requestedLinkId: link-789
                  identity:
                    names:
                      - firstName: John
                        lastName: Doe
                        middleName: Michael
                    addresses:
                      - line1: 123 Main St
                        city: Springfield
                        state: IL
                        postalCode: '62701'
                    datesOfBirth:
                      - dateOfBirth: '1980-01-15'
                    ssns:
                      - ssn: 123-45-6789
                  identityGroupedBySource:
                    - names:
                        - firstName: John
                          lastName: Doe
                    - vinIds:
                        - vin-001
                        - vin-002
components:
  schemas:
    ServiceRequest_postIdentity:
      type: object
      description: Service request wrapper for post identity operations
      properties:
        auditId:
          type: string
          description: Audit ID for tracking
        customerId:
          type: string
          description: Customer identifier
        auditLogMap:
          type: object
          additionalProperties:
            type: string
          description: Audit log entries
        content:
          $ref: '#/components/schemas/PostIdentityWsRequest'
        trackingId:
          type: string
          description: Tracking ID for the request
      required:
        - customerId
        - content
    ServiceResponse_postIdentity:
      type: object
      description: Service response wrapper for post identity operations
      properties:
        auditId:
          type: string
          description: Audit ID
        success:
          type: boolean
          description: Whether the operation was successful
        unparsedJson:
          type: string
          description: Unparsed JSON if any
        warnings:
          type: array
          items:
            type: string
          description: List of warnings
        retryableError:
          type: boolean
          description: Whether the error is retryable
        message:
          type: string
          description: Response message
        content:
          $ref: '#/components/schemas/PostIdentityWsResponse'
        errors:
          type: array
          items:
            type: string
          description: List of errors
        trackingId:
          type: string
          description: Tracking ID of the request
    ServiceRequest_v2_demographicsSearch:
      description: Wrapper for demographics search request with audit information
      type: object
      properties:
        auditId:
          type: string
          description: Audit identifier for this request
        customerId:
          type: string
          description: Customer ID making the request
        auditLogMap:
          type: object
          additionalProperties:
            type: string
          description: Map of audit log entries
        content:
          $ref: '#/components/schemas/DemographicsSearchWsRequest'
        trackingId:
          type: string
          description: Tracking ID for request correlation
      required:
        - customerId
        - content
    ServiceResponse_v2_demographicsSearch:
      description: >-
        Wrapper for demographics search response with audit and status
        information
      type: object
      properties:
        auditId:
          type: string
          description: Audit identifier for this response
        success:
          type: boolean
          description: Whether the request was successful
        unparsedJson:
          type: string
          nullable: true
          description: Unparsed JSON if parsing failed
        warnings:
          type: array
          description: Warning messages from the service
          items:
            type: string
        retryableError:
          type: boolean
          description: Whether the error is retryable
        message:
          type: string
          nullable: true
          description: Status message
        content:
          $ref: '#/components/schemas/DemographicsSearchWsResponse'
        errors:
          type: array
          description: Error messages if any occurred
          items:
            type: string
        trackingId:
          type: string
          nullable: true
          description: Tracking ID for request correlation
    ServiceRequest_v2DemographicsQuery:
      description: Wrapper for demographics query request with audit information
      type: object
      properties:
        auditId:
          type: string
          description: Audit identifier for this request
        customerId:
          type: string
          description: Customer ID making the request
        auditLogMap:
          type: object
          additionalProperties:
            type: string
          description: Map of audit log entries
        content:
          $ref: '#/components/schemas/DemographicsQueryWsRequest'
        trackingId:
          type: string
          description: Tracking ID for request correlation
      required:
        - customerId
        - content
    ServiceResponse_v2DemographicsQuery:
      description: >-
        Wrapper for demographics query response with audit and status
        information
      type: object
      properties:
        auditId:
          type: string
          description: Audit identifier for this response
        success:
          type: boolean
          description: Whether the request was successful
        unparsedJson:
          type: string
          nullable: true
          description: Unparsed JSON if parsing failed
        warnings:
          type: array
          description: Warning messages from the service
          items:
            type: string
        retryableError:
          type: boolean
          description: Whether the error is retryable
        message:
          type: string
          nullable: true
          description: Status message
        content:
          $ref: '#/components/schemas/DemographicsQueryWsResponse'
        errors:
          type: array
          description: Error messages if any occurred
          items:
            type: string
        trackingId:
          type: string
          nullable: true
          description: Tracking ID for request correlation
    ServiceRequest_v2IdentityIdQuery:
      type: object
      description: Service request wrapper for identity ID query operation
      required:
        - auditId
        - customerId
        - content
      properties:
        auditId:
          $ref: '#/components/schemas/AuditID'
        customerId:
          type: string
          description: Customer identifier
          example: customer-456
        auditLogMap:
          type: object
          description: Audit logging metadata
          additionalProperties:
            type: string
          example:
            action: query_identity
            timestamp: '2025-12-16T10:30:00Z'
        content:
          $ref: '#/components/schemas/IdentityIdQueryWsRequest'
        trackingId:
          type: string
          description: Request tracking identifier
          example: track-101112
    ServiceResponse_v2IdentityIdQuery:
      type: object
      description: Service response wrapper for identity ID query operation
      required:
        - auditId
        - success
      properties:
        auditId:
          $ref: '#/components/schemas/AuditID'
        success:
          type: boolean
          description: Indicates if the request was successful
          example: true
        message:
          type: string
          description: Response message
          example: OK
        unparsedJson:
          type: string
          description: Raw unparsed JSON response, if applicable
        warnings:
          type: array
          description: List of warning messages
          items:
            type: string
          example:
            - Partial data returned
        errors:
          type: array
          description: List of error messages
          items:
            type: string
        retryableError:
          type: boolean
          description: Indicates if the error is retryable
          example: false
        content:
          $ref: '#/components/schemas/IdentityIdQueryWsResponse'
        trackingId:
          type: string
          description: Request tracking identifier
          example: track-101112
    PostIdentityWsRequest:
      type: object
      description: Request to add a new identity to the LINK database
      properties:
        includeEnrichData:
          type: boolean
          default: false
          description: Flag to include enrich data in the response
        identity:
          $ref: '#/components/schemas/Identity'
          description: Identity object containing demographic information
        responseIdentityFormatNames:
          type: array
          uniqueItems: true
          items:
            type: string
          description: >
            A set of values that indicates the different formats of the Identity
            to be sent back in the response. If no values are specified,
            "DEFAULT" is assumed. Valid values: DEFAULT, GROUP_BY_SOURCE,
            CUSTOM_VIEW
      required:
        - identity
    PostIdentityWsResponse:
      type: object
      description: Response containing the identity record after post operation
      properties:
        identityGroupedBySource:
          type: array
          items:
            $ref: '#/components/schemas/IdentityPerSource'
          description: >
            An alternative view of the link identity where information is
            grouped by the source. Present if the Request object contains
            "GROUP_BY_SOURCE" in its identity view names list.
        linkIdentity:
          $ref: '#/components/schemas/Identity'
          description: The link identity as it exists in the link database
        linkId:
          type: string
          nullable: true
          description: LinkId of the returned Identity, if any. Null if no match found
        identity:
          $ref: '#/components/schemas/Identity'
          nullable: true
          description: Found identity, if any. Null if no match found
        domains:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Domain'
          nullable: true
          description: Domains of the returned Identity, if any. Null if none
        customizedIdentitiesWithSource:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/IdentityWithSource'
          description: >
            An alternative view of the link identity where information is
            customized according to the view name along with source information.
            Present if the Request object contains "CUSTOM_VIEW" in its identity
            view names list.
        customizedIdentities:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Identity'
          description: >
            An alternative view of the link identity where information is
            customized according to the view name. Present if the Request object
            contains "CUSTOM_VIEW" in its identity view names list.
        vinIds:
          type: array
          uniqueItems: true
          items:
            type: string
          description: The VIN IDs associated with the identity
        events:
          type: array
          items:
            $ref: '#/components/schemas/PostIdentityWsEvent'
          description: Events related to the post identity operation
        incomingIdentity:
          $ref: '#/components/schemas/Identity'
          description: The identity posted to the LINK stack
        enrichedDetails:
          $ref: '#/components/schemas/EnrichedDetails'
          nullable: true
          description: >-
            Enriched details for an Identity that is augmented from the enrich
            stack
    DemographicsSearchWsRequest:
      description: Request object for demographics query
      type: object
      properties:
        includeEnrichData:
          type: boolean
          default: false
          description: Flag to include enrich data in the response, defaults to false
        identity:
          description: Identity containing demographic search values
          $ref: '#/components/schemas/Identity'
        matchScoreThreshold:
          type: number
          format: double
          description: >-
            Only identities with match scores equal to or above this value will
            appear in the response. If not provided, then no filtering based on
            match score is performed.
        maxSearchResults:
          type: integer
          format: int32
          minimum: 1
          maximum: 100000000
          description: >-
            The number of results to return at one time. Must be greater than 0.
            If not provided, the system's maximum number of results will be
            returned.
        responseIdentityFormatNames:
          type: array
          uniqueItems: true
          description: >-
            A set of values that indicates the different formats of the Identity
            to be sent back in the response. If no values are specified,
            "DEFAULT" is assumed.
          items:
            type: string
      required:
        - identity
    DemographicsSearchWsResponse:
      description: Response object for demographics query
      type: object
      properties:
        searchResults:
          type: array
          description: >-
            A list of search results in order of best to worst match for the
            Identity provided in the request. Empty if no matches were found.
          items:
            $ref: '#/components/schemas/DemographicsSearchResult'
      required:
        - searchResults
    DemographicsSearchResult:
      description: A single search result from demographics search query
      type: object
      properties:
        sameIdentity:
          type: string
          enum:
            - 'Y'
            - 'N'
            - U
          description: >-
            Represents whether or not the Identity is thought to be the same
            identity as provided in the request. Y=Yes, N=No, U=Unknown
        matchScore:
          type: number
          format: double
          minimum: 0
          maximum: 1
          description: >-
            Represents how well the Identity is thought to match the identity
            provided in the request
        linkId:
          type: string
          nullable: true
          description: LinkId of the returned Identity, if any. Null if no match found
        identity:
          nullable: true
          description: Found identity, if any. Null if no match found
          $ref: '#/components/schemas/Identity'
        identityGroupedBySource:
          type: array
          nullable: true
          description: >-
            An alternative view of the link identity where information is
            grouped by the source. Present if the Request object contains
            "GROUP_BY_SOURCE" in its identity view names list.
          items:
            $ref: '#/components/schemas/IdentityPerSource'
        domains:
          type: array
          uniqueItems: true
          nullable: true
          description: Domains of the returned Identity, if any. Null if none
          items:
            type: string
        customizedIdentitiesWithSource:
          type: object
          nullable: true
          additionalProperties:
            $ref: '#/components/schemas/IdentityWithSource'
          description: >-
            An alternative view of the link identity where information is
            customized according to the view name along with source information.
        customizedIdentities:
          type: object
          nullable: true
          additionalProperties:
            $ref: '#/components/schemas/Identity'
          description: >-
            An alternative view of the link identity where information is
            customized according to the view name.
        vinIds:
          type: array
          uniqueItems: true
          nullable: true
          description: The VIN IDs associated with the identity
          items:
            type: string
        enrichedDetails:
          nullable: true
          description: >-
            Enriched details for an Identity that is augmented from the enrich
            stack
          $ref: '#/components/schemas/EnrichedDetails'
      required:
        - sameIdentity
        - matchScore
    DemographicsQueryWsRequest:
      description: Request object for demographics query
      type: object
      properties:
        includeEnrichData:
          type: boolean
          default: false
          description: Flag to include enrich data in the response, defaults to false
        identity:
          description: Identity containing demographic search values
          $ref: '#/components/schemas/Identity'
        responseIdentityFormatNames:
          type: array
          uniqueItems: true
          description: >-
            A set of values that indicates the different formats of the Identity
            to be sent back in the response. If no values are specified,
            "DEFAULT" is assumed.
          items:
            type: string
      required:
        - identity
    DemographicsQueryWsResponse:
      description: Response object for demographics query
      type: object
      properties:
        identityGroupedBySource:
          type: array
          nullable: true
          description: >-
            An alternative view of the link identity where information is
            grouped by the source. Present if the Request object contains
            "GROUP_BY_SOURCE" in its identity view names list.
          items:
            $ref: '#/components/schemas/IdentityPerSource'
        linkId:
          type: string
          nullable: true
          description: LinkId of the returned Identity, if any. Null if no match found
        identity:
          nullable: true
          description: Found identity, if any. Null if no match found
          $ref: '#/components/schemas/Identity'
        domains:
          type: array
          uniqueItems: true
          nullable: true
          description: Domains of the returned Identity, if any. Null if none
          items:
            type: string
        customizedIdentitiesWithSource:
          type: object
          nullable: true
          additionalProperties:
            $ref: '#/components/schemas/IdentityWithSource'
          description: >-
            An alternative view of the link identity where information is
            customized according to the view name along with source information.
        customizedIdentities:
          type: object
          nullable: true
          additionalProperties:
            $ref: '#/components/schemas/Identity'
          description: >-
            An alternative view of the link identity where information is
            customized according to the view name.
        vinIds:
          type: array
          uniqueItems: true
          nullable: true
          description: The VIN IDs associated with the identity
          items:
            type: string
        enrichedDetails:
          nullable: true
          description: >-
            Enriched details for an Identity that is augmented from the enrich
            stack
          $ref: '#/components/schemas/EnrichedDetails'
    IdentityIdQueryWsRequest:
      type: object
      description: Request object used to query by LinkId or external entity Id
      required:
        - linkId
      properties:
        linkId:
          type: string
          description: The id to query for
          example: link-789
        includeEnrichData:
          type: boolean
          description: Flag to include enrich data in the response, defaults to false
          example: true
        addVeratoReferenceToEntity:
          type: boolean
          description: >-
            Flag to include verato reference data with the entity in the
            response
          example: false
        responseIdentityFormatNames:
          type: array
          description: >-
            A set of values that indicates the different formats of the Identity
            to be sent back in the response. If no values are specified,
            "DEFAULT" is assumed.
          uniqueItems: true
          items:
            type: string
          example:
            - DEFAULT
            - GROUP_BY_SOURCE
    IdentityIdQueryWsResponse:
      type: object
      description: Response object for query by linkId
      properties:
        linkId:
          type: string
          nullable: true
          description: >-
            The linkId of the returned Identity. May differ from requested
            LinkId for Identities that have been merged
          example: link-789
        requestedLinkId:
          type: string
          description: The linkId used in the original query
          example: link-789
        identity:
          $ref: '#/components/schemas/Identity'
          description: Found identity, if any. Null if no match found
        identityGroupedBySource:
          type: array
          description: >-
            An alternative view of the link identity where information is
            grouped by the source. Present if the Request object contains
            "GROUP_BY_SOURCE" in its identity view names list.
          items:
            $ref: '#/components/schemas/IdentityPerSource'
        customizedIdentities:
          type: object
          description: >-
            An alternative view of the link identity where information is
            customized according to the view name. Present if the Request object
            contains "CUSTOM_VIEW" in its identity view names list.
          additionalProperties:
            $ref: '#/components/schemas/Identity'
        customizedIdentitiesWithSource:
          type: object
          description: >-
            An alternative view of the link identity where information is
            customized according to the view name along with source information.
            Present if the Request object contains "CUSTOM_VIEW" in its identity
            view names list.
          additionalProperties:
            $ref: '#/components/schemas/IdentityWithSource'
        domains:
          type: array
          description: Domains of the returned Identity, if any. Null if none
          uniqueItems: true
          items:
            $ref: '#/components/schemas/Domain'
        vinIds:
          type: array
          description: The VIN IDs associated with the identity
          uniqueItems: true
          items:
            type: string
          example:
            - vin-001
            - vin-002
        enrichedDetails:
          $ref: '#/components/schemas/EnrichedDetails'
          nullable: true
          description: >-
            Enriched details for an Identity that is augmented from the enrich
            stack
    Identity:
      type: object
      description: API object representing a patient or entity identity
      properties:
        names:
          type: array
          items:
            $ref: '#/components/schemas/Name'
          description: Array of names for this identity
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          description: Array of addresses for this identity
        datesOfBirth:
          type: array
          items:
            $ref: '#/components/schemas/DateOfBirth'
          description: Array of birth dates for this identity
        ssns:
          type: array
          items:
            $ref: '#/components/schemas/SSN'
          description: Array of social security numbers
        genders:
          type: array
          items:
            $ref: '#/components/schemas/Gender'
          description: Array of gender information
        phoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/Phone'
          description: Array of phone numbers
        emails:
          type: array
          items:
            $ref: '#/components/schemas/Email'
          description: Array of email addresses
        deathDetails:
          type: array
          items:
            $ref: '#/components/schemas/DeathDetails'
          description: Death information if applicable
    Name:
      type: object
      description: Personal name information
      properties:
        prefix:
          type: string
          description: Name prefix (e.g., Dr., Mr., Ms.)
        firstName:
          type: string
          description: First name
        middleName:
          type: string
          description: Middle name
        lastName:
          type: string
          description: Last name
        suffix:
          type: string
          description: Name suffix (e.g., Jr., Sr., Ph.D.)
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
          description: Sources where this name was found
        clusterStatus:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: Status of this clustered attribute
    Address:
      type: object
      description: Physical address
      properties:
        type:
          type: string
          description: Type of address (e.g., HOME, WORK)
        line1:
          type: string
          description: First line of address
        line2:
          type: string
          description: Second line of address
        city:
          type: string
          description: City name
        state:
          type: string
          description: State or province
        postalCode:
          type: string
          description: Postal or ZIP code
        country:
          type: string
          description: Country name
        latitude:
          type: number
          format: double
          description: Latitude coordinate
        longitude:
          type: number
          format: double
          description: Longitude coordinate
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
          description: Sources where this address was found
        clusterStatus:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: Status of this clustered attribute
    SSN:
      type: object
      description: Social Security Number information
      properties:
        ssn:
          type: string
          description: Social Security Number (typically masked or encrypted)
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
          description: Sources where this SSN was found
        clusterStatus:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: Status of this clustered attribute
    Source:
      type: object
      description: Information about the source system where data originated
      properties:
        sourceId:
          type: string
          description: Unique identifier for the source system
        sourceName:
          type: string
          description: Name of the source system
        displayName:
          type: string
          description: Display name for the source
        nativeId:
          type: string
          description: Native identifier in the source system
    DateOfBirth:
      type: object
      description: Date of birth information
      properties:
        dateOfBirth:
          type: string
          format: date
          description: The date of birth
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
          description: Sources where this date was found
        clusterStatus:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: Current status of this clustered attribute
    Gender:
      type: object
      description: Gender information
      properties:
        gender:
          type: string
          description: Gender value (e.g., M, F, Other)
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
          description: Sources where this gender was found
        clusterStatus:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: Current status of this clustered attribute
    Phone:
      type: object
      description: Telephone number information
      properties:
        countryCode:
          type: string
          description: Country code for the phone number
        number:
          type: string
          description: The phone number
        extension:
          type: string
          description: Phone extension if applicable
        type:
          type: string
          description: Type of phone (e.g., MOBILE, HOME, WORK)
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
          description: Sources where this phone was found
        clusterStatus:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: Status of this clustered attribute
    Email:
      type: object
      description: Email address information
      properties:
        email:
          type: string
          format: email
          description: The email address
        type:
          type: string
          description: Type of email (e.g., PERSONAL, WORK)
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
          description: Sources where this email was found
        clusterStatus:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: Status of this clustered attribute
    DeathDetails:
      type: object
      description: Information about death status
      properties:
        deathIndicator:
          type: boolean
          description: Whether the individual is deceased
        deathDate:
          type: string
          format: date
          description: Date of death if applicable
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
          description: Sources where this information was found
        clusterStatus:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: Status of this clustered attribute
    AuditID:
      type: object
      description: Audit identifier for tracking
      properties:
        auditId:
          type: string
          description: Unique audit identifier
          example: audit-123
    IdentityPerSource:
      type: object
      description: Identity information grouped by source
      additionalProperties: true
    Domain:
      type: object
      description: Domain classification
      properties:
        id:
          type: string
        name:
          type: string
    IdentityWithSource:
      type: object
      description: Identity with source information
      additionalProperties: true
    PostIdentityWsEvent:
      type: object
      description: Event related to post identity operation
      additionalProperties: true
    EnrichedDetails:
      type: object
      description: Enriched details for an identity
      additionalProperties: true
    Error:
      type: object
      description: >
        Standard error envelope returned by this API. Use this schema
        consistently across all endpoints for predictable error handling.
      properties:
        code:
          type: string
          description: Application-specific error code (machine-readable).
          example: RESOURCE_NOT_FOUND
        message:
          type: string
          description: Human-readable explanation of the error.
          example: The requested resource could not be found.
        correlationId:
          type: string
          description: >
            ID used to correlate this request across distributed systems.
            Propagate the value from the `X-Correlation-Id` request header if
            present.
          example: 7c3e2f71-2a7f-4d58-9d1f-9c382f0ea2b0
        details:
          type: object
          description: Optional structured information with error-specific details.
          additionalProperties: true
      required:
        - code
        - message
        - correlationId
    HealthStatus:
      type: object
      description: >-
        Health check response indicating the status of the API and its
        dependencies.
      properties:
        status:
          type: string
          description: Overall health status.
          enum:
            - UP
            - DEGRADED
            - DOWN
        timestamp:
          type: string
          format: date-time
          description: UTC timestamp at which the health was evaluated.
        components:
          type: object
          description: Component-level health information keyed by component name.
          additionalProperties:
            type: object
            properties:
              status:
                type: string
                description: Component health status.
                enum:
                  - UP
                  - DEGRADED
                  - DOWN
              details:
                type: object
                description: Optional component-specific diagnostic information.
                additionalProperties: true
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: HTTP Bearer token authentication (JWT)
    clientCertificateAuth:
      type: apiKey
      in: header
      name: X-Client-Cert-Thumbprint
      description: Client certificate-based authentication (mutual TLS)
  parameters:
    CorrelationIdHeader:
      name: X-Correlation-Id
      in: header
      description: >
        Optional correlation ID for tracking requests across distributed
        systems. If not provided by the client, the platform may generate a new
        value.
      required: false
      schema:
        type: string
        maxLength: 128
    AcceptLanguageHeader:
      name: Accept-Language
      in: header
      description: >
        Optional language preference for localized content, using IETF BCP 47
        language tags (for example, `en-US` or `fr-FR`).
      required: false
      schema:
        type: string
