openapi: 3.0.3
info:
  title: Talent Catalog API
  description: >
    The Talent Catalog (TC) is a purpose-built platform designed to connect
    skilled displaced 

    populations with international job opportunities and refugee-focused support
    services.


    The Talent Catalog API allows third-party systems to connect to the TC
    platform.


    ### Key Features

    The Talent Catalog API offers the following capabilities:

    - **Search Candidate Profiles**: Retrieve anonymised candidate data from the
    TC database.

    - **Filter Search Results**: Find candidates based on various criteria (e.g.
    location, 

    occupation, or nationality).

    - **Post Job Matches**: Match candidate profiles with relevant employment
    opportunities.

    - **Post Service Matches**: Connect candidate profiles with appropriate
    support services.

    - **Register Candidates**: Add new candidate registrations directly to the
    TC database.


    ### Authentication

    The Talent Catalog API uses API Key Authentication.


    Each request must include an `X-API-Key` header with your API key.


    ### Getting Started

    - Contact us to register for an API key.

    - Use the endpoints below to interact with the API.
  version: 1.0.0
  contact:
    name: Talent Catalog API Support
    url: https://github.com/Talent-Catalog/tc-api-spec
    email: api@talentcatalog.net
  license:
    name: Gnu Affero General Public License
    url: https://www.gnu.org/licenses/agpl-3.0.html
  x-logo:
    url: ./assets/tc-logo.png
    altText: Talent Catalog logo
tags:
  - name: Candidates
    description: Operations related to anonymised candidates.
servers:
  - url: https://test.api.tctalent.org
    description: Staging server
  - url: https://api.tctalent.org
    description: Production server
paths:
  /v1/candidates:
    get:
      summary: Retrieve a page of anonymised candidates
      description: >-
        Fetches a paginated array of anonymised candidates. Optionally filter
        candidates by their ISCO (International Standard Classification of
        Occupations) codes.
      tags:
        - Candidates
      operationId: findCandidates
      parameters:
        - name: page
          in: query
          description: The page number for pagination
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: limit
          in: query
          description: The number of results per page
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
        - name: location
          in: query
          description: >-
            A list of ISO 3166-1 alpha-2 location codes to filter candidates by
            their current location. Provide one or more ISO codes as a
            comma-separated list (e.g., `US,GB`).
          required: false
          schema:
            type: string
            example: US,GB
        - name: nationality
          in: query
          description: >-
            A list of ISO 3166-1 alpha-2 nationality codes to filter candidates
            by their nationality. Provide one or more ISO codes as a
            comma-separated list (e.g., `FR,DE`).
          required: false
          schema:
            type: string
            example: FR,DE
        - name: occupation
          in: query
          description: >-
            A list of ISCO codes to filter candidates by their occupations.
            Provide one or more ISCO codes as a comma-separated list (e.g.,
            `1234,5678`).
          required: false
          schema:
            type: string
            example: 1234,5678
        - name: includeEmployed
          in: query
          description: >-
            Flag to include candidate profiles with an "employed" status in the
            results. Defaults to false.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: A page of anonymised candidates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidatePage'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestParamError'
        '401':
          description: Unauthorised
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorisedError'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
  /v1/candidates/{publicId}:
    get:
      summary: Retrieve an anonymised candidate by candidate public ID
      description: >-
        Fetches details of an anonymised candidate by their unique public
        candidate ID.
      tags:
        - Candidates
      operationId: getCandidateByPublicId
      parameters:
        - name: publicId
          in: path
          required: true
          description: Unique public ID of the candidate to retrieve
          schema:
            type: string
            format: base64-uuid
            example: ABcd2EFgHIjkLMNOp3QR-S
      responses:
        '200':
          description: An anonymised candidate's details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Candidate'
        '204':
          description: No content - No candidates available for the requested page
        '400':
          description: Bad request - Invalid candidate ID
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestParamError'
        '401':
          description: Unauthorised - Access token is missing or invalid
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorisedError'
        '404':
          description: Not found - Candidate not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
  /v1/candidates/by-list/{publicListId}:
    get:
      summary: Retrieve a page of anonymised candidates in a saved list
      description: >-
        Fetches a paginated array of anonymised candidates belonging to a
        specific saved list, identified by its public ID.
      tags:
        - Candidates
      operationId: getCandidatesByPublicListId
      parameters:
        - name: publicListId
          in: path
          required: true
          description: The public ID of the saved list
          schema:
            type: string
        - name: page
          in: query
          description: The page number for pagination
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: limit
          in: query
          description: The number of results per page
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: A page of anonymised candidates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidatePage'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestParamError'
        '401':
          description: Unauthorised
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorisedError'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
  /v1/candidates/job-match:
    post:
      summary: Expression of interest in candidates for a job
      description: >-
        Allows prospective employers or recruiters to indicate that one or more
        candidates look like they match the requirements of a job, and that they
        are interested in proceeding further with those candidates.
      tags:
        - Candidates
      operationId: jobMatch
      requestBody:
        description: >-
          Information about the prospective employer or recruiter who has the
          job
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                candidates:
                  type: array
                  description: A list of candidate public IDs.
                  items:
                    type: object
                    properties:
                      publicId:
                        type: string
                        format: base64-uuid
                        description: The unique public ID of the candidate.
                        example: ABcd2EFgHIjkLMNOp3QR-S
                additionalNotes:
                  type: string
                  description: >-
                    Optional additional notes provided by the employer or
                    recruiter
                  example: >-
                    Candidates' experience aligns with our job requirements. We
                    would like to arrange interviews at the earliest
                    convenience.
      responses:
        '201':
          description: >-
            Successfully expressed interest in matching the candidates to the
            job
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Success message
                    example: Your interest has been successfully recorded.
                  jobMatchId:
                    type: string
                    description: The unique ID for the job match record
                    example: job-match-7890
        '400':
          description: Bad request - Invalid request payload or candidate ID
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestBodyError'
        '401':
          description: Unauthorised - Access token is missing or invalid
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorisedError'
        '403':
          description: Forbidden - You do not have permission to job match
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Not found - Candidate(s) not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
  /v1/candidates/offer-to-assist:
    post:
      summary: Offer to assist candidates
      description: >-
        Allows candidate service providers to offer assistance to one or more
        candidates. For example, to invite eligible candidate's to access
        specialised services for education, migration or settlement support.
      tags:
        - Candidates
      operationId: offerToAssistCandidates
      requestBody:
        description: >-
          Information about the prospective employer, recruiter or candidate
          service provider expressing interest in the candidate
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                candidates:
                  type: array
                  description: A list of candidate public IDs and optional coupon codes.
                  items:
                    $ref: '#/components/schemas/CandidateCoupon'
                reason:
                  type: string
                  description: The reason for expressing interest in the candidate
                  allOf:
                    - $ref: '#/components/schemas/candidate_assistance_type'
                  example: EDUCATION_SERVICE
                additionalNotes:
                  type: string
                  description: >-
                    Optional additional notes provided by the candidate service
                    provider
                  example: We would like to provide our services to these candidates.
      responses:
        '201':
          description: Successfully expressed interest in the candidate
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Success message
                    example: Your offer has been successfully recorded.
                  offerId:
                    type: string
                    description: The unique ID for the offer to assist record
                    example: interest-7890
        '400':
          description: Bad request - Invalid request payload or candidate ID
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestBodyError'
        '401':
          description: Unauthorised - Access token is missing or invalid
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorisedError'
        '403':
          description: >-
            Forbidden - You do not have permission to offer assistance to
            candidates
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Not found - Candidate(s) not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
  /v1/candidates/register:
    post:
      summary: Register a candidate with the Talent Catalog
      description: >-
        Allows API users to register a candidate with the Talent Catalog by
        providing candidate information using the IdentifiableCandidate schema.
        Users should provide as much information as possible, including all
        required fields.
      tags:
        - Candidates
      operationId: registerCandidate
      requestBody:
        description: Candidate information to register with the Talent Catalog
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                registrarId:
                  type: string
                  description: >-
                    The unique identifier of organization supplying the
                    registration data
                  example: registrar-12345
                registrationData:
                  allOf:
                    - $ref: '#/components/schemas/CandidateRegistration'
      responses:
        '201':
          description: Candidate successfully registered with the Talent Catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Success message
                    example: Candidate successfully registered.
                  publicId:
                    type: string
                    format: base64-uuid
                    description: The unique public ID assigned to the registered candidate
                    example: ABcd2EFgHIjkLMNOp3QR-S
        '400':
          description: Bad request - Invalid request payload
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/BadRequestBodyError'
        '401':
          description: Unauthorised - Access token is missing or invalid
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorisedError'
        '403':
          description: Forbidden - Access token does not have the required permissions
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '409':
          description: Conflict - Candidate already registered
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ConflictError'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
  schemas:
    IdentifiableCandidate:
      allOf:
        - $ref: '#/components/schemas/Candidate'
        - $ref: '#/components/schemas/IdentifiableCandidateRegistrationFields'
        - type: object
          properties:
            id:
              type: string
              description: Unique Talent Catalog identifier for the candidate.
              example: 1234567
            candidateNumber:
              type: string
              description: Unique candidate number.
              example: '12345678'
            candidateDependants:
              type: array
              description: List of dependants related to the candidate.
              items:
                $ref: '#/components/schemas/IdentifiableDependant'
            candidateVisaChecks:
              type: array
              description: List of visa checks related to the candidate.
              items:
                $ref: '#/components/schemas/IdentifiableCandidateVisaCheck'
            externalId:
              type: string
              description: External ID of the candidate.
              example: '12345678'
            externalIdSource:
              type: string
              description: Source of the external ID.
              example: source1
            address1:
              type: string
              description: Candidate's address line 1.
              example: 123 Main St
            partnerCandidate:
              description: The candidate's partner (if also a candidate in the system)
              allOf:
                - $ref: '#/components/schemas/IdentifiablePartner'
            registeredByPublicId:
              type: string
              format: base64-uuid
              description: >-
                Anonymised public ID of the partner who registered the candidate
                or null if the candidate registered themselves.
              example: ABcd2EFgHIjkLMNOp3QR-S
            regoIp:
              type: string
              description: IP address of the candidate during registration.
              example: 12.34.56.78
            regoPartnerParam:
              description: Query parameter (p=) for partner during registration.
              type: string
              example: partner1
            regoReferrerParam:
              description: Referrer parameter (r=) during registration.
              type: string
              example: referrer1
            regoUtmCampaign:
              description: UTM campaign parameter during registration.
              type: string
              example: campaign1
            regoUtmContent:
              description: UTM content parameter during registration.
              type: string
              example: content1
            regoUtmMedium:
              description: UTM medium parameter during registration.
              type: string
              example: medium1
            regoUtmSource:
              description: UTM source parameter during registration.
              type: string
              example: source1
            regoUtmTerm:
              description: UTM term parameter during registration.
              type: string
              example: term1
            unhcrFile:
              type: string
              description: Candidate's UNHCR file number.
              example: '12345678'
            unrwaFile:
              type: string
              description: Candidate's UNRWA file number.
              example: '12345678'
            textSearchId:
              type: string
              description: The ID of the corresponding elastic search record.
              example: '12345678'
            folderlink:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                documents.
              example: https://drive.google.com/folder/12345678
            folderlinkAddress:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                address documents.
              example: https://drive.google.com/folder/12345678
            folderlinkCharacter:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                character documents.
              example: https://drive.google.com/folder/12345678
            folderlinkEmployer:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                employer documents.
              example: https://drive.google.com/folder/12345678
            folderlinkEngagement:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                engagement documents.
              example: https://drive.google.com/folder/12345678
            folderlinkExperience:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                experience documents.
              example: https://drive.google.com/folder/12345678
            folderlinkFamily:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                family documents.
              example: https://drive.google.com/folder/12345678
            folderlinkIdentity:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                identity documents.
              example: https://drive.google.com/folder/12345678
            folderlinkImmigration:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                immigration documents.
              example: https://drive.google.com/folder/12345678
            folderlinkLanguage:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                language documents.
              example: https://drive.google.com/folder/12345678
            folderlinkMedical:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                medical documents.
              example: https://drive.google.com/folder/12345678
            folderlinkQualification:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                qualification documents.
              example: https://drive.google.com/folder/12345678
            folderlinkRegistration:
              type: string
              description: >-
                Link to the corresponding folder containing the candidate's
                registration documents.
              example: https://drive.google.com/folder/12345678
            sflink:
              type: string
              description: Link to the corresponding Salesforce record.
              example: https://salesforce.com/record/12345678
            videolink:
              type: string
              description: Link to the corresponding candidate's video profile.
              example: https://drive.google.com/video/12345678
            surveyType:
              description: Survey type associated with the candidate.
              allOf:
                - $ref: '#/components/schemas/SurveyType'
            contactConsentPartners:
              type: boolean
              description: >-
                Indicates whether the candidate has given consent to be
                contacted by TC partners.
              example: true
          required:
            - candidateNumber
    IdentifiableCandidatePage:
      type: object
      description: Page of identifiable candidate data
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/IdentifiableCandidate'
        totalElements:
          type: integer
        totalPages:
          type: integer
        size:
          type: integer
        number:
          type: integer
    IdentifiableDependant:
      allOf:
        - $ref: '#/components/schemas/Dependant'
        - type: object
          properties:
            name:
              type: string
              description: The name of the dependant.
              example: Jane Doe
            dob:
              type: string
              description: >-
                Dependant's date of birth. A date without a time-zone in the
                ISO-8601 calendar system.
              format: date
              example: '1985-06-15'
            registeredNumber:
              type: string
              description: The registration number of the dependant.
              example: '12345678'
    IdentifiableCandidateVisaCheck:
      allOf:
        - $ref: '#/components/schemas/CandidateVisaCheck'
        - type: object
          properties:
            candidateVisaJobChecks:
              type: array
              description: The job checks for the candidate's visa.
              items:
                $ref: '#/components/schemas/IdentifiableCandidateVisaJobCheck'
    IdentifiableCandidateVisaJobCheck:
      allOf:
        - $ref: '#/components/schemas/CandidateVisaJobCheck'
        - type: object
          properties:
            tbbEligibility:
              description: The candidate is eligible for the Talent Catalog.
              allOf:
                - $ref: '#/components/schemas/tc_eligibility_assessment'
    CandidateCertification:
      type: object
      description: A certification that a candidate has achieved.
      properties:
        name:
          type: string
          description: The name of the certification.
          example: Certified Kubernetes Administrator
        institution:
          type: string
          description: The authority that issued the certification.
          example: Cloud Native Computing Foundation
        dateCompleted:
          type: string
          format: date
          description: The date the certification was achieved.
          example: '2024-11-27'
      required:
        - name
        - institution
        - dateCompleted
    has_passport:
      type: string
      enum:
        - NO_RESPONSE
        - VALID_PASSPORT
        - INVALID_PASSPORT
        - NO_PASSPORT
      x-enum-varnames:
        - NO_RESPONSE
        - VALID_PASSPORT
        - INVALID_PASSPORT
        - NO_PASSPORT
      example: VALID_PASSPORT
    status:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
        - DELETED
      x-enum-varnames:
        - ACTIVE
        - INACTIVE
        - DELETED
      example: ACTIVE
    Country:
      type: object
      properties:
        isoCode:
          type: string
          description: The ISO 3166-1 alpha-2 code for the country.
          example: GB
        name:
          type: string
          description: The name of the country.
          example: United Kingdom
        status:
          type: string
          description: The status of the country.
          allOf:
            - $ref: '#/components/schemas/status'
      required:
        - isoCode
        - name
        - status
    CandidateCitizenship:
      type: object
      description: A candidate's citizenship information.
      properties:
        hasPassport:
          type: string
          description: Whether the candidate has a passport.
          allOf:
            - $ref: '#/components/schemas/has_passport'
        passportExp:
          type: string
          format: date
          description: The expiration date of the candidate's passport.
          example: '2024-11-27'
        nationality:
          description: The country of citizenship of the candidate.
          $ref: '#/components/schemas/Country'
    yes_no_unsure:
      type: string
      enum:
        - NO_RESPONSE
        - 'YES'
        - 'NO'
        - UNSURE
      x-enum-varnames:
        - NO_RESPONSE
        - 'YES'
        - 'NO'
        - UNSURE
      example: 'YES'
    Destination:
      type: object
      description: A destination that a candidate is interested in.
      properties:
        country:
          description: The country of the destination.
          allOf:
            - $ref: '#/components/schemas/Country'
        interest:
          type: string
          description: The candidate's interest in the destination.
          allOf:
            - $ref: '#/components/schemas/yes_no_unsure'
    education_type:
      type: string
      enum:
        - ASSOCIATE
        - VOCATIONAL
        - BACHELOR
        - MASTERS
        - DOCTORAL
      x-enum-varnames:
        - ASSOCIATE
        - VOCATIONAL
        - BACHELOR
        - MASTERS
        - DOCTORAL
      example: MASTERS
    EducationMajor:
      type: object
      description: An education major.
      properties:
        id:
          type: integer
          format: int64
          description: The unique identifier for the education major.
          example: 8713
        iscedCode:
          type: string
          description: The ISCED code for the education major.
          example: '0711'
        name:
          type: string
          description: The name of the education major.
          example: Computer Science
        status:
          type: string
          description: The status of the education major.
          allOf:
            - $ref: '#/components/schemas/status'
    CandidateEducation:
      type: object
      description: An education achievement of a candidate
      properties:
        educationType:
          type: string
          description: The type of education.
          allOf:
            - $ref: '#/components/schemas/education_type'
        country:
          $ref: '#/components/schemas/Country'
        educationMajor:
          description: The major of the education.
          allOf:
            - $ref: '#/components/schemas/EducationMajor'
        lengthOfCourseYears:
          type: integer
          description: The length of the course in years.
          example: 4
        institution:
          type: string
          description: The institution where the education was completed.
          example: University of Cambridge
        courseName:
          type: string
          description: The name of the course.
          example: Computer Science Tripos
        yearCompleted:
          type: integer
          description: The year the education was completed.
          example: 2024
        incomplete:
          type: boolean
          description: Whether the education was completed.
          example: false
    exam:
      type: string
      enum:
        - NO_RESPONSE
        - OET
        - OET_READ
        - OET_LIST
        - OET_LANG
        - IELTS_GEN
        - IELTS_ACA
        - TOEFL
        - OTHER
        - DET_OFFICIAL
      x-enum-varnames:
        - NO_RESPONSE
        - OET
        - OET_READ
        - OET_LIST
        - OET_LANG
        - IELTS_GEN
        - IELTS_ACA
        - TOEFL
        - OTHER
        - DET_OFFICIAL
      example: IELTS_GEN
    CandidateExam:
      type: object
      description: An exam that a candidate has taken.
      properties:
        exam:
          type: string
          description: The type of the exam.
          allOf:
            - $ref: '#/components/schemas/exam'
          example: OTHER
        otherExam:
          type: string
          description: The name of the exam if the exam type is "Other".
          example: Test of English for Aviation
        score:
          type: string
          description: The score of the exam.
          example: '8.5'
        year:
          type: integer
          format: int64
          description: The year the exam was taken.
          example: 2024
    Language:
      type: object
      properties:
        isoCode:
          type: string
          description: The ISO code for the language.
          example: en
        name:
          type: string
          description: The name of the language.
          example: English
        status:
          type: string
          description: The status of the language.
          allOf:
            - $ref: '#/components/schemas/status'
    cefr_levels:
      type: string
      enum:
        - A1
        - A2
        - B1
        - B2
        - C1
        - C2
      x-enum-varnames:
        - A1
        - A2
        - B1
        - B2
        - C1
        - C2
      example: B2
    LanguageLevel:
      type: object
      description: A language proficiency level that a candidate has achieved.
      properties:
        level:
          type: integer
          format: int32
          description: The language proficiency level id.
          example: 351
        name:
          type: string
          description: The name of the language proficiency level.
          example: Full Professional Proficiency
        cefrLevel:
          type: string
          description: The CEFR code for the language proficiency level.
          allOf:
            - $ref: '#/components/schemas/cefr_levels'
    CandidateLanguage:
      type: object
      description: The candidate's language proficiency.
      properties:
        language:
          description: The language that the candidate is proficient in.
          allOf:
            - $ref: '#/components/schemas/Language'
        writtenLevel:
          description: The candidate's written proficiency in this language.
          allOf:
            - $ref: '#/components/schemas/LanguageLevel'
        spokenLevel:
          description: The candidate's spoken proficiency in this language.
          allOf:
            - $ref: '#/components/schemas/LanguageLevel'
    Occupation:
      type: object
      description: An occupation.
      properties:
        isco08Code:
          type: string
          description: The ISCO-08 code for the occupation.
          example: '2411'
        name:
          type: string
          description: The name of the occupation.
          example: Accountant
        status:
          type: string
          description: The status of the occupation.
          allOf:
            - $ref: '#/components/schemas/status'
    CandidateJobExperience:
      type: object
      description: A job experience that a candidate has had
      properties:
        country:
          $ref: '#/components/schemas/Country'
        companyName:
          type: string
          description: The name of the company where the candidate worked.
          example: Acme Corporation
        role:
          type: string
          description: The role the candidate had at the company.
          example: Senior Software Engineer
        startDate:
          type: string
          format: date
          description: The date the candidate started working at the company.
          example: '2020-11-27'
        endDate:
          type: string
          format: date
          description: The date the candidate stopped working at the company.
          example: '2024-11-27'
        fullTime:
          type: boolean
          description: Whether the candidate worked full-time at the company.
          example: true
        paid:
          type: boolean
          description: Whether the candidate was paid for their work at the company.
          example: true
        description:
          type: string
          description: A description of the candidate's work at the company.
          example: Developed new features for the company's flagship product.
    CandidateOccupation:
      type: object
      description: The candidate's occupation
      properties:
        occupation:
          description: The candidate's occupation.
          allOf:
            - $ref: '#/components/schemas/Occupation'
        yearsExperience:
          type: integer
          description: The number of years of experience the candidate has in this job.
          example: 5
        candidateJobExperiences:
          type: array
          description: List of job experiences of the candidate in this occupation.
          items:
            $ref: '#/components/schemas/CandidateJobExperience'
    CandidateSkill:
      type: object
      description: A skill associated with a candidate.
      properties:
        skill:
          type: string
          description: The name of the skill.
          example: Java
        timePeriod:
          type: string
          description: The duration the candidate has been using this skill.
          example: 5 years
    gender:
      type: string
      enum:
        - MALE
        - FEMALE
        - OTHER
      x-enum-varnames:
        - MALE
        - FEMALE
        - OTHER
      example: OTHER
    EducationLevel:
      type: object
      description: The education level.
      properties:
        level:
          type: integer
          format: int32
          description: The level of education.
          example: 40
        status:
          description: The status of the education level.
          allOf:
            - $ref: '#/components/schemas/status'
        educationType:
          description: The type of education.
          allOf:
            - $ref: '#/components/schemas/education_type'
    how_heard_about_us:
      type: string
      enum:
        - ONLINE_GOOGLE_SEARCH
        - FACEBOOK
        - INSTAGRAM
        - LINKEDIN
        - X
        - WHATSAPP
        - YOUTUBE
        - FRIEND_COLLEAGUE_REFERRAL
        - UNIVERSITY_SCHOOL_REFERRAL
        - EMPLOYER_REFERRAL
        - EVENT_WEBINAR
        - INFORMATION_SESSION
        - COMMUNITY_CENTRE_POSTING_FLYERS
        - OUTREACH_WORKER
        - NGO
        - UNHCR
        - US_AFGHAN
        - ULYP
        - TECHFUGEES
        - AL_GHURAIR_FOUNDATION
        - OTHER
      x-enum-varnames:
        - ONLINE_GOOGLE_SEARCH
        - FACEBOOK
        - INSTAGRAM
        - LINKEDIN
        - X
        - WHATSAPP
        - YOUTUBE
        - FRIEND_COLLEAGUE_REFERRAL
        - UNIVERSITY_SCHOOL_REFERRAL
        - EMPLOYER_REFERRAL
        - EVENT_WEBINAR
        - INFORMATION_SESSION
        - COMMUNITY_CENTRE_POSTING_FLYERS
        - OUTREACH_WORKER
        - NGO
        - UNHCR
        - US_AFGHAN
        - ULYP
        - TECHFUGEES
        - AL_GHURAIR_FOUNDATION
        - OTHER
      example: FRIEND_COLLEAGUE_REFERRAL
    yes_no:
      type: string
      enum:
        - NO_RESPONSE
        - 'YES'
        - 'NO'
      x-enum-varnames:
        - NO_RESPONSE
        - 'YES'
        - 'NO'
      example: 'YES'
    AnonCandidateRegistrationFields:
      type: object
      description: >-
        Represents non identifiable Candidate data that originates in the
        original registration.
      properties:
        candidateCertifications:
          type: array
          description: List of certifications held by the candidate.
          items:
            $ref: '#/components/schemas/CandidateCertification'
        candidateCitizenships:
          type: array
          description: List of citizenships held by the candidate.
          items:
            $ref: '#/components/schemas/CandidateCitizenship'
        candidateDestinations:
          type: array
          description: List of destinations related to the candidate.
          items:
            $ref: '#/components/schemas/Destination'
        candidateEducations:
          type: array
          description: List of educational achievements of the candidate.
          items:
            $ref: '#/components/schemas/CandidateEducation'
        candidateExams:
          type: array
          description: List of exams taken by the candidate.
          items:
            $ref: '#/components/schemas/CandidateExam'
        candidateLanguages:
          type: array
          description: List of languages that the candidate is proficient in.
          items:
            $ref: '#/components/schemas/CandidateLanguage'
        candidateMessage:
          type: string
          description: Message written by the candidate.
        candidateOccupations:
          type: array
          description: List of occupations related to the candidate.
          items:
            $ref: '#/components/schemas/CandidateOccupation'
        candidateSkills:
          type: array
          description: List of skills possessed by the candidate.
          items:
            $ref: '#/components/schemas/CandidateSkill'
        city:
          type: string
          description: City of residence
          example: Amman
        contactConsentTcPartners:
          type: boolean
          description: >-
            Indicates whether the candidate has given consent to be contacted by
            TC partners.
          example: true
        contactConsentRegistration:
          type: boolean
          description: >-
            Indicates whether the candidate has given consent to be contacted
            regarding their registration and employment opportunities.
          example: true
        country:
          description: Country where candidate is currently located
          allOf:
            - $ref: '#/components/schemas/Country'
        gender:
          description: Candidate's gender.
          allOf:
            - $ref: '#/components/schemas/gender'
        maxEducationLevel:
          description: The maximum education level of the candidate
          allOf:
            - $ref: '#/components/schemas/EducationLevel'
        nationality:
          description: Nationality of the candidate.
          allOf:
            - $ref: '#/components/schemas/Country'
        howHeardAboutUs:
          description: How the candidate heard about the Talent Catalog.
          allOf:
            - $ref: '#/components/schemas/how_heard_about_us'
        unhcrConsent:
          description: >-
            Indicates whether the candidate has given consent for UNHCR to be
            notified that they have registered on the Talent Catalog.
          allOf:
            - $ref: '#/components/schemas/yes_no'
        yearOfArrival:
          type: integer
          format: int32
          description: Year of arrival in the country
          example: 2010
    avail_immediate_reason:
      type: string
      enum:
        - FAMILY
        - HEALTH
        - CURRENT_WORK
        - STUDIES
        - OTHER
      x-enum-varnames:
        - FAMILY
        - HEALTH
        - CURRENT_WORK
        - STUDIES
        - OTHER
      example: FAMILY
    dependant_relations:
      type: string
      enum:
        - NO_RESPONSE
        - PARTNER
        - CHILD
        - PARENT
        - SIBLING
        - AUNT_UNCLE
        - GRANDPARENT
        - COUSIN
        - OTHER
      x-enum-varnames:
        - NO_RESPONSE
        - PARTNER
        - CHILD
        - PARENT
        - SIBLING
        - AUNT_UNCLE
        - GRANDPARENT
        - COUSIN
        - OTHER
      example: CHILD
    registration:
      type: string
      enum:
        - NO_RESPONSE
        - UNHCR
        - UNRWA
        - NEITHER
        - NA
      x-enum-varnames:
        - NO_RESPONSE
        - UNHCR
        - UNRWA
        - NEITHER
        - NA
      example: UNHCR
    Dependant:
      type: object
      description: A dependant of a candidate.
      properties:
        relation:
          description: The relation of the dependant to the candidate.
          allOf:
            - $ref: '#/components/schemas/dependant_relations'
        relationOther:
          type: string
          description: >-
            The relation of the dependant to the candidate if the relation is
            "Other".
          example: Niece
        yearOfBirth:
          type: integer
          format: int32
          description: Year of birth of the candidate
          example: 1985
        gender:
          description: The gender of the dependant.
          allOf:
            - $ref: '#/components/schemas/gender'
        registered:
          description: Whether and where the dependant is registered.
          allOf:
            - $ref: '#/components/schemas/registration'
        healthConcern:
          description: Any health concerns for the dependant.
          allOf:
            - $ref: '#/components/schemas/yes_no'
          example: 'NO'
    risk_level:
      type: string
      enum:
        - NO_RESPONSE
        - LOW
        - MEDIUM
        - HIGH
      x-enum-varnames:
        - NO_RESPONSE
        - LOW
        - MEDIUM
        - HIGH
      example: LOW
    document_status:
      type: string
      enum:
        - NO_RESPONSE
        - VALID
        - EXPIRED
        - NONE
      x-enum-varnames:
        - NO_RESPONSE
        - VALID
        - EXPIRED
        - NONE
      example: VALID
    family_relations:
      type: string
      enum:
        - NO_RESPONSE
        - NO_RELATION
        - CHILD
        - PARENT
        - SIBLING
        - AUNT_UNCLE
        - GRANDPARENT
        - COUSIN
        - OTHER
      x-enum-varnames:
        - NO_RESPONSE
        - NO_RELATION
        - CHILD
        - PARENT
        - SIBLING
        - AUNT_UNCLE
        - GRANDPARENT
        - COUSIN
        - OTHER
      example: CHILD
    Employer:
      type: object
      description: An anonymised employer.
      properties:
        country:
          description: The country where the employer is located.
          allOf:
            - $ref: '#/components/schemas/Country'
        hasHiredInternationally:
          type: boolean
          description: Whether the employer has hired internationally.
          example: true
    job_opportunity_stage:
      type: string
      enum:
        - PROSPECT
        - BRIEFING
        - PITCHING
        - MOU
        - IDENTIFYING_ROLES
        - CANDIDATE_SEARCH
        - VISA_ELIGIBILITY
        - CV_PREPARATION
        - CV_REVIEW
        - RECRUITMENT_PROCESS
        - JOB_OFFER
        - TRAINING
        - VISA_PREPARATION
        - POST_HIRE_ENGAGEMENT
        - HIRING_COMPLETED
        - INELIGIBLE_EMPLOYER
        - INELIGIBLE_OCCUPATION
        - INELIGIBLE_REGION
        - NO_INTEREST
        - NO_JOB_OFFER
        - NO_PR_PATHWAY
        - NO_SUITABLE_CANDIDATES
        - NO_VISA
        - TOO_EXPENSIVE
        - TOO_HIGH_WAGE
        - TOO_LONG
        - MOU_ISSUE
        - TRAINING_NOT_COMPLETED
      x-enum-varnames:
        - PROSPECT
        - BRIEFING
        - PITCHING
        - MOU
        - IDENTIFYING_ROLES
        - CANDIDATE_SEARCH
        - VISA_ELIGIBILITY
        - CV_PREPARATION
        - CV_REVIEW
        - RECRUITMENT_PROCESS
        - JOB_OFFER
        - TRAINING
        - VISA_PREPARATION
        - POST_HIRE_ENGAGEMENT
        - HIRING_COMPLETED
        - INELIGIBLE_EMPLOYER
        - INELIGIBLE_OCCUPATION
        - INELIGIBLE_REGION
        - NO_INTEREST
        - NO_JOB_OFFER
        - NO_PR_PATHWAY
        - NO_SUITABLE_CANDIDATES
        - NO_VISA
        - TOO_EXPENSIVE
        - TOO_HIGH_WAGE
        - TOO_LONG
        - MOU_ISSUE
        - TRAINING_NOT_COMPLETED
      example: CANDIDATE_SEARCH
    JobOpportunity:
      type: object
      description: A job opportunity.
      properties:
        country:
          description: The country where the job opportunity is located.
          allOf:
            - $ref: '#/components/schemas/Country'
        employerEntity:
          description: The anonymised employer details.
          allOf:
            - $ref: '#/components/schemas/Employer'
        evergreen:
          type: boolean
          description: Whether the job opportunity is evergreen.
          example: true
        publishedDate:
          type: string
          format: date-time
          description: The date the job opportunity was published.
          example: '2021-01-01T00:00:00Z'
        stage:
          description: The stage of the job opportunity.
          allOf:
            - $ref: '#/components/schemas/job_opportunity_stage'
          example: VISA_PREPARATION
        submissionDueDate:
          type: string
          format: date
          description: The date submissions are due for the job opportunity.
          example: '2021-01-01'
        hiringCommitment:
          type: integer
          format: int64
          description: >-
            The number of candidates the employer has committed to hiring for
            this opportunity.
          example: 3
        employerHiredInternationally:
          type: string
          description: >-
            Whether the employer had hired internationally prior to this
            opportunity.
          example: 'Yes'
    other_visas:
      type: string
      enum:
        - NO_RESPONSE
        - TEMP_SKILLED
        - SPECIAL_HUM
        - OTHER_HUM
        - DIRECT_ENT
        - POINTS_INDEP
      x-enum-varnames:
        - NO_RESPONSE
        - TEMP_SKILLED
        - SPECIAL_HUM
        - OTHER_HUM
        - DIRECT_ENT
        - POINTS_INDEP
      example: TEMP_SKILLED
    visa_eligibility:
      type: string
      enum:
        - NO_RESPONSE
        - 'YES'
        - YES_BUT
        - DISCUSS_FURTHER
        - SEEK_ADVICE
        - 'NO'
      x-enum-varnames:
        - NO_RESPONSE
        - 'YES'
        - YES_BUT
        - DISCUSS_FURTHER
        - SEEK_ADVICE
        - 'NO'
      example: 'YES'
    tc_eligibility_assessment:
      type: string
      enum:
        - NO_RESPONSE
        - PROCEED
        - DISCUSS
        - DONT_PROCEED
      x-enum-varnames:
        - NO_RESPONSE
        - PROCEED
        - DISCUSS
        - DONT_PROCEED
      example: PROCEED
    CandidateVisaJobCheck:
      type: object
      description: A job check related to a candidate's visa for a destination.
      properties:
        jobOpp:
          description: >-
            The job opportunity that's located in same destination associated
            with the visa check.
          allOf:
            - $ref: '#/components/schemas/JobOpportunity'
        interest:
          description: >-
            The candidate has genuine interest and desire to relocate for the
            job opportunity.
          allOf:
            - $ref: '#/components/schemas/yes_no'
        qualification:
          description: The candidate has relevant qualification for the job opportunity.
          allOf:
            - $ref: '#/components/schemas/yes_no'
        occupation:
          description: The occupation for the job opportunity.
          allOf:
            - $ref: '#/components/schemas/Occupation'
        salaryTsmit:
          description: >-
            The salary for the job opportunity meets the TSMIT threshold
            (Australia visa check ONLY), see
            'https://www.homeaffairs.gov.au/reports-and-pubs/files/tsmit_review_report.pdf'
          allOf:
            - $ref: '#/components/schemas/yes_no'
        regional:
          description: The job opportunity is in a regional area.
          allOf:
            - $ref: '#/components/schemas/yes_no'
        eligible_494:
          description: >-
            The candidate is eligible for the 494 visa (Australia visa check
            ONLY).
          allOf:
            - $ref: '#/components/schemas/yes_no'
        eligible_186:
          description: >-
            The candidate is eligible for the 186 visa.(Australia visa check
            ONLY)
          allOf:
            - $ref: '#/components/schemas/yes_no'
        eligibleOther:
          description: >-
            The candidate is eligible for another visa (Australia visa check
            ONLY).
          allOf:
            - $ref: '#/components/schemas/other_visas'
        putForward:
          description: The candidate has been put forward for the job opportunity.
          allOf:
            - $ref: '#/components/schemas/visa_eligibility'
        tcEligibility:
          description: The candidate is eligible for the Talent Catalog.
          allOf:
            - $ref: '#/components/schemas/tc_eligibility_assessment'
        ageRequirement:
          type: string
          description: The candidate meets the age requirement for the job opportunity.
          example: 'Yes'
        languagesRequired:
          type: array
          description: >-
            An array of language IDs denoting the languages required for the job
            opportunity.
          items:
            type: integer
            format: int64
          example:
            - 1
            - 2
        languagesThresholdMet:
          description: The candidate meets the language threshold for the job opportunity.
          allOf:
            - $ref: '#/components/schemas/yes_no'
    CandidateVisaCheck:
      type: object
      description: A check of a candidate's visa status.
      properties:
        country:
          description: The country of the visa.
          allOf:
            - $ref: '#/components/schemas/Country'
        protection:
          description: Meets international protection assessment.
          allOf:
            - $ref: '#/components/schemas/yes_no'
        englishThreshold:
          description: Meets the English language threshold for the visa.
          allOf:
            - $ref: '#/components/schemas/yes_no'
        healthAssessment:
          description: Meets health assessment for the visa.
          allOf:
            - $ref: '#/components/schemas/yes_no'
        characterAssessment:
          description: Meets character assessment for the visa.
          allOf:
            - $ref: '#/components/schemas/yes_no'
        securityRisk:
          description: Meets security risk assessment for the visa.
          allOf:
            - $ref: '#/components/schemas/yes_no'
          example: 'NO'
        overallRisk:
          description: The overall risk assessment status for the visa.
          allOf:
            - $ref: '#/components/schemas/risk_level'
        validTravelDocs:
          description: The validity status of the candidate's travel document (if exists).
          allOf:
            - $ref: '#/components/schemas/document_status'
        pathwayAssessment:
          description: Meets pathway assessment for the visa.
          allOf:
            - $ref: '#/components/schemas/yes_no_unsure'
        destinationFamily:
          description: >-
            The closest relative of the candidate in the destination country (if
            exists).
          allOf:
            - $ref: '#/components/schemas/family_relations'
          example: SIBLING
        candidateVisaJobChecks:
          type: array
          description: The job checks for the candidate's visa.
          items:
            $ref: '#/components/schemas/CandidateVisaJobCheck'
    vaccination_status:
      type: string
      enum:
        - NO_RESPONSE
        - FULL
        - PARTIAL
      x-enum-varnames:
        - NO_RESPONSE
        - FULL
        - PARTIAL
      example: FULL
    int_recruit_reason:
      type: string
      enum:
        - NO_RESPONSE
        - CANT_RETURN_HOME
        - CITIZENSHIP
        - EXPERIENCE
        - CHILDREN
        - OTHER
      x-enum-varnames:
        - NO_RESPONSE
        - CANT_RETURN_HOME
        - CITIZENSHIP
        - EXPERIENCE
        - CHILDREN
        - OTHER
      example: CANT_RETURN_HOME
    left_home_reason:
      type: string
      enum:
        - NO_RESPONSE
        - SAFETY
        - JOB
        - OTHER
      x-enum-varnames:
        - NO_RESPONSE
        - SAFETY
        - JOB
        - OTHER
      example: SAFETY
    marital_status:
      type: string
      enum:
        - NO_RESPONSE
        - MARRIED
        - ENGAGED
        - DEFACTO
        - SINGLE
        - DIVORCED
        - SEPARATED
        - WIDOWER
      x-enum-varnames:
        - NO_RESPONSE
        - MARRIED
        - ENGAGED
        - DEFACTO
        - SINGLE
        - DIVORCED
        - SEPARATED
        - WIDOWER
      example: MARRIED
    ielts_status:
      type: string
      enum:
        - NO_RESPONSE
        - YES_GENERAL
        - YES_ACADEMIC
        - 'NO'
        - UNSURE
      x-enum-varnames:
        - NO_RESPONSE
        - YES_GENERAL
        - YES_ACADEMIC
        - 'NO'
        - UNSURE
      example: YES_GENERAL
    residence_status:
      type: string
      enum:
        - NO_RESPONSE
        - LEGAL_RES
        - ILLEGAL_RES
        - OTHER
      x-enum-varnames:
        - NO_RESPONSE
        - LEGAL_RES
        - ILLEGAL_RES
        - OTHER
      example: LEGAL_RES
    candidate_status:
      type: string
      enum:
        - ACTIVE
        - AUTONOMOUS_EMPLOYMENT
        - DELETED
        - DRAFT
        - EMPLOYED
        - INCOMPLETE
        - INELIGIBLE
        - PENDING
        - UNREACHABLE
        - WITHDRAWN
      x-enum-varnames:
        - ACTIVE
        - AUTONOMOUS_EMPLOYMENT
        - DELETED
        - DRAFT
        - EMPLOYED
        - INCOMPLETE
        - INELIGIBLE
        - PENDING
        - UNREACHABLE
        - WITHDRAWN
      example: ACTIVE
    not_registered_status:
      type: string
      enum:
        - NO_RESPONSE
        - WAS_REGISTERED
        - NEVER_REGISTERED
        - REGISTERING
        - UNSURE
        - NA
      x-enum-varnames:
        - NO_RESPONSE
        - WAS_REGISTERED
        - NEVER_REGISTERED
        - REGISTERING
        - UNSURE
        - NA
      example: NEVER_REGISTERED
    unhcr_status:
      type: string
      enum:
        - NO_RESPONSE
        - MANDATE_REFUGEE
        - REGISTERED_ASYLUM
        - REGISTERED_STATELESS
        - REGISTERED_STATUS_UNKNOWN
        - NOT_REGISTERED
        - UNSURE
        - NA
      x-enum-varnames:
        - NO_RESPONSE
        - MANDATE_REFUGEE
        - REGISTERED_ASYLUM
        - REGISTERED_STATELESS
        - REGISTERED_STATUS_UNKNOWN
        - NOT_REGISTERED
        - UNSURE
        - NA
      example: MANDATE_REFUGEE
    work_permit:
      type: string
      enum:
        - NO_RESPONSE
        - YES_NOT_DESIRED
        - YES_DESIRED
        - 'NO'
      x-enum-varnames:
        - NO_RESPONSE
        - YES_NOT_DESIRED
        - YES_DESIRED
        - 'NO'
      example: YES_DESIRED
    iso_timestamp:
      type: string
      format: date-time
      description: >-
        ISO 8601 formatted timestamp. Created and modified timestamps are in
        UTC.
      example: '2024-11-14T14:30:00Z'
      title: ISO 8601 Timestamp
      readOnly: true
    Candidate:
      allOf:
        - $ref: '#/components/schemas/AnonCandidateRegistrationFields'
        - type: object
          description: Represents anon Candidate data that is created post registration
          properties:
            publicId:
              type: string
              format: base64-uuid
              description: Universally unique identifier for the candidate
              example: ABcd2EFgHIjkLMNOp3QR-S
            asylumYear:
              type: string
              format: date
              description: Date of asylum
              example: '2015-07-12'
            arrestImprison:
              type: string
              description: Indicates whether the candidate has been arrested or imprisoned.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
            availDate:
              type: string
              format: date
              description: >-
                Date when the candidate becomes available for opportunities. A
                date without a time-zone in the ISO-8601 calendar system
              example: '2023-12-01'
            availImmediate:
              type: string
              description: >-
                Indicates whether the candidate is immediately available for
                opportunities.
              allOf:
                - $ref: '#/components/schemas/yes_no'
            availImmediateJobOps:
              type: string
              description: The type of job opportunities the candidate is qualified for.
              example: 'Yes'
            availImmediateReason:
              type: string
              description: Reason for the candidate's immediate availability.
              allOf:
                - $ref: '#/components/schemas/avail_immediate_reason'
            birthCountry:
              description: Country of birth
              allOf:
                - $ref: '#/components/schemas/Country'
            candidateDependants:
              type: array
              description: List of dependants related to the candidate.
              items:
                $ref: '#/components/schemas/Dependant'
            candidateVisaChecks:
              type: array
              description: List of visa checks related to the candidate.
              items:
                $ref: '#/components/schemas/CandidateVisaCheck'
            canDrive:
              description: Indicates whether the candidate can drive.
              allOf:
                - $ref: '#/components/schemas/yes_no'
            conflict:
              description: Indicates whether the candidate has participated in a conflict.
              allOf:
                - $ref: '#/components/schemas/yes_no'
              example: 'NO'
            covidVaccinated:
              description: Vaccination status of the candidate.
              allOf:
                - $ref: '#/components/schemas/yes_no'
            covidVaccinatedDate:
              type: string
              format: date
              description: Date of the candidate's last COVID-19 vaccination.
              example: '2022-12-15'
            covidVaccineName:
              type: string
              description: Name of the COVID-19 vaccine received by the candidate.
              example: Pfizer-BioNTech
            covidVaccinatedStatus:
              description: COVID-19 vaccination status of the candidate.
              allOf:
                - $ref: '#/components/schemas/vaccination_status'
            crimeConvict:
              description: Indicates whether the candidate has a criminal conviction.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
              example: 'NO'
            destLimit:
              description: Destination limits for the candidate.
              allOf:
                - $ref: '#/components/schemas/yes_no'
              example: 'NO'
            drivingLicense:
              description: Indicates the status of the candidate's driving license.
              allOf:
                - $ref: '#/components/schemas/document_status'
            drivingLicenseCountry:
              description: Country where the candidate's driving license was issued.
              allOf:
                - $ref: '#/components/schemas/Country'
            drivingLicenseExp:
              type: string
              format: date
              description: Expiry date of the candidate's driving license.
              example: '2025-12-31'
            englishAssessmentScoreIelts:
              type: string
              description: IELTS score of the candidate's English assessment.
              example: '6.5'
            familyMove:
              description: Indicates whether the candidate is moving with their family.
              allOf:
                - $ref: '#/components/schemas/yes_no'
            frenchAssessmentScoreNclc:
              type: integer
              format: int64
              description: >-
                NCLC (Canadian Language Benchmark) score of the candidate's
                French assessment.
              example: 10
            fullIntakeCompletedDate:
              type: string
              format: date-time
              description: Date when the full intake was completed.
              example: '2022-12-31T14:30:00Z'
            healthIssues:
              description: Indicates whether the candidate has health issues.
              allOf:
                - $ref: '#/components/schemas/yes_no'
              example: 'NO'
            homeLocation:
              type: string
              description: Home location of the candidate before they became a refugee.
              example: Damascus
            hostChallenges:
              type: string
              description: Challenges faced by the candidate in the host country.
              example: Host country challenges
            hostEntryLegally:
              description: Indicates if the candidate entered the host country legally.
              allOf:
                - $ref: '#/components/schemas/yes_no'
            hostEntryYear:
              type: integer
              description: Year the candidate entered the host country.
              example: 2010
            ieltsScore:
              type: number
              format: float
              description: IELTS score of the candidate.
              example: 7.5
            intRecruitReasons:
              type: array
              description: Reasons for the candidate's international recruitment.
              items:
                $ref: '#/components/schemas/int_recruit_reason'
            intRecruitRural:
              description: Indicates whether the candidate will work in a rural area.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
            leftHomeReasons:
              type: array
              description: Reasons for the candidate leaving home.
              items:
                $ref: '#/components/schemas/left_home_reason'
            maritalStatus:
              description: Marital status of the candidate.
              allOf:
                - $ref: '#/components/schemas/marital_status'
            mediaWillingness:
              type: string
              description: >-
                Indicates the candidate's willingness to participate in media
                activities
              example: 'Yes'
            militaryService:
              description: Indicates whether the candidate has served in the military.
              allOf:
                - $ref: '#/components/schemas/yes_no'
            militaryWanted:
              description: Indicates whether the candidate is wanted for military service.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
              example: 'NO'
            militaryStart:
              type: string
              format: date
              description: Start date of the candidate's military service.
              example: '2010-01-01'
            militaryEnd:
              type: string
              format: date
              description: End date of the candidate's military service.
              example: '2015-01-01'
            miniIntakeCompletedDate:
              type: string
              format: date-time
              description: Date when the mini intake was completed.
              example: '2022-12-31T14:30:00Z'
            monitoringEvaluationConsent:
              description: >-
                Indicates whether the candidate has given consent for monitoring
                and evaluation.
              allOf:
                - $ref: '#/components/schemas/yes_no'
            numberDependants:
              type: integer
              format: int64
              description: Number of dependants related to the candidate.
              example: 2
            partnerRegistered:
              description: Indicates whether the candidate's partner is registered.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
            partnerPublicId:
              type: string
              format: base64-uuid
              description: >-
                Anonymised public ID of the candidate's partner (if also a
                candidate in the system)
              example: ABcd2EFgHIjkLMNOp3QR-S
            partnerCitizenship:
              type: array
              description: Citizenship(s) of the candidate's partner.
              items:
                type: integer
                format: int64
              example:
                - 1
                - 2
            partnerEduLevel:
              description: Education level of the candidate's partner.
              allOf:
                - $ref: '#/components/schemas/EducationLevel'
            partnerEnglish:
              description: Indicates whether the candidate's partner speaks English.
              allOf:
                - $ref: '#/components/schemas/yes_no'
            partnerEnglishLevel:
              description: English proficiency level of the candidate's partner.
              allOf:
                - $ref: '#/components/schemas/LanguageLevel'
            partnerIelts:
              description: >-
                Indicates whether the candidate's partner has taken the IELTS
                exam.
              allOf:
                - $ref: '#/components/schemas/ielts_status'
            partnerIeltsScore:
              type: string
              description: IELTS score of the candidate's partner.
              example: '7.5'
            partnerIeltsYr:
              type: integer
              format: int64
              description: Year the candidate's partner took the IELTS exam.
              example: 2020
            partnerOccupation:
              description: Occupation of the candidate's partner.
              allOf:
                - $ref: '#/components/schemas/Occupation'
            residenceStatus:
              description: Residence status of the candidate.
              allOf:
                - $ref: '#/components/schemas/residence_status'
            returnedHome:
              description: Indicates whether the candidate has returned home.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
              example: 'NO'
            returnHomeSafe:
              description: Indicates whether the candidate returned home safely.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
            returnHomeFuture:
              description: >-
                Indicates whether the candidate plans to return home in the
                future.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
              example: 'NO'
            resettleThird:
              description: >-
                Indicates whether the candidate has ever applied for
                resettlement or emigration to a 3rd country.
              allOf:
                - $ref: '#/components/schemas/yes_no'
            status:
              description: Status of the candidate.
              allOf:
                - $ref: '#/components/schemas/candidate_status'
            unhcrNotRegStatus:
              description: UNHCR not registered status of the candidate.
              allOf:
                - $ref: '#/components/schemas/not_registered_status'
            unhcrRegistered:
              description: Indicates whether the candidate is registered with UNHCR.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
            unhcrStatus:
              description: UNHCR status of the candidate.
              allOf:
                - $ref: '#/components/schemas/unhcr_status'
            unrwaNotRegStatus:
              description: UNRWA not registered status of the candidate.
              allOf:
                - $ref: '#/components/schemas/not_registered_status'
            unrwaRegistered:
              description: Indicates whether the candidate is registered with UNRWA.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
              example: 'NO'
            visaIssues:
              description: Indicates whether the candidate has had visa issues.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
              example: 'NO'
            visaReject:
              description: >-
                Indicates whether the candidate has had a visa application
                rejected.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
              example: 'NO'
            workAbroad:
              description: Indicates whether the candidate has worked abroad.
              allOf:
                - $ref: '#/components/schemas/yes_no'
            workPermit:
              description: >-
                Indicates whether the candidate has a work permit and if it is
                in the desired field.
              allOf:
                - $ref: '#/components/schemas/work_permit'
            workPermitDesired:
              description: Indicates whether the candidate desires a work permit.
              allOf:
                - $ref: '#/components/schemas/yes_no_unsure'
            yearOfArrival:
              type: integer
              format: int32
              description: Year of arrival in the country
              example: 2010
            yearOfBirth:
              type: integer
              format: int32
              description: Year of birth of the candidate
              example: 1985
            createdDate:
              description: Date when the candidate was created.
              allOf:
                - $ref: '#/components/schemas/iso_timestamp'
          required:
            - publicId
    CandidatePage:
      type: object
      description: Page of anonymised candidate data
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/Candidate'
        totalElements:
          type: integer
        totalPages:
          type: integer
        size:
          type: integer
        number:
          type: integer
    ErrorBase:
      type: object
      properties:
        type:
          type: string
          description: >
            A URI reference that identifies the problem type with a link to
            human-readable  documentation for the error.
          example: https://example.com/probs/doc
        title:
          type: string
          description: >
            A short, human-readable summary of the problem type that does not
            change from occurrence to  occurrence of the problem.
          example: Invalid Pagination Parameter
        status:
          type: integer
          description: >
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
        detail:
          type: string
          description: >
            A human-readable explanation specific to this occurrence of the
            problem.
        instance:
          type: string
          description: >
            A URI reference that identifies the specific occurrence of the
            problem. It may be used to  provide further context.
          example: /v1/candidates?page=1
    BadRequestBase:
      allOf:
        - $ref: '#/components/schemas/ErrorBase'
        - type: object
          properties:
            title:
              example: Invalid Request
            status:
              example: 400
    BadRequestParamError:
      allOf:
        - $ref: '#/components/schemas/BadRequestBase'
        - type: object
          properties:
            detail:
              example: A request parameter is invalid.
    UnauthorisedError:
      allOf:
        - $ref: '#/components/schemas/ErrorBase'
        - type: object
          properties:
            title:
              example: Authentication required
            status:
              example: 401
            detail:
              example: Invalid API key.
    InternalServerError:
      allOf:
        - $ref: '#/components/schemas/ErrorBase'
        - type: object
          properties:
            title:
              example: Service Unavailable
            status:
              example: 500
            detail:
              example: An unexpected error occurred. Please try again later.
    NotFoundError:
      allOf:
        - $ref: '#/components/schemas/ErrorBase'
        - type: object
          properties:
            title:
              example: Resource not found
            status:
              example: 404
            detail:
              example: Candidate with the provided publicId was not found.
    BadRequestBodyError:
      allOf:
        - $ref: '#/components/schemas/BadRequestBase'
        - type: object
          properties:
            detail:
              example: Request body is missing required fields.
    ForbiddenError:
      allOf:
        - $ref: '#/components/schemas/ErrorBase'
        - type: object
          properties:
            title:
              example: Forbidden
            status:
              example: 403
            detail:
              example: You do not have permission to offer candidate services.
    CandidateCoupon:
      type: object
      description: A candidate plus an optional coupon - used in offer to assist services
      properties:
        publicId:
          type: string
          format: base64-uuid
          description: The unique public ID of the candidate.
          example: ABcd2EFgHIjkLMNOp3QR-S
        couponCode:
          type: string
          description: >-
            An optional coupon code that the candidate may use for service
            access.
          example: COUPON2025
      required:
        - publicId
    candidate_assistance_type:
      type: string
      enum:
        - JOB_OPPORTUNITY
        - EDUCATION_SERVICE
        - MIGRATION_SERVICE
        - FINANCIAL_SUPPORT_SERVICE
        - SETTLEMENT_SERVICE
        - OTHER
      x-enum-varnames:
        - JOB_OPPORTUNITY
        - EDUCATION_SERVICE
        - MIGRATION_SERVICE
        - FINANCIAL_SUPPORT_SERVICE
        - SETTLEMENT_SERVICE
        - OTHER
      example: JOB_OPPORTUNITY
    User:
      type: object
      description: A user of the TC system.
      properties:
        firstName:
          type: string
          description: First name (and any middle names) of user.
          example: John
        lastName:
          type: string
          description: The last name of the user.
          example: Doe
        email:
          type: string
          format: email
          description: The email address of the user.
          example: john@doe.com
    IdentifiableCandidateRegistrationFields:
      type: object
      description: >-
        Identifiable Candidate data that originates in the original
        registration.
      properties:
        identity:
          allOf:
            - $ref: '#/components/schemas/User'
        dob:
          type: string
          description: >-
            Candidate's date of birth. A date without a time-zone in the
            ISO-8601 calendar system.
          format: date
          example: '1985-06-15'
        linkedInLink:
          type: string
          description: Candidate's LinkedIn profile URL.
          example: https://www.linkedin.com/in/johndoe
        phone:
          type: string
          description: Candidate's phone number.
          example: +1-234-567-890
        unhcrNumber:
          type: string
          description: Candidate's UNHCR number.
          example: '12345678'
        unrwaNumber:
          type: string
          description: Candidate's UNRWA number.
          example: '12345678'
        whatsapp:
          type: string
          description: Candidate's WhatsApp number.
          example: +1-234-567-890
    CandidateRegistration:
      description: Data required to register a candidate on the Talent Catalog.
      allOf:
        - $ref: '#/components/schemas/IdentifiableCandidateRegistrationFields'
        - $ref: '#/components/schemas/AnonCandidateRegistrationFields'
    ConflictError:
      allOf:
        - $ref: '#/components/schemas/ErrorBase'
        - type: object
          properties:
            title:
              example: Potential Duplicate
            status:
              example: 409
            detail:
              example: A candidate with this email address already exists.
    IdentifiablePartner:
      type: object
      properties:
        id:
          type: string
          description: Unique Talent Catalog identifier for the candidate's partner.
          example: 1234567
        candidateNumber:
          type: string
          description: Unique candidate number for the candidate's partner.
          example: '12345678'
        publicId:
          type: string
          format: base64-uuid
          description: Anonymised public ID of the candidate's partner
          example: ABcd2EFgHIjkLMNOp3QR-S
    SurveyType:
      type: object
      description: The type of survey.
      properties:
        name:
          type: string
          description: The name of the survey type.
          example: Employee Engagement
        status:
          description: The status of the survey type.
          allOf:
            - $ref: '#/components/schemas/status'
security:
  - ApiKeyAuth: []
