Factorial

aid: factorial
url: https://raw.githubusercontent.com/api-evangelist/factorial-hr/refs/heads/main/apis.yml
apis:
  - aid: factorial:factorial-core-employees-api
    name: Factorial Core Employees API
    tags:
      - HR
      - Employees
      - Core
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/
        type: Documentation
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
      - url: openapi/factorial-openapi.yml
        type: OpenAPI
      - url: json-schema/factorial-employee-schema.json
        type: JSONSchema
      - url: json-ld/factorial-hr-context.jsonld
        type: JSONLD
      - url: examples/factorial-list-employees-example.json
        type: Example
      - url: examples/factorial-create-employee-example.json
        type: Example
      - url: examples/factorial-get-current-user-example.json
        type: Example
    description: >-
      List, read, create, and update employees in the Factorial HR directory. The Core Employees v2 API exposes a clean,
      non-data-intensive employee record (replacing the legacy v1 shape) plus the /v1/me endpoint for identifying the
      current OAuth2 token holder. Supports both OAuth2 and x-api-key authentication.
  - aid: factorial:factorial-webhooks-api
    name: Factorial Webhooks API
    tags:
      - HR
      - Webhooks
      - Events
    humanURL: https://apidoc.factorialhr.com/docs/manage-webhooks
    properties:
      - url: https://apidoc.factorialhr.com/docs/manage-webhooks
        type: Documentation
      - url: https://apidoc.factorialhr.com/docs/webhooks-policies
        type: Documentation
      - url: https://apidoc.factorialhr.com/docs/webhooks-what
        type: Documentation
      - url: https://apidoc.factorialhr.com/docs/webhook-attendance-clock-in
        type: Documentation
      - url: json-schema/factorial-webhook-subscription-schema.json
        type: JSONSchema
    description: >-
      Subscribe to lifecycle events fired by Factorial (employee created, employee terminated, attendance clock-in/out,
      ATS application created/updated, time-off leave created/approved, document created, etc.). Factorial POSTs the
      event payload to your target URL and retries on failure; consumer endpoints must be idempotent.
  - aid: factorial:factorial-ats-api
    name: Factorial ATS API
    tags:
      - HR
      - Recruiting
      - ATS
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      Applicant Tracking surface — Candidates, Applications, Application Phases, Job Postings, Feedback, Evaluation
      Forms, Answers. Read, create, update, and delete candidates and applications, plus phase progression and
      structured feedback collection. Part of the dated 2026-04-01 resource API.
  - aid: factorial:factorial-attendance-api
    name: Factorial Attendance API
    tags:
      - HR
      - Time
      - Attendance
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      Manage attendance shifts, breaks, overtime requests, timesheet edits, and attendance reviews. v2026-04-01
      introduces an api_source field on shift DTOs so integrations can identify themselves on clock operations.
  - aid: factorial:factorial-time-off-api
    name: Factorial Time Off API
    tags:
      - HR
      - Time Off
      - PTO
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      Time-off leaves, leave types, and time-off allowances with enriched statistics. Trigger webhooks on leave
      creation, update, and approval. Combine with the Approvals API to programmatically approve or reject pending
      leaves.
  - aid: factorial:factorial-contracts-compensations-api
    name: Factorial Contracts and Compensations API
    tags:
      - HR
      - Contracts
      - Compensation
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      Manage contract versions and compensation records. v2026-04-01 is a breaking-change release that removes legacy
      job catalog fields (job_title, professional_category_id, professional_category_description) in favour of
      job_catalog_tree_node_uuid, and adds richer fields for German and Spanish payroll integrations.
  - aid: factorial:factorial-payroll-api
    name: Factorial Payroll API
    tags:
      - HR
      - Payroll
      - Finance
    humanURL: https://apidoc.factorialhr.com/docs/payroll-integrations
    properties:
      - url: https://apidoc.factorialhr.com/docs/payroll-integrations
        type: Documentation
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      Payroll supplements, payroll identifiers, family situations, and bookkeeper resources. Backs Factorial's
      integrations with country- specific payroll engines.
  - aid: factorial:factorial-finance-banking-api
    name: Factorial Finance and Banking API
    tags:
      - Finance
      - Banking
      - Accounting
    humanURL: https://apidoc.factorialhr.com/docs/finance-integrations
    properties:
      - url: https://apidoc.factorialhr.com/docs/finance-integrations
        type: Documentation
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      Bank accounts, transactions, ledger accounts, journal entries, tax rates and tax types, cost centers, cost center
      memberships, and budgets. Cost center memberships are bulk-updatable so percentage splits can be applied
      atomically per employee.
  - aid: factorial:factorial-expenses-api
    name: Factorial Expenses API
    tags:
      - Finance
      - Expenses
      - Mileage
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: Submit, approve, and reconcile employee expenses, mileage claims, and per-diem requests.
  - aid: factorial:factorial-documents-api
    name: Factorial Documents API
    tags:
      - HR
      - Documents
      - E-Signature
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      Manage company- and employee-scoped documents and folders. Create, update, retrieve, and delete documents, request
      legal e-signatures, and fire document_created webhook events. Admin-only for document creation.
  - aid: factorial:factorial-performance-api
    name: Factorial Performance API
    tags:
      - HR
      - Performance
      - Talent
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      Performance reviews, review processes, evaluations, and performance agreements. Configurable review cycles backed
      by the Job Catalog Tree introduced in v2026-01-01.
  - aid: factorial:factorial-trainings-api
    name: Factorial Trainings API
    tags:
      - HR
      - Training
      - Learning
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: Manage training programs and training classes, expanded in v2026-04-01 with new class-level capabilities.
  - aid: factorial:factorial-job-catalog-api
    name: Factorial Job Catalog API
    tags:
      - HR
      - Job Catalog
      - Levels
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      Job levels, roles, functions, and the hierarchical Job Catalog Tree introduced in v2026-01-01. Replaces the legacy
      free-text job_title on contracts via job_catalog_tree_node_uuid.
  - aid: factorial:factorial-project-management-api
    name: Factorial Project Management API
    tags:
      - Projects
      - Tasks
      - Time Tracking
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      Projects, subprojects, tasks, project workers, planned and flexible time records, and budget strategies (full CRUD
      added in v2026-04-01).
  - aid: factorial:factorial-it-management-api
    name: Factorial IT Management API
    tags:
      - IT
      - Asset Management
      - MDM
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      IT asset and IT model endpoints (added in v2026-01-01) backing the SaaS, Inventory, MDM, and Cybersecurity
      modules.
  - aid: factorial:factorial-procurement-api
    name: Factorial Procurement API
    tags:
      - Procurement
      - Purchase Orders
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: Purchase orders, purchase requests, and purchase types. Added in v2026-01-01.
  - aid: factorial:factorial-approvals-api
    name: Factorial Approvals API
    tags:
      - Workflows
      - Approvals
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      Programmatically approve or reject pending steps of a materialized approval flow, either by id or by
      resource_id+resource_type. Added in v2026-04-01.
  - aid: factorial:factorial-locations-holidays-api
    name: Factorial Locations and Holidays API
    tags:
      - HR
      - Locations
      - Holidays
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: Company locations, work areas, and company holidays.
  - aid: factorial:factorial-custom-fields-api
    name: Factorial Custom Fields API
    tags:
      - HR
      - Custom Fields
      - Extensibility
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
      - url: openapi/factorial-openapi.yml
        type: OpenAPI
    description: Define custom fields, options, values, and schemas to extend Factorial resources with company-specific metadata.
  - aid: factorial:factorial-posts-communities-api
    name: Factorial Posts and Communities API
    tags:
      - Communities
      - Posts
      - Communication
    humanURL: https://apidoc.factorialhr.com/reference
    properties:
      - url: https://apidoc.factorialhr.com/reference
        type: Documentation
    description: >-
      Groups, posts, and comments backing the Communities V2 feature. Requires Communities V2 to be enabled on the
      company.
  - aid: factorial:factorial-marketplace-integrations-api
    name: Factorial Marketplace and Integrations API
    tags:
      - Integrations
      - Marketplace
    humanURL: https://apidoc.factorialhr.com/docs/integrations-framework
    properties:
      - url: https://apidoc.factorialhr.com/docs/integrations-framework
        type: Documentation
    description: >-
      Integrations Framework and Marketplace endpoints used by partner integrations to register, surface, and operate
      within the Factorial app.
  - aid: factorial:factorial-keys-oauth-api
    name: Factorial Keys and OAuth API
    tags:
      - Authentication
      - OAuth2
      - API Keys
    humanURL: https://apidoc.factorialhr.com/docs/authentication
    properties:
      - url: https://apidoc.factorialhr.com/docs/api-keys
        type: Documentation
      - url: https://apidoc.factorialhr.com/docs/oauth-2
        type: Documentation
      - url: https://apidoc.factorialhr.com/docs/oauth-scopes
        type: Documentation
      - url: https://apidoc.factorialhr.com/docs/create-a-new-oauth-application
        type: Documentation
      - url: https://apidoc.factorialhr.com/docs/oauth2-partner-guide
        type: Documentation
    description: >-
      Two authentication methods. OAuth2 (authorization code flow at /oauth/authorize and /oauth/token) is used to act
      on behalf of a user; Credentials/API Keys (x-api-key header) are used to act on behalf of the company with full
      admin access. API Keys overrule OAuth tokens when both are present on the same request.
name: Factorial
tags:
  - HR
  - Human Resources
  - Payroll
  - Time Off
  - Time Tracking
  - ATS
  - Performance
  - Finance
  - Expenses
  - Spain
  - Barcelona
  - All-in-One
kind: contract
image: https://kinlane-images.s3.amazonaws.com/shared/apis-json/apis-json-logo.jpg
access: 3rd-Party
common:
  - type: Portal
    url: https://factorialhr.com
  - type: Documentation
    url: https://apidoc.factorialhr.com/
  - type: Documentation
    name: API Reference
    url: https://apidoc.factorialhr.com/reference
  - type: GettingStarted
    url: https://apidoc.factorialhr.com/docs/getting-started
  - type: Documentation
    name: First Steps
    url: https://apidoc.factorialhr.com/docs/first-steps
  - type: Documentation
    name: Authentication
    url: https://apidoc.factorialhr.com/docs/authentication
  - type: Documentation
    name: OAuth 2
    url: https://apidoc.factorialhr.com/docs/oauth-2
  - type: Documentation
    name: OAuth Scopes
    url: https://apidoc.factorialhr.com/docs/oauth-scopes
  - type: Documentation
    name: API Keys
    url: https://apidoc.factorialhr.com/docs/api-keys
  - type: Documentation
    name: API Versioning
    url: https://apidoc.factorialhr.com/docs/api-versioning
  - type: Documentation
    name: Production and Demo Environments
    url: https://apidoc.factorialhr.com/docs/production-and-demo
  - type: Documentation
    name: Pagination
    url: https://apidoc.factorialhr.com/docs/pagination
  - type: Documentation
    name: FAQs
    url: https://apidoc.factorialhr.com/docs/faqs
  - type: ChangeLog
    url: https://apidoc.factorialhr.com/changelog
  - type: Webhooks
    url: https://apidoc.factorialhr.com/docs/manage-webhooks
  - type: Documentation
    name: Webhooks Policies
    url: https://apidoc.factorialhr.com/docs/webhooks-policies
  - type: Documentation
    name: Integrations Framework
    url: https://apidoc.factorialhr.com/docs/integrations-framework
  - type: Documentation
    name: Payroll Integrations
    url: https://apidoc.factorialhr.com/docs/payroll-integrations
  - type: Documentation
    name: Finance Integrations
    url: https://apidoc.factorialhr.com/docs/finance-integrations
  - type: Pricing
    url: https://factorialhr.com/pricing
  - type: SignUp
    url: https://factorialhr.com/signup
  - type: Login
    url: https://app.factorialhr.com/users/sign_in
  - type: StatusPage
    url: https://factorial.statuspage.io/
  - type: Blog
    url: https://factorialhr.com/blog
  - type: Customers
    url: https://factorialhr.com/customers
  - type: Support
    url: https://apidoc.factorialhr.com/docs/contact-page
  - type: GitHubOrganization
    url: https://github.com/factorialco
  - type: SDK
    name: OpenAPI Schema Repository
    url: https://github.com/factorialco/oas
  - type: SDK
    name: Ruby SDK (generated)
    url: https://github.com/factorialco/oas/tree/main/sdk-ruby
  - type: SDK
    name: Python SDK (generated)
    url: https://github.com/factorialco/oas/tree/main/sdk-python
  - type: SDK
    name: Java SDK (generated)
    url: https://github.com/factorialco/oas/tree/main/sdk-java
  - type: SDK
    name: PHP SDK (generated)
    url: https://github.com/factorialco/oas/tree/main/sdk-php
  - type: SDK
    name: TypeScript Axios SDK (generated)
    url: https://github.com/factorialco/oas/tree/main/sdk-typescript-axios
  - type: SDK
    name: Node.js Server SDK (generated)
    url: https://github.com/factorialco/oas/tree/main/sdk-nodejs-server
  - type: Tool
    name: f0 Design System
    url: https://github.com/factorialco/f0
  - type: PrivacyPolicy
    url: https://factorialhr.com/privacy-policy
  - type: TermsOfService
    url: https://factorialhr.com/terms-and-conditions
  - type: LinkedIn
    url: https://www.linkedin.com/company/factorial-hr/
  - type: Plans
    url: plans/factorial-plans-pricing.yml
  - type: RateLimits
    url: rate-limits/factorial-rate-limits.yml
  - type: FinOps
    url: finops/factorial-finops.yml
  - type: SpectralRules
    url: rules/factorial-rules.yml
  - type: Vocabulary
    url: vocabulary/factorial-hr-vocabulary.yml
  - type: Features
    data:
      - All-in-one HR, payroll, time, finance, talent, and IT modules
      - Public REST API with dated, major-versioned releases (current 2026-04-01 "Legendre")
      - Two auth schemes - OAuth2 authorization code on behalf of a user and x-api-key on behalf of the company
      - 30+ OAuth scopes for fine-grained partner access
      - Production and Demo environments (api.factorialhr.com vs api.demo.factorialhr.com)
      - 681+ documented endpoints across 30+ resource domains
      - Webhook subscriptions with documented event catalogue and retry policy
      - Approvals API for programmatic approve/reject of pending workflows
      - Job Catalog Tree replacing free-text job titles on contracts
      - Bulk endpoints (e.g. cost-center memberships) to reduce roundtrips
      - Integrations Framework, Payroll and Finance Integrations partner programs
      - Marketplace surface for distributing partner integrations inside the Factorial app
      - Officially generated SDKs for Ruby, Python, Java, PHP, TypeScript (axios), and Node.js server
      - llms.txt endpoint for AI agents at https://apidoc.factorialhr.com/llms.txt
      - 16,000+ companies on platform; HQ in Barcelona, Spain
    sources:
      - https://factorialhr.com
      - https://apidoc.factorialhr.com/
      - https://apidoc.factorialhr.com/changelog
      - https://github.com/factorialco/oas
    updated: '2026-05-25'
created: '2026-05-25'
modified: '2026-05-25'
position: Consuming
description: >-
  Factorial is an all-in-one HR, payroll, time, talent, finance, and IT management platform headquartered in Barcelona,
  Spain, used by 16,000+ companies worldwide. The Factorial public API is a date-versioned REST API (current major
  2026-04-01 "Legendre") covering employees, contracts, attendance, time off, payroll, ATS, performance, trainings,
  projects, finance, banking, procurement, IT assets, documents, webhooks, and an Approvals workflow surface.
  Authentication uses OAuth2 (on behalf of a user) or an x-api-key header (on behalf of the company), with 30+ scopes
  for granular partner access. Factorial publishes the OpenAPI schema and generated SDKs (Ruby, Python, Java, PHP,
  TypeScript, Node.js) at github.com/factorialco/oas and exposes an llms.txt index for AI agents.
maintainers:
  - FN: Kin Lane
    email: info@apievangelist.com
    X: apievangelist
    url: https://apievangelist.com
specificationVersion: '0.16'