Ats

Usage

Work with candidates, job postings, and applications:

import asyncio
import factorialhr

async def main():
    auth = factorialhr.AccessTokenAuth("your_access_token")
    async with factorialhr.ApiClient(auth=auth) as api:
        # List job postings and show open positions
        job_postings = factorialhr.JobPostingsEndpoint(api)
        postings = await job_postings.all()
        for job in postings.data():
            print(job.name, job.status)

        # List candidates and inspect application stage
        candidates = factorialhr.CandidatesEndpoint(api)
        response = await candidates.get(params={"limit": 10})
        for candidate in response.data():
            print(candidate.first_name, candidate.last_name)

asyncio.run(main())

Enums

class factorialhr.OriginalQuestionType(*values)

Bases: StrEnum

Enum for ATS question types.

FILE = 'file'

LONG_TEXT = 'long_text'

MULTIPLE_CHOICE = 'multiple_choice'

SINGLE_CHOICE = 'single_choice'

TEXT = 'text'

class factorialhr.PhaseType(*values)

Bases: StrEnum

Enum for ATS application phase types.

ASSESSMENT = 'assessment'

HIRED = 'hired'

INITIAL = 'initial'

INTERVIEW = 'interview'

NORMAL = 'normal'

OFFER = 'offer'

SCREENING = 'screening'

class factorialhr.Gender(*values)

Bases: StrEnum

Enum for candidate gender.

FEMALE = 'female'

MALE = 'male'

OTHER = 'other'

UNANSWERED = 'unanswered'

class factorialhr.CandidateSourceCategory(*values)

Bases: StrEnum

Enum for candidate source categories.

AGENCY_OR_EXTERNAL_RECRUITER = 'agency_or_external_recruiter'

EVENT = 'event'

INTERNAL = 'internal'

JOB_BOARD = 'job_board'

MANUALLY_ADDED = 'manually_added'

ORGANIC = 'organic'

REFERRAL = 'referral'

SOCIAL_MEDIA = 'social_media'

SYSTEM = 'system'

class factorialhr.HiringStageName(*values)

Bases: StrEnum

Enum for hiring stage names.

ASSESSMENT = 'assessment'

HIRED = 'hired'

INTERVIEW = 'interview'

NEW = 'new'

OFFER = 'offer'

SCREENING = 'screening'

class factorialhr.ContractType(*values)

Bases: StrEnum

Enum for job posting contract types.

ALTERNANT = 'alternant'

APPRENDISTATO = 'apprendistato'

APPRENTICESHIP = 'apprenticeship'

APPRENTISSAGE = 'apprentissage'

A_TEMPO_PARCIAL = 'a_tempo_parcial'

A_TERMO_CERTO = 'a_termo_certo'

A_TERMO_INCERTO = 'a_termo_incerto'

CLT = 'clt'

COM_PLURALIDADE_DE_EMPREGADORES = 'com_pluralidade_de_empregadores'

DE_CURTA_DURACAO = 'de_curta_duracao'

DE_MUITA_CURTA_DURACAO = 'de_muita_curta_duracao'

ESTAGIO = 'estagio'

FIXED_DISCONTINUED = 'fixed_discontinued'

FREELANCE = 'freelance'

INDEFINITE = 'indefinite'

INTERIM = 'interim'

INTERN = 'intern'

JOVEM_APRENDIZ = 'jovem_aprendiz'

MINIJOB = 'minijob'

OTHER = 'other'

PER_HOUR = 'per_hour'

PJ = 'pj'

PRE_REFORMA = 'pre_reforma'

PROMESSA_DE_TRABALHO = 'promessa_de_trabalho'

RECIBOS_VERDES = 'recibos_verdes'

SEM_TERMO = 'sem_termo'

TELETRABALHO = 'teletrabalho'

TEMPORARY = 'temporary'

TRAINING = 'training'

VENDOR_CONTRACTOR = 'vendor_contractor'

VOLUNTEER = 'volunteer'

WERKSTUDENT = 'werkstudent'

class factorialhr.WorkplaceType(*values)

Bases: StrEnum

Enum for job posting workplace types.

HYBRID = 'hybrid'

ONSITE = 'onsite'

REMOTE = 'remote'

class factorialhr.JobPostingStatus(*values)

Bases: StrEnum

Enum for job posting status.

ARCHIVED = 'archived'

CANCELLED = 'cancelled'

DRAFT = 'draft'

PUBLISHED = 'published'

UNLISTED = 'unlisted'

class factorialhr.ScheduleType(*values)

Bases: StrEnum

Enum for job posting schedule types.

FULL_TIME = 'full_time'

PART_TIME = 'part_time'

class factorialhr.SalaryFormat(*values)

Bases: StrEnum

Enum for salary format.

FIXED_AMOUNT = 'fixed_amount'

RANGE = 'range'

class factorialhr.RequirementLevel(*values)

Bases: StrEnum

Enum for requirement levels.

DO_NOT_ASK = 'do_not_ask'

MANDATORY = 'mandatory'

OPTIONAL = 'optional'

class factorialhr.SalaryPeriod(*values)

Bases: StrEnum

Enum for salary periods.

ANNUAL = 'annual'

DAILY = 'daily'

MONTHLY = 'monthly'

class factorialhr.DecisionMaker(*values)

Bases: StrEnum

Enum for rejection reason decision maker.

CANDIDATE = 'candidate'

COMPANY = 'company'

Models and endpoints

class factorialhr.Answer(*, id: int, ats_question_id: int | None = None, ats_application_id: int, original_question_label: str, value: str | None = None, original_question_type: OriginalQuestionType, created_at: datetime, updated_at: datetime)

Model for ats_answer.

ats_application_id: int

Identifier of the application

ats_question_id: int | None

Identifier of the question

created_at: datetime

Created date of the answer

id: int

Identifier of the answer

original_question_label: str

Question label of the answer

original_question_type: OriginalQuestionType

Original type of the question

updated_at: datetime

Last updated date of the answer

value: str | None

Value of the answer

class factorialhr.AnswersEndpoint(api: ApiClient)

async all(**kwargs) → ListApiResponse[Answer]

Get all answers.

Official documentation: ats/answers

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing the list of answers.

Return type:

ListApiResponse[Answer]

async create(data: Mapping[str, Any], **kwargs) → Answer

Create an answer.

Official documentation: ats/answers

Parameters:

• data (Mapping[str, Any]) – Payload for the new answer (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created answer record.

Return type:

Answer

async get(**kwargs) → MetaApiResponse[Answer]

Get answers with pagination metadata.

Official documentation: ats/answers

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing answers and pagination metadata.

Return type:

MetaApiResponse[Answer]

async get_by_id(answer_id: int | str, **kwargs) → Answer

Get a specific answer by ID.

Official documentation: ats/answers

Parameters:

• answer_id (int | str) – The unique identifier of the answer.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The answer record.

Return type:

Answer

class factorialhr.Application(*, id: int, company_id: int, ats_job_posting_id: int, ats_candidate_id: int, employee_id: int | None = None, phone: str | None = None, qualified: bool | None = None, ats_application_phase_id: int | None = None, created_at: datetime, cover_letter: str | None = None, ats_conversation_id: int | None = None, medium: str | None = None, rating_average: int | None = None, ats_rejection_reason_id: int | None = None, source_id: int | None = None)

Model for ats_application.

ats_application_phase_id: int | None

Application phase id

ats_candidate_id: int

Candidate id of the application

ats_conversation_id: int | None

Application conversation id

ats_job_posting_id: int

Job posting id of the application

ats_rejection_reason_id: int | None

Application rejection reason id

company_id: int

Company id of the application

cover_letter: str | None

Application cover letter

created_at: datetime

Application created at date

employee_id: int | None

Employee id of the application

id: int

Id of the application

medium: str | None

Application medium

phone: str | None

Candidate phone of the application

qualified: bool | None

Qualified of the application

rating_average: int | None

Application average rating

source_id: int | None

Application source id

class factorialhr.ApplicationPhase(*, id: int, ats_job_posting_id: int, name: str, position: int, editable: bool, phase_type: PhaseType, applications_count: int | None = None, active_applications_count: int | None = None, ats_hiring_stage_id: int | None = None)

Model for ats_application_phase.

active_applications_count: int | None

Active applications count

applications_count: int | None

Active application count

ats_hiring_stage_id: int | None

Hiring stage identifier

ats_job_posting_id: int

Job posting of the application phase

editable: bool

If the application phase is editable

id: int

Identifier of the application Phase

name: str

Name of the application phase

phase_type: PhaseType

Application phase type

position: int

Position of the application phase

class factorialhr.ApplicationPhasesEndpoint(api: ApiClient)

async all(**kwargs) → ListApiResponse[ApplicationPhase]

Get all application phases.

Official documentation: ats/application_phases

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing the list of application phases.

Return type:

ListApiResponse[ApplicationPhase]

async get(**kwargs) → MetaApiResponse[ApplicationPhase]

Get application phases with pagination metadata.

Official documentation: ats/application_phases

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing application phases and pagination metadata.

Return type:

MetaApiResponse[ApplicationPhase]

async get_by_id(application_phase_id: int | str, **kwargs) → ApplicationPhase

Get a single application phase by ID.

Official documentation: ats/application_phases

Parameters:

• application_phase_id (int | str) – The unique identifier of the application phase.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The application phase record.

Return type:

ApplicationPhase

class factorialhr.ApplicationsEndpoint(api: ApiClient)

async all(**kwargs) → ListApiResponse[Application]

Get all applications.

Official documentation: ats/applications

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing the list of applications.

Return type:

ListApiResponse[Application]

async apply(data: Mapping[str, Any], **kwargs) → Application

Apply to an application.

Official documentation: ats/applications

Parameters:

• data (Mapping[str, Any]) – Payload for the apply action (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The application record resulting from the apply action.

Return type:

Application

async create(data: Mapping[str, Any], **kwargs) → Application

Create an application.

Official documentation: ats/applications

Parameters:

• data (Mapping[str, Any]) – Payload for the new application (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created application record.

Return type:

Application

async delete(application_id: int | str, **kwargs) → Application

Delete an application.

Official documentation: ats/applications

Parameters:

• application_id (int | str) – The unique identifier of the application to delete.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The deleted application record.

Return type:

Application

async get(**kwargs) → MetaApiResponse[Application]

Get applications with pagination metadata.

Official documentation: ats/applications

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing applications and pagination metadata.

Return type:

MetaApiResponse[Application]

async get_by_id(application_id: int | str, **kwargs) → Application

Get a specific application by ID.

Official documentation: ats/applications

Parameters:

• application_id (int | str) – The unique identifier of the application.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The application record.

Return type:

Application

async update(application_id: int | str, data: Mapping[str, Any], **kwargs) → Application

Update an application.

Official documentation: ats/applications

Parameters:

• application_id (int | str) – The unique identifier of the application to update.

• data (Mapping[str, Any]) – Payload with fields to update (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The updated application record.

Return type:

Application

class factorialhr.Candidate(*, id: int, company_id: int | None = None, first_name: str, last_name: str, full_name: str, email: str | None = None, talent_pool: bool, phone_number: str | None = None, created_at: datetime, updated_at: datetime, consent_given_at: datetime | None = None, inactive_since: datetime | None = None, ats_job_posting_ids: Sequence[int] | None = None, personal_url: str | None = None, consent_expiration_date: datetime | None = None, consent_to_talent_pool: bool | None = None, medium: str | None = None, source_id: int | None = None, gender: Gender | None = None, score: float | None = None)

Model for ats_candidate.

ats_job_posting_ids: Sequence[int] | None

List of job posting identifiers

company_id: int | None

Company identifier

consent_expiration_date: datetime | None

Date when the consent expires

consent_given_at: datetime | None

Date when the consent was given

consent_to_talent_pool: bool | None

Consent to talent pool

created_at: datetime

Creation date of the candidate

email: str | None

Email of the candidate

first_name: str

Name of the candidate

full_name: str

Full name of the candidate

gender: Gender | None

Gender of the candidate

id: int

Identifier of the candidate

inactive_since: datetime | None

Date when the candidate became inactive

last_name: str

Last name of the candidate

medium: str | None

Specifies additional details related to the source of the candidate, such as the referrer name for example if the source is referred

personal_url: str | None

Personal web resource from the candidate

phone_number: str | None

Phone number of the candidate

score: float | None

Score of the candidate

source_id: int | None

Candidate source identifier, refers to ats/candidate_sources endpoint

talent_pool: bool

Is the candidate part of talent pool?

updated_at: datetime

Last update of the candidate

class factorialhr.CandidatesEndpoint(api: ApiClient)

async all(**kwargs) → ListApiResponse[Candidate]

Get all candidates.

Official documentation: ats/candidates

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing the list of candidates.

Return type:

ListApiResponse[Candidate]

async create(data: Mapping[str, Any], **kwargs) → Candidate

Create a candidate.

Official documentation: ats/candidates

Parameters:

• data (Mapping[str, Any]) – Payload for the new candidate (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created candidate record.

Return type:

Candidate

async delete(candidate_id: int | str, **kwargs) → Candidate

Delete a candidate.

Official documentation: ats/candidates

Parameters:

• candidate_id (int | str) – The unique identifier of the candidate to delete.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The deleted candidate record.

Return type:

Candidate

async get(**kwargs) → MetaApiResponse[Candidate]

Get candidates with pagination metadata.

Official documentation: ats/candidates

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing candidates and pagination metadata.

Return type:

MetaApiResponse[Candidate]

async get_by_id(candidate_id: int | str, **kwargs) → Candidate

Get a single candidate by ID.

Official documentation: ats/candidates

Parameters:

• candidate_id (int | str) – The unique identifier of the candidate.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The candidate record.

Return type:

Candidate

async update(candidate_id: int | str, data: Mapping[str, Any], **kwargs) → Candidate

Update a candidate.

Official documentation: ats/candidates

Parameters:

• candidate_id (int | str) – The unique identifier of the candidate to update.

• data (Mapping[str, Any]) – Payload with fields to update (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The updated candidate record.

Return type:

Candidate

class factorialhr.CandidateSource(*, id: int, company_id: int, category: CandidateSourceCategory, name: str, label: str)

Model for ats_candidate_source.

category: CandidateSourceCategory

Category of the source

company_id: int

Identifier of the company

id: int

Identifier of the source

label: str

Translated label of the source if it is a default one, or name otherwise

name: str

Name of the source

class factorialhr.CandidateSourcesEndpoint(api: ApiClient)

async all(**kwargs) → ListApiResponse[CandidateSource]

Get all candidate sources.

Official documentation: ats/candidate_sources

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing the list of candidate sources.

Return type:

ListApiResponse[CandidateSource]

async get(**kwargs) → MetaApiResponse[CandidateSource]

Get candidate sources with pagination metadata.

Official documentation: ats/candidate_sources

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing candidate sources and pagination metadata.

Return type:

MetaApiResponse[CandidateSource]

async get_by_id(candidate_source_id: int | str, **kwargs) → CandidateSource

Get a single candidate source by ID.

Official documentation: ats/candidate_sources

Parameters:

• candidate_source_id (int | str) – The unique identifier of the candidate source.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The candidate source record.

Return type:

CandidateSource

class factorialhr.EvaluationForm(*, id: int, company_id: int, ats_job_posting_id: int | None = None, name: str, based_on_id: int | None = None, questions: Sequence[Any], created_at: datetime, updated_at: datetime)

Model for ats_evaluation_form.

ats_job_posting_id: int | None

Id of the job posting that the evaluation form is associated with

based_on_id: int | None

Id of the evaluation form that this evaluation form is related

company_id: int

Id of the company that the evaluation form belongs to

created_at: datetime

Date and time when the evaluation form was created

id: int

Id of the evaluation form

name: str

Name of the evaluation form

questions: Sequence[Any]

List of questions in the evaluation form

updated_at: datetime

Date and time when the evaluation form was last updated

class factorialhr.EvaluationFormsEndpoint(api: ApiClient)

async all(**kwargs) → ListApiResponse[EvaluationForm]

Get all evaluation forms.

Official documentation: ats/evaluation_forms

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing the list of evaluation forms.

Return type:

ListApiResponse[EvaluationForm]

async get(**kwargs) → MetaApiResponse[EvaluationForm]

Get evaluation forms with pagination metadata.

Official documentation: ats/evaluation_forms

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing evaluation forms and pagination metadata.

Return type:

MetaApiResponse[EvaluationForm]

async get_by_id(evaluation_form_id: int | str, **kwargs) → EvaluationForm

Get a single evaluation form by ID.

Official documentation: ats/evaluation_forms

Parameters:

• evaluation_form_id (int | str) – The unique identifier of the evaluation form.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The evaluation form record.

Return type:

EvaluationForm

async save_as_template(data: Mapping[str, Any], **kwargs) → EvaluationForm

Save the evaluation form as a template.

Official documentation: ats/evaluation_forms

Parameters:

• data (Mapping[str, Any]) – Payload for saving as template (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The evaluation form record saved as template.

Return type:

EvaluationForm

class factorialhr.Feedback(*, id: int, rating: int | None = None, description: str | None = None, ats_application_id: int | None = None, ats_application_phase_id: int | None = None, created_at: datetime, ats_candidate_id: int, ats_evaluation_forms_id: int | None = None, evaluation_form_answers: Sequence[Any] | None = None)

Model for ats_feedback.

ats_application_id: int | None

The ID of the application related to the feedback

ats_application_phase_id: int | None

The ID of the phase within the application related to the feedback

ats_candidate_id: int

The ID of the candidate to whom the feedback is associated

ats_evaluation_forms_id: int | None

The ID of the evaluation form to which the feedback belongs if the evaluation forms feature is active

created_at: datetime

The date and time when the feedback entry was created

description: str | None

The description of the feedback provided

evaluation_form_answers: Sequence[Any] | None

The answers from the evaluation form, if this feedback is related to an evaluation form

id: int

The ID of the feedback entry

rating: int | None

The overall rating from 1 to 5 for the candidate’s application

class factorialhr.FeedbacksEndpoint(api: ApiClient)

async all(**kwargs) → ListApiResponse[Feedback]

Get all feedbacks.

Official documentation: ats/feedbacks

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing the list of feedbacks.

Return type:

ListApiResponse[Feedback]

async create(data: Mapping[str, Any], **kwargs) → Feedback

Create a feedback.

Official documentation: ats/feedbacks

Parameters:

• data (Mapping[str, Any]) – Payload for the new feedback (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created feedback record.

Return type:

Feedback

async delete(feedback_id: int | str, **kwargs) → Feedback

Delete a feedback.

Official documentation: ats/feedbacks

Parameters:

• feedback_id (int | str) – The unique identifier of the feedback to delete.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The deleted feedback record.

Return type:

Feedback

async get(**kwargs) → MetaApiResponse[Feedback]

Get feedbacks with pagination metadata.

Official documentation: ats/feedbacks

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing feedbacks and pagination metadata.

Return type:

MetaApiResponse[Feedback]

async get_by_id(feedback_id: int | str, **kwargs) → Feedback

Get a single feedback by ID.

Official documentation: ats/feedbacks

Parameters:

• feedback_id (int | str) – The unique identifier of the feedback.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The feedback record.

Return type:

Feedback

async update(feedback_id: int | str, data: Mapping[str, Any], **kwargs) → Feedback

Update a feedback.

Official documentation: ats/feedbacks

Parameters:

• feedback_id (int | str) – The unique identifier of the feedback to update.

• data (Mapping[str, Any]) – Payload with fields to update (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The updated feedback record.

Return type:

Feedback

class factorialhr.HiringStage(*, id: int, name: HiringStageName, label: str, company_id: int, position: int)

Model for ats_hiring_stage.

company_id: int

Company identifier of the hiring stage

id: int

Identifier of the hiring stage

label: str

Label of the hiring stage

name: HiringStageName

Name of the hiring stage

position: int

Position of the hiring stage

class factorialhr.HiringStagesEndpoint(api: ApiClient)

async all(**kwargs) → ListApiResponse[HiringStage]

Get all hiring stages.

Official documentation: ats/hiring_stages

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing the list of hiring stages.

Return type:

ListApiResponse[HiringStage]

async get(**kwargs) → MetaApiResponse[HiringStage]

Get hiring stages with pagination metadata.

Official documentation: ats/hiring_stages

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing hiring stages and pagination metadata.

Return type:

MetaApiResponse[HiringStage]

async get_by_id(hiring_stage_id: int | str, **kwargs) → HiringStage

Get a single hiring stage by ID.

Official documentation: ats/hiring_stages

Parameters:

• hiring_stage_id (int | str) – The unique identifier of the hiring stage.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The hiring stage record.

Return type:

HiringStage

class factorialhr.JobPosting(*, id: int, company_id: int, ats_company_id: int, title: str, description: str | None = None, contract_type: ContractType | None = None, workplace_type: WorkplaceType | None = None, remote: bool, status: JobPostingStatus, schedule_type: ScheduleType | None = None, team_id: int | None = None, location_id: int | None = None, legal_entity_id: int | None = None, salary_format: SalaryFormat | None = None, salary_from_amount_in_cents: int | None = None, salary_to_amount_in_cents: int | None = None, hide_salary: bool | None = None, cv_requirement: RequirementLevel, cover_letter_requirement: RequirementLevel, phone_requirement: RequirementLevel, photo_requirement: RequirementLevel, preview_token: str | None = None, url: str | None = None, salary_period: SalaryPeriod, published_at: datetime | None = None, created_at: datetime)

Model for ats_job_posting.

ats_company_id: int

Identifier of the ATS company associated with the job posting

company_id: int

Company identifier

contract_type: ContractType | None

Contract type of the job posting

cover_letter_requirement: RequirementLevel

Requirement for the cover letter

created_at: datetime

Date in ISO 8601 format when the job posting was created

cv_requirement: RequirementLevel

Requirement for the CV

description: str | None

Description of the job posting

hide_salary: bool | None

Indicates whether the salary information for the job posting should be hidden from applicants

id: int

Unique identifier for the job posting

legal_entity_id: int | None

Identifier of the legal entity associated with the job posting

location_id: int | None

Identifier of the location associated with the job posting

phone_requirement: RequirementLevel

Requirement for the phone number

photo_requirement: RequirementLevel

Requirement for the photo

preview_token: str | None

Preview token for the job posting

published_at: datetime | None

Published date in ISO 8601 format of the job. If never been published the value will be null

remote: bool

Indicates if the job posting is remote

salary_format: SalaryFormat | None

The format of the salary

salary_from_amount_in_cents: int | None

The minimum salary amount in cents

salary_period: SalaryPeriod

Salary period

salary_to_amount_in_cents: int | None

The maximum salary amount in cents

schedule_type: ScheduleType | None

The schedule type of the job posting

status: JobPostingStatus

The current status of the job posting

team_id: int | None

Identifier of the team associated with the job posting

title: str

Title of the job posting

url: str | None

If published, the public URL of the job posting. Otherwise will be null

workplace_type: WorkplaceType | None

Workplace type of the job posting

class factorialhr.JobPostingsEndpoint(api: ApiClient)

async all(**kwargs) → ListApiResponse[JobPosting]

Get all job postings.

Official documentation: ats/job_postings

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing the list of job postings.

Return type:

ListApiResponse[JobPosting]

async create(data: Mapping[str, Any], **kwargs) → JobPosting

Create a job posting.

Official documentation: ats/job_postings

Parameters:

• data (Mapping[str, Any]) – Payload for the new job posting (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created job posting record.

Return type:

JobPosting

async delete(job_posting_id: int | str, **kwargs) → JobPosting

Delete a job posting.

Official documentation: ats/job_postings

Parameters:

• job_posting_id (int | str) – The unique identifier of the job posting to delete.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The deleted job posting record.

Return type:

JobPosting

async duplicate(data: Mapping[str, Any], **kwargs) → JobPosting

Duplicate a job posting.

Official documentation: ats/job_postings

Parameters:

• data (Mapping[str, Any]) – Payload for the duplicate action (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The duplicated job posting record.

Return type:

JobPosting

async get(**kwargs) → MetaApiResponse[JobPosting]

Get job postings with pagination metadata.

Official documentation: ats/job_postings

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing job postings and pagination metadata.

Return type:

MetaApiResponse[JobPosting]

async get_by_id(job_posting_id: int | str, **kwargs) → JobPosting

Get a single job posting by ID.

Official documentation: ats/job_postings

Parameters:

• job_posting_id (int | str) – The unique identifier of the job posting.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The job posting record.

Return type:

JobPosting

async update(job_posting_id: int | str, data: Mapping[str, Any], **kwargs) → JobPosting

Update a job posting.

Official documentation: ats/job_postings

Parameters:

• job_posting_id (int | str) – The unique identifier of the job posting to update.

• data (Mapping[str, Any]) – Payload with fields to update (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The updated job posting record.

Return type:

JobPosting

class factorialhr.Message(*, id: int, content: str, ats_conversation_id: int, sent_by_id: int, sent_by_type: str, created_at: datetime, attachments: Sequence[Any], topic: str, delayed_until: datetime | None = None, sent_at: datetime | None = None, delivered_at: datetime | None = None, opened_at: datetime | None = None, last_error_at: datetime | None = None)

Model for ats_message.

ats_conversation_id: int

Conversation identifier

attachments: Sequence[Any]

Message attachments

content: str

Message content

created_at: datetime

Message creation date

delayed_until: datetime | None

Delayed until date

delivered_at: datetime | None

Delivered at date

id: int

Message identifier

last_error_at: datetime | None

Last error at date

opened_at: datetime | None

Opened at date

sent_at: datetime | None

Sent at date

sent_by_id: int

Sender identifier

sent_by_type: str

Sender type

topic: str

Message topic

class factorialhr.MessagesEndpoint(api: ApiClient)

async all(**kwargs) → ListApiResponse[Message]

Get all messages.

Official documentation: ats/messages

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing the list of messages.

Return type:

ListApiResponse[Message]

async create(data: Mapping[str, Any], **kwargs) → Message

Create a message.

Official documentation: ats/messages

Parameters:

• data (Mapping[str, Any]) – Payload for the new message (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created message record.

Return type:

Message

async get(**kwargs) → MetaApiResponse[Message]

Get messages with pagination metadata.

Official documentation: ats/messages

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing messages and pagination metadata.

Return type:

MetaApiResponse[Message]

async get_by_id(message_id: int | str, **kwargs) → Message

Get a single message by ID.

Official documentation: ats/messages

Parameters:

• message_id (int | str) – The unique identifier of the message.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The message record.

Return type:

Message

class factorialhr.Question(*, id: int, ats_job_posting_id: int, label: str, position: int, mandatory: bool, auto_disqualify: bool, question_type: OriginalQuestionType, created_at: datetime, updated_at: datetime, options: Sequence[Any] | None = None)

Model for ats_question.

ats_job_posting_id: int

Job posting identifier

auto_disqualify: bool

If the question autodisqualifies the candidate depending on its response

created_at: datetime

Creation date

id: int

Question identifier

label: str

Text of the question

mandatory: bool

Is the question mandatory or not

options: Sequence[Any] | None

Options for the question

position: int

Position of the question in the list

question_type: OriginalQuestionType

Type of the question

updated_at: datetime

Last update date

class factorialhr.QuestionsEndpoint(api: ApiClient)

async all(**kwargs) → ListApiResponse[Question]

Get all questions.

Official documentation: ats/questions

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing the list of questions.

Return type:

ListApiResponse[Question]

async create(data: Mapping[str, Any], **kwargs) → Question

Create a question.

Official documentation: ats/questions

Parameters:

• data (Mapping[str, Any]) – Payload for the new question (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created question record.

Return type:

Question

async delete(question_id: int | str, **kwargs) → Question

Delete a question.

Official documentation: ats/questions

Parameters:

• question_id (int | str) – The unique identifier of the question to delete.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The deleted question record.

Return type:

Question

async get(**kwargs) → MetaApiResponse[Question]

Get questions with pagination metadata.

Official documentation: ats/questions

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing questions and pagination metadata.

Return type:

MetaApiResponse[Question]

async get_by_id(question_id: int | str, **kwargs) → Question

Get a single question by ID.

Official documentation: ats/questions

Parameters:

• question_id (int | str) – The unique identifier of the question.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The question record.

Return type:

Question

async update(question_id: int | str, data: Mapping[str, Any], **kwargs) → Question

Update a question.

Official documentation: ats/questions

Parameters:

• question_id (int | str) – The unique identifier of the question to update.

• data (Mapping[str, Any]) – Payload with fields to update (key-value mapping).

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The updated question record.

Return type:

Question

class factorialhr.RejectionReason(*, id: int, company_id: int, decision_maker: DecisionMaker, reason: str, created_at: datetime, updated_at: datetime)

Model for ats_rejection_reason.

company_id: int

Company identifier of the rejection reason

created_at: datetime

Rejection reason created date

decision_maker: DecisionMaker

Decision maker of the rejection reason

id: int

Rejection reason identifier

reason: str

Reason of the rejection

updated_at: datetime

Rejection reason updated date

class factorialhr.RejectionReasonsEndpoint(api: ApiClient)

async all(**kwargs) → ListApiResponse[RejectionReason]

Get all rejection reasons.

Official documentation: ats/rejection_reasons

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing the list of rejection reasons.

Return type:

ListApiResponse[RejectionReason]

async get(**kwargs) → MetaApiResponse[RejectionReason]

Get rejection reasons with pagination metadata.

Official documentation: ats/rejection_reasons

Parameters:

kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

Response containing rejection reasons and pagination metadata.

Return type:

MetaApiResponse[RejectionReason]

async get_by_id(rejection_reason_id: int | str, **kwargs) → RejectionReason

Get a single rejection reason by ID.

Official documentation: ats/rejection_reasons

Parameters:

• rejection_reason_id (int | str) – The unique identifier of the rejection reason.

• kwargs (optional) – Optional keyword arguments forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The rejection reason record.

Return type:

RejectionReason