Connecting to Factorial

Authentication

Factorial uses OAuth 2.0 for authentication to connect to your HR data or to allow other users to connect to their data.

Using OAuth Authentication

To connect using OAuth, follow these steps:

Navigate to your Factorial admin panel and create a new OAuth application.
Copy the Client ID and Client Secret from your application configuration.
Configure the following connection properties:

After setting the following connection properties, you are ready to connect:

AuthScheme: Set this to OAuth.
OAuthClientId: Set this to your OAuth Client ID.
OAuthClientSecret: Set this to your OAuth Client Secret.
Scope: Set this to specify the data access permissions (default: "read write").

Available Tables

The Factorial API Profile provides access to comprehensive human resources management and business data across 51 specialized tables:

Agreements - Access performance review agreements between managers and employees with signature tracking and evaluation data.
Allowances - Query time-off allowance configurations including accrual rules, carry-over policies, and holiday settings.
Applications - Retrieve job application records with candidate information, hiring stages, and recruitment workflow data.
BankAccount - Access employee bank account information including IBAN details, balance data, and payment configurations.
BreakConfiguration - Query break management configurations with paid/unpaid status and active settings.
Candidates - Access job candidate profiles with contact information, qualifications, and application history.
Categories - Retrieve expense categories and classification data for organizational budgeting and reporting.
Compensations - Query employee compensation data including salaries, bonuses, and benefit information.
Concepts - Access payroll concept definitions and calculation rules for salary processing.
ContractTemplates - Retrieve standardized employee contract templates and legal document frameworks.
ContractVersions - Access contract version history with detailed terms, conditions, and amendment tracking.
CostCenters - Query organizational cost center data for budget allocation and expense tracking.
DayConfiguration - Access working day configuration settings including schedules and time zone management.
Documents - Retrieve employee and company document management records with file attachments and metadata.
Employees - Access core employee data including personal information, job roles, and organizational hierarchy.
Expenses - Query employee expense records with receipts, approvals, and reimbursement tracking.
Field - Access custom field definitions and configuration data for extended data capture.
FinancialDocuments - Retrieve financial document records including invoices, receipts, and payment documentation.
Folders - Access document folder organization structure for file management and categorization.
HiringStages - Query recruitment process stages and workflow configurations for candidate management.
JobLevels - Access job level and hierarchy definitions for organizational structure management.
JobPostings - Retrieve job posting data including requirements, descriptions, and application settings.
JobRoles - Query job role definitions including responsibilities, requirements, and competency frameworks.
Leaves - Access employee leave requests and time-off records with approval workflow data.
LeaveTypes - Query leave type configurations including policies, accrual rules, and approval requirements.
LegalEntities - Access company legal entity information including registration details and compliance data.
Locations - Retrieve office and work location data including addresses, time zones, and facility information.
Memberships - Query employee group and team memberships for organizational structure and access control.
Mileage - Access employee mileage tracking data for travel reimbursements and expense management.
OpenShifts - Retrieve available shift data for scheduling and workforce management.
OvertimeRequests - Query employee overtime requests with approval status and compensation tracking.
PayrollFamilySituations - Access employee family status information for payroll tax calculations and benefits.
PayrollSupplements - Retrieve payroll supplement data including bonuses, allowances, and additional compensation.
PerDiem - Query per diem allowances and travel expense configurations for business trip management.
Policies - Access company policies and procedure definitions including HR rules and compliance frameworks.
Projects - Retrieve project management data including timelines, budgets, and resource allocation.
ProjectTasks - Access individual project tasks with assignments, deadlines, and completion tracking.
ReferenceContracts - Query reference contract templates and standardized agreement frameworks.
RejectionReasons - Retrieve candidate rejection reason codes for recruitment process improvement.
ReviewEvaluations - Access performance review evaluation data with scoring and assessment details.
ReviewEvaluationScores - Query detailed performance review scoring data with competency breakdowns.
ReviewProcesses - Retrieve performance review process configurations including cycles and evaluation criteria.
Schedule - Access employee work schedules with shift patterns, availability, and calendar integration.
Shifts - Query work shift definitions including timing, break configurations, and assignment rules.
Tasks - Access general task management data with assignments, priorities, and completion tracking.
Teams - Retrieve team structure and membership data for organizational hierarchy management.
TimeRecord - Query employee time tracking and attendance records with clock-in/out data.
Trainings - Access training program data including courses, certifications, and skill development tracking.
TrainingSessions - Retrieve individual training session records with attendance and completion data.
Transaction - Query financial transaction records including payroll, expenses, and reimbursements.
Value - Access custom value definitions and configuration data for extended business logic.
WorkedTime - Retrieve detailed worked time tracking data with project allocation and billing information.

Usage Examples

Query performance review agreements by process:

SELECT * FROM Agreements WHERE ProcessId = 123

Query time-off allowances by policy:

SELECT * FROM Allowances WHERE TimeoffPolicyId = 456

Query job applications by candidate:

SELECT * FROM Applications WHERE AtsCandidateId = 789

Query bank accounts by currency:

SELECT * FROM BankAccount WHERE Currency = 'EUR'

Query break configurations:

SELECT * FROM BreakConfiguration WHERE IsActive = true

Query candidates by job posting:

SELECT * FROM Candidates WHERE AtsJobPostingIds = 123

Query expense categories by parent:

SELECT * FROM Categories WHERE ParentCategoryId = 456

Query employee compensation by contract:

SELECT * FROM Compensations WHERE ContractVersionId = 789

Query payroll concepts by category:

SELECT * FROM Concepts WHERE Category = 'salary'

Query contract templates by company:

SELECT * FROM ContractTemplates WHERE CompanyId = 123

Query contract versions by employee:

SELECT * FROM ContractVersions WHERE EmployeeId = 456

Query cost centers by company:

SELECT * FROM CostCenters WHERE CompanyId = 789

Query day configurations by overlap period:

SELECT * FROM DayConfiguration WHERE OverlapPeriodId = 123

Query documents by employee:

SELECT * FROM Documents WHERE EmployeeId = 456

Query employees by legal entity:

SELECT * FROM Employees WHERE LegalEntityId = 789

Query expenses by employee:

SELECT * FROM Expenses WHERE EmployeeId = 123

Query custom fields by type:

SELECT * FROM Field WHERE FieldType = 'text'

Query financial documents by status:

SELECT * FROM FinancialDocuments WHERE Status = 'approved'

Query document folders by status:

SELECT * FROM Folders WHERE IsActive = 'true'

Query hiring stages by company:

SELECT * FROM HiringStages WHERE CompanyId = 456

Query job levels by role:

SELECT * FROM JobLevels WHERE RoleId = 789

Query job postings by status:

SELECT * FROM JobPostings WHERE Status = 'published'

Query job roles:

SELECT * FROM JobRoles

Query leaves by employee and date range:

SELECT * FROM Leaves WHERE EmployeeId = 123 AND StartOn >= '2026-01-01'

Query leave types by company:

SELECT * FROM LeaveTypes WHERE CompanyId = 456

Query legal entities by country:

SELECT * FROM LegalEntities WHERE Country = 'ES'

Query office locations:

SELECT * FROM Locations WHERE Main = 'true'

Query team memberships by employee:

SELECT * FROM Memberships WHERE EmployeeId = 789

Query mileage expenses by employee:

SELECT * FROM Mileage WHERE EmployeeId = 123

Query open shifts by employee:

SELECT * FROM OpenShifts WHERE EmployeeId = 456

Query overtime requests by status:

SELECT * FROM OvertimeRequests WHERE Status = 'approved'

Query payroll family situations by employee:

SELECT * FROM PayrollFamilySituations WHERE EmployeeId = 789

Query payroll supplements by employee:

SELECT * FROM PayrollSupplements WHERE EmployeeId = 123

Query per diem expenses:

SELECT * FROM PerDiem WHERE ExpensesExpensableId = 456

Query company policies:

SELECT * FROM Policies WHERE CompanyId = 789

Query projects by name:

SELECT * FROM Projects WHERE Name = 'Marketing Campaign'

Query project tasks by project:

SELECT * FROM ProjectTasks WHERE ProjectId = 123

Query reference contracts by employee:

SELECT * FROM ReferenceContracts WHERE EmployeeId = 456

Query rejection reasons by company:

SELECT * FROM RejectionReasons WHERE CompanyId = 789

Query review evaluations by process:

SELECT * FROM ReviewEvaluations WHERE PerformanceReviewProcessId = 123

Query review evaluation scores by process:

SELECT * FROM ReviewEvaluationScores WHERE ReviewProcessId = 456

Query review processes:

SELECT * FROM ReviewProcesses

Query work schedules:

SELECT * FROM Schedule

Query employee shifts by date:

SELECT * FROM Shifts WHERE EmployeeId = 789 AND Date >= '2026-01-01'

Query tasks by status:

SELECT * FROM Tasks WHERE Status = 'todo'

Query teams:

SELECT * FROM Teams

Query time records by project worker:

SELECT * FROM TimeRecord WHERE ProjectWorkerId = 123

Query training programs by status:

SELECT * FROM Trainings WHERE Status = 'active'

Query training sessions by training:

SELECT * FROM TrainingSessions WHERE TrainingId = 456

Query financial transactions by account:

SELECT * FROM Transaction WHERE BankAccountId = 789

Query custom field values by field:

SELECT * FROM Value WHERE FieldId = 123

Query worked time by employee and date range:

SELECT * FROM WorkedTime WHERE EmployeeId = 456 AND Date >= '2026-01-01'

Connection Properties

The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider.

Property	Description
AuthScheme	The scheme used for authentication. Accepted entries are OAuth, or None. Allowed values are: BASIC, NONE, NTLM, OAUTH, APIKEY, OAUTH_CLIENT
Scope	Scope(s) to use when authenticating, that control access to specific information.