# Talent Catalog API

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
License: Gnu Affero General Public License

## Servers

Staging server
```
https://test.api.tctalent.org
```

Production server
```
https://api.tctalent.org
```

## Security

### ApiKeyAuth

Type: apiKey
In: header
Name: X-API-KEY

## Download OpenAPI description

[Talent Catalog API](https://tc-api.redocly.app/_bundle/openapi.yaml)

## Candidates

Operations related to anonymised candidates.

### Retrieve a page of anonymised candidates

 - [GET /v1/candidates](https://tc-api.redocly.app/openapi/candidates/findcandidates.md): Fetches a paginated array of anonymised candidates. Optionally filter candidates by their ISCO (International Standard Classification of Occupations) codes.

### Retrieve an anonymised candidate by candidate public ID

 - [GET /v1/candidates/{publicId}](https://tc-api.redocly.app/openapi/candidates/getcandidatebypublicid.md): Fetches details of an anonymised candidate by their unique public candidate ID.

### Retrieve a page of anonymised candidates in a saved list

 - [GET /v1/candidates/by-list/{publicListId}](https://tc-api.redocly.app/openapi/candidates/getcandidatesbypubliclistid.md): Fetches a paginated array of anonymised candidates belonging to a specific saved list, identified by its public ID.

### Expression of interest in candidates for a job

 - [POST /v1/candidates/job-match](https://tc-api.redocly.app/openapi/candidates/jobmatch.md): 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.

### Offer to assist candidates

 - [POST /v1/candidates/offer-to-assist](https://tc-api.redocly.app/openapi/candidates/offertoassistcandidates.md): 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.

### Register a candidate with the Talent Catalog

 - [POST /v1/candidates/register](https://tc-api.redocly.app/openapi/candidates/registercandidate.md): 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.