openapi: 3.1.0
info:
  title: Credentially Public Compliance-packages References API
  description: Public API Proxy with Rate Limiting and Audit
  version: 2.0.0
servers:
- url: https://app.credentially.io/gateway
  description: Generated server url
tags:
- name: References
  description: Profile reference status lookup endpoints
paths:
  /api/profile/{profileId}/references:
    get:
      tags:
      - References
      summary: Get Profile References
      description: 'Returns reference titles, employment dates, durations, and status for the requested profile.


        **Rate Limit:** `profile-references` (100 req / 1s)'
      operationId: getProfileReferences
      parameters:
      - name: profileId
        in: path
        description: Credentially profile ID.
        required: true
        schema:
          type: string
        example: profile-123
      - name: X-API-Version
        in: header
        schema:
          type: string
          default: 2.0.0
          enum:
          - 2.0.0
      responses:
        '200':
          description: References retrieved
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProfileReferencesDto'
              examples:
                references:
                  description: references
                  value:
                    profileId: profile-123
                    status: OK
                    references:
                    - id: reference-123
                      title: Employment reference
                      startDate: '2023-01-01'
                      endDate: '2025-12-31'
                      currentEmployment: false
                      durationDays: 1095
                      status: OK
                      sourceStatus: APPROVED
                      expiryDate: '2026-12-31'
                      referee:
                        fullName: Alex Johnson
                        email: alex.johnson@example.com
                        phone: '+441234567890'
        '404':
          description: Profile not found in the authenticated organisation context
        '500':
          description: Internal server error
        '429':
          description: Too many requests - the rate limit for this endpoint has been exceeded. Use the Retry-After header to determine when to retry.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              schema:
                type: integer
                format: int32
                example: 1
      security:
      - bearer-key: []
components:
  schemas:
    ProfileReferencesDto:
      type: object
      description: Reference status summary for a profile.
      properties:
        profileId:
          type: string
          description: Credentially profile identifier.
          example: profile-123
        status:
          type: string
          description: Normalised status across the profile references.
          enum:
          - OK
          - EXPIRED
          - MISSING
          example: OK
        references:
          type: array
          description: References for the profile.
          items:
            $ref: '#/components/schemas/ProfileReferenceDto'
    RefereeDto:
      type: object
      description: Referee contact details for a profile reference.
      properties:
        fullName:
          type: string
          description: Referee full name.
          example: Alex Johnson
        email:
          type: string
          description: Referee email address.
          example: alex.johnson@example.com
        phone:
          type: string
          description: Referee phone number.
          example: '+441234567890'
    ProfileReferenceDto:
      type: object
      description: Reference summary for a profile.
      properties:
        id:
          type: string
          description: Credentially reference identifier.
          example: reference-123
        title:
          type: string
          description: Reference title.
          example: Employment reference
        startDate:
          type: string
          format: date
          description: Reference start date.
          example: '2023-01-01'
        endDate:
          type: string
          format: date
          description: Reference end date.
          example: '2025-12-31'
        currentEmployment:
          type: boolean
          description: Whether the reference describes current employment.
          example: false
        durationDays:
          type: integer
          format: int64
          description: Reference duration in calendar days.
          example: 1095
        status:
          type: string
          description: Normalised reference status.
          enum:
          - OK
          - EXPIRED
          - MISSING
          example: OK
        sourceStatus:
          type: string
          description: Current Credentially reference status.
          example: APPROVED
        expiryDate:
          type: string
          format: date
          description: Reference expiry date, when configured.
          example: '2026-12-31'
        referee:
          $ref: '#/components/schemas/RefereeDto'
          description: Referee contact details.
  securitySchemes:
    bearer-key:
      type: http
      scheme: bearer
      bearerFormat: JWT