# Register a candidate with the Talent Catalog

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.

Endpoint: POST /v1/candidates/register
Version: 1.0.0
Security: ApiKeyAuth

## Request fields (application/json):

  - `registrarId` (string)
    The unique identifier of organization supplying the registration data
    Example: "registrar-12345"

  - `registrationData` (object)
    Data required to register a candidate on the Talent Catalog.

  - `registrationData.identity` (object)
    A user of the TC system.

  - `registrationData.identity.firstName` (string)
    First name (and any middle names) of user.
    Example: "John"

  - `registrationData.identity.lastName` (string)
    The last name of the user.
    Example: "Doe"

  - `registrationData.identity.email` (string)
    The email address of the user.
    Example: "john@doe.com"

  - `registrationData.dob` (string)
    Candidate's date of birth. A date without a time-zone in the ISO-8601 calendar system.
    Example: "1985-06-15"

  - `registrationData.linkedInLink` (string)
    Candidate's LinkedIn profile URL.
    Example: "https://www.linkedin.com/in/johndoe"

  - `registrationData.phone` (string)
    Candidate's phone number.
    Example: "+1-234-567-890"

  - `registrationData.unhcrNumber` (string)
    Candidate's UNHCR number.
    Example: "12345678"

  - `registrationData.unrwaNumber` (string)
    Candidate's UNRWA number.
    Example: "12345678"

  - `registrationData.whatsapp` (string)
    Candidate's WhatsApp number.
    Example: "+1-234-567-890"

  - `registrationData.candidateCertifications` (array)
    List of certifications held by the candidate.

  - `registrationData.candidateCertifications.name` (string, required)
    The name of the certification.
    Example: "Certified Kubernetes Administrator"

  - `registrationData.candidateCertifications.institution` (string, required)
    The authority that issued the certification.
    Example: "Cloud Native Computing Foundation"

  - `registrationData.candidateCertifications.dateCompleted` (string, required)
    The date the certification was achieved.
    Example: "2024-11-27"

  - `registrationData.candidateCitizenships` (array)
    List of citizenships held by the candidate.

  - `registrationData.candidateCitizenships.hasPassport` (string)
    Whether the candidate has a passport.
    Enum: "NO_RESPONSE", "VALID_PASSPORT", "INVALID_PASSPORT", "NO_PASSPORT"

  - `registrationData.candidateCitizenships.passportExp` (string)
    The expiration date of the candidate's passport.
    Example: "2024-11-27"

  - `registrationData.candidateCitizenships.nationality` (object)

  - `registrationData.candidateCitizenships.nationality.isoCode` (string, required)
    The ISO 3166-1 alpha-2 code for the country.
    Example: "GB"

  - `registrationData.candidateCitizenships.nationality.name` (string, required)
    The name of the country.
    Example: "United Kingdom"

  - `registrationData.candidateCitizenships.nationality.status` (string, required)
    The status of the country.
    Enum: "ACTIVE", "INACTIVE", "DELETED"

  - `registrationData.candidateDestinations` (array)
    List of destinations related to the candidate.

  - `registrationData.candidateDestinations.country` (object)
    The country of the destination.

  - `registrationData.candidateDestinations.interest` (string)
    The candidate's interest in the destination.
    Enum: "NO_RESPONSE", "YES", "NO", "UNSURE"

  - `registrationData.candidateEducations` (array)
    List of educational achievements of the candidate.

  - `registrationData.candidateEducations.educationType` (string)
    The type of education.
    Enum: "ASSOCIATE", "VOCATIONAL", "BACHELOR", "MASTERS", "DOCTORAL"

  - `registrationData.candidateEducations.country` (object)

  - `registrationData.candidateEducations.educationMajor` (object)
    The major of the education.

  - `registrationData.candidateEducations.educationMajor.id` (integer)
    The unique identifier for the education major.
    Example: 8713

  - `registrationData.candidateEducations.educationMajor.iscedCode` (string)
    The ISCED code for the education major.
    Example: "0711"

  - `registrationData.candidateEducations.educationMajor.name` (string)
    The name of the education major.
    Example: "Computer Science"

  - `registrationData.candidateEducations.educationMajor.status` (string)
    The status of the education major.
    Enum: "ACTIVE", "INACTIVE", "DELETED"

  - `registrationData.candidateEducations.lengthOfCourseYears` (integer)
    The length of the course in years.
    Example: 4

  - `registrationData.candidateEducations.institution` (string)
    The institution where the education was completed.
    Example: "University of Cambridge"

  - `registrationData.candidateEducations.courseName` (string)
    The name of the course.
    Example: "Computer Science Tripos"

  - `registrationData.candidateEducations.yearCompleted` (integer)
    The year the education was completed.
    Example: 2024

  - `registrationData.candidateEducations.incomplete` (boolean)
    Whether the education was completed.

  - `registrationData.candidateExams` (array)
    List of exams taken by the candidate.

  - `registrationData.candidateExams.exam` (string)
    The type of the exam.
    Enum: "NO_RESPONSE", "OET", "OET_READ", "OET_LIST", "OET_LANG", "IELTS_GEN", "IELTS_ACA", "TOEFL", "OTHER", "DET_OFFICIAL"

  - `registrationData.candidateExams.otherExam` (string)
    The name of the exam if the exam type is "Other".
    Example: "Test of English for Aviation"

  - `registrationData.candidateExams.score` (string)
    The score of the exam.
    Example: "8.5"

  - `registrationData.candidateExams.year` (integer)
    The year the exam was taken.
    Example: 2024

  - `registrationData.candidateLanguages` (array)
    List of languages that the candidate is proficient in.

  - `registrationData.candidateLanguages.language` (object)
    The language that the candidate is proficient in.

  - `registrationData.candidateLanguages.language.isoCode` (string)
    The ISO code for the language.
    Example: "en"

  - `registrationData.candidateLanguages.language.name` (string)
    The name of the language.
    Example: "English"

  - `registrationData.candidateLanguages.language.status` (string)
    The status of the language.
    Enum: "ACTIVE", "INACTIVE", "DELETED"

  - `registrationData.candidateLanguages.writtenLevel` (object)
    The candidate's written proficiency in this language.

  - `registrationData.candidateLanguages.writtenLevel.level` (integer)
    The language proficiency level id.
    Example: 351

  - `registrationData.candidateLanguages.writtenLevel.name` (string)
    The name of the language proficiency level.
    Example: "Full Professional Proficiency"

  - `registrationData.candidateLanguages.writtenLevel.cefrLevel` (string)
    The CEFR code for the language proficiency level.
    Enum: "A1", "A2", "B1", "B2", "C1", "C2"

  - `registrationData.candidateLanguages.spokenLevel` (object)
    The candidate's spoken proficiency in this language.

  - `registrationData.candidateMessage` (string)
    Message written by the candidate.

  - `registrationData.candidateOccupations` (array)
    List of occupations related to the candidate.

  - `registrationData.candidateOccupations.occupation` (object)
    The candidate's occupation.

  - `registrationData.candidateOccupations.occupation.isco08Code` (string)
    The ISCO-08 code for the occupation.
    Example: "2411"

  - `registrationData.candidateOccupations.occupation.name` (string)
    The name of the occupation.
    Example: "Accountant"

  - `registrationData.candidateOccupations.occupation.status` (string)
    The status of the occupation.
    Enum: "ACTIVE", "INACTIVE", "DELETED"

  - `registrationData.candidateOccupations.yearsExperience` (integer)
    The number of years of experience the candidate has in this job.
    Example: 5

  - `registrationData.candidateOccupations.candidateJobExperiences` (array)
    List of job experiences of the candidate in this occupation.

  - `registrationData.candidateOccupations.candidateJobExperiences.companyName` (string)
    The name of the company where the candidate worked.
    Example: "Acme Corporation"

  - `registrationData.candidateOccupations.candidateJobExperiences.role` (string)
    The role the candidate had at the company.
    Example: "Senior Software Engineer"

  - `registrationData.candidateOccupations.candidateJobExperiences.startDate` (string)
    The date the candidate started working at the company.
    Example: "2020-11-27"

  - `registrationData.candidateOccupations.candidateJobExperiences.endDate` (string)
    The date the candidate stopped working at the company.
    Example: "2024-11-27"

  - `registrationData.candidateOccupations.candidateJobExperiences.fullTime` (boolean)
    Whether the candidate worked full-time at the company.
    Example: true

  - `registrationData.candidateOccupations.candidateJobExperiences.paid` (boolean)
    Whether the candidate was paid for their work at the company.
    Example: true

  - `registrationData.candidateOccupations.candidateJobExperiences.description` (string)
    A description of the candidate's work at the company.
    Example: "Developed new features for the company's flagship product."

  - `registrationData.candidateSkills` (array)
    List of skills possessed by the candidate.

  - `registrationData.candidateSkills.skill` (string)
    The name of the skill.
    Example: "Java"

  - `registrationData.candidateSkills.timePeriod` (string)
    The duration the candidate has been using this skill.
    Example: "5 years"

  - `registrationData.city` (string)
    City of residence
    Example: "Amman"

  - `registrationData.contactConsentTcPartners` (boolean)
    Indicates whether the candidate has given consent to be contacted by TC partners.
    Example: true

  - `registrationData.contactConsentRegistration` (boolean)
    Indicates whether the candidate has given consent to be contacted regarding their registration and employment opportunities.
    Example: true

  - `registrationData.country` (object)
    Country where candidate is currently located

  - `registrationData.gender` (string)
    Candidate's gender.
    Enum: "MALE", "FEMALE", "OTHER"

  - `registrationData.maxEducationLevel` (object)
    The maximum education level of the candidate

  - `registrationData.maxEducationLevel.level` (integer)
    The level of education.
    Example: 40

  - `registrationData.maxEducationLevel.status` (string)
    The status of the education level.
    Enum: "ACTIVE", "INACTIVE", "DELETED"

  - `registrationData.nationality` (object)
    Nationality of the candidate.

  - `registrationData.howHeardAboutUs` (string)
    How the candidate heard about the Talent Catalog.
    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"

  - `registrationData.unhcrConsent` (string)
    Indicates whether the candidate has given consent for UNHCR to be notified that they have registered on the Talent Catalog.
    Enum: "NO_RESPONSE", "YES", "NO"

  - `registrationData.yearOfArrival` (integer)
    Year of arrival in the country
    Example: 2010

## Response 201 fields (application/json):

  - `message` (string)
    Success message
    Example: "Candidate successfully registered."

  - `publicId` (string)
    The unique public ID assigned to the registered candidate
    Example: "ABcd2EFgHIjkLMNOp3QR-S"

## Response 400 fields (application/problem+json):

  - `type` (string)
    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` (string)
    A short, human-readable summary of the problem type that does not change from occurrence to  occurrence of the problem.
    Example: "Invalid Request"

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence of the problem.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "Request body is missing required fields."

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem. It may be used to  provide further context.
    Example: "/v1/candidates?page=1"

## Response 401 fields (application/problem+json):

  - `type` (string)
    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` (string)
    A short, human-readable summary of the problem type that does not change from occurrence to  occurrence of the problem.
    Example: "Authentication required"

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence of the problem.
    Example: 401

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "Invalid API key."

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem. It may be used to  provide further context.
    Example: "/v1/candidates?page=1"

## Response 403 fields (application/problem+json):

  - `type` (string)
    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` (string)
    A short, human-readable summary of the problem type that does not change from occurrence to  occurrence of the problem.
    Example: "Forbidden"

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence of the problem.
    Example: 403

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "You do not have permission to offer candidate services."

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem. It may be used to  provide further context.
    Example: "/v1/candidates?page=1"

## Response 409 fields (application/problem+json):

  - `type` (string)
    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` (string)
    A short, human-readable summary of the problem type that does not change from occurrence to  occurrence of the problem.
    Example: "Potential Duplicate"

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence of the problem.
    Example: 409

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "A candidate with this email address already exists."

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem. It may be used to  provide further context.
    Example: "/v1/candidates?page=1"

## Response 500 fields (application/problem+json):

  - `type` (string)
    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` (string)
    A short, human-readable summary of the problem type that does not change from occurrence to  occurrence of the problem.
    Example: "Service Unavailable"

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence of the problem.
    Example: 500

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: "An unexpected error occurred. Please try again later."

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem. It may be used to  provide further context.
    Example: "/v1/candidates?page=1"