factorial ai agent hr automation integrations

To connect an AI agent to Factorial, you give it scoped access to the HRIS public API so it can close out HR admin on its own: time-off requests, certificates and documents, new-hire onboarding, attendance exceptions and the questions employees ask over and over. Factorial exposes a date-versioned REST API — the current major version as of August 2026 is 2026-04-01, codenamed "Legendre" — covering employees, contracts, time off, attendance, payroll, ATS, performance, training, documents and webhooks. No browser automation, no scraping: the agent works against official endpoints.

This matters because Factorial is the default HRIS for thousands of Spanish and European small and mid-sized companies, and the same pattern shows up in nearly all of them: the system is set up properly, but the HR person is still the human middleware between the employee and the software. This article covers which parts of that middleware an agent can take over, how to connect it without opening the door to data it should never see, and where we draw the line.

Which parts of Factorial can an agent touch?

Effectively the whole employee lifecycle, because the public API is organised by domain and each domain carries its own permissions. According to the official developer documentation (apidoc.factorialhr.com, checked August 2026), the available surfaces include employees and contracts, attendance and clock-ins, time off, payroll concepts, expenses, documents, recruiting (ATS), performance, training, projects and an approvals surface, plus webhooks to react to events.

That domain split is exactly what makes a cautious rollout possible. An employee-questions agent needs to read time off, calendar and the employee's own documents; it does not need payroll, performance or ATS. An onboarding agent needs to create employees, assign documents and trigger tasks; it does not need to read anybody else's salary.

Beyond the API itself, Factorial publishes its OpenAPI schema and generated SDKs in several languages (Ruby, Python, Java, PHP, TypeScript and Node.js) in a public repository, which shortens the integration phase considerably. In practice, the heavy lifting is not talking to Factorial — it is deciding what the agent may do on its own and what it must escalate.

How do you authenticate without handing over full access?

By choosing the right authentication model per case: a company-level API key when the agent acts as a system (background jobs, syncs, reporting), and OAuth2 on behalf of the user when the agent acts for a specific employee and should see exactly what that employee would see. Factorial supports both and offers a broad catalogue of scopes — more than thirty — to fence access off by domain.

The rule we always apply is least privilege per use case, not per vendor. You do not create "the AI agent key" with everything enabled; you create one credential per function with strictly the read or write scopes it needs. If the time-off agent cannot read payroll, the privacy conversation with your works council gets a great deal shorter.

Use case	Authentication	Typical access
Employee questions ("how many days do I have left?")	OAuth2 on behalf of the user	Read own time off, calendar and documents
Requesting and processing time off	OAuth2 + approvals	Read and write the requester's time off
Onboarding a new hire	Company API key	Write to employees, contracts, documents and tasks
HR reporting and dashboards	Company API key (read only)	Aggregate reads of attendance, absence and headcount
Attendance exception alerts	Webhooks + company key	Read attendance, write notifications

Which use cases pay for themselves?

The four that generate most of any HR team's internal ticket volume: time off, documents, onboarding and repeat questions. None of them is glamorous, but together they consume the time of the person who should be doing hiring, development plans and culture work.

1. Time off and holidays. The employee writes in plain language ("I'd like the 14th to the 18th plus the December bridge") and the agent checks the balance, overlaps with the rest of the team and company policy, creates the request in Factorial and routes it to the approver with the context already resolved. The manager approves in one click instead of opening the HRIS to verify things.
2. Documents and certificates. Employment certificates, tax withholding statements, contract copies, last month's payslip. These requests carry zero value for whoever processes them and high value for whoever asks; the agent resolves them instantly against the documents that employee is entitled to see.
3. Onboarding. The moment a hire is signed, the agent creates the record, launches the documentation checklist, books the first-week sessions, requests IT access and chases whatever is missing. A well-orchestrated onboarding shows up in first-month productivity, and it is one of the most rewarding processes to automate.
4. Repeat questions. Remote work policy, flexible compensation, how clock-in works, what happens with bank holidays. The agent answers by citing the current internal policy and, when it is not sure, escalates instead of improvising.

All four sit on the same architecture we describe in our guide to automating HR and recruiting with AI. What changes here is that the system of record is Factorial, and the agent writes into it rather than into a parallel spreadsheet.

Where should the agent live: in Factorial or in your chat?

In your chat, almost always. The employee who wants to know their remaining holiday is not going to open the HRIS — they are going to ask in Slack, Teams or WhatsApp, because that is where they already are. The agent lives in that conversation and uses Factorial as the source of truth behind it.

This design decision has a measurable effect on adoption. A well-built self-service portal reduces tickets a little; an agent in the channel where people already type reduces them far more, because it removes the "go to another place" step. How that conversational layer is built is covered in AI agents in Slack and Teams.

The second effect is traceability: every answer is logged next to the query the agent ran against Factorial. When someone disputes a holiday balance or a contract date, there is a complete trail of what was asked, what the system returned and what was answered.

What should you NOT automate in HR?

Decisions about people. An agent can prepare, look up, draft and process; it must not decide who gets hired, who gets let go, who gets promoted or how anyone is rated. That is not only our position — it is the direction European regulation is taking.

• Hiring and termination decisions. The agent can screen against objective requirements and prepare the information; the decision and its justification stay human and must be explainable.
• Performance reviews. Drafting from evidence the manager supplies, yes. Scoring a person, no.
• Health data and medical leave. A special category under GDPR. The agent can record that a certificate exists; it should not read or process its clinical content.
• Labour disputes and disciplinary matters. Detect and escalate, yes; answer automatically, never.

Two regulatory dates are worth keeping in view. Since 2 August 2026, the transparency obligations of Article 50 of the EU AI Act apply: if an employee is talking to an agent, you have to tell them. And AI systems used in employment and worker management sit in Annex III as high risk, on a timetable that — after the digital omnibus revision — places enforceability in December 2027 (as of August 2026; confirm the final text before budgeting for compliance). The practical translation: an agent that answers questions and processes paperwork falls outside that category, and one that scores candidates or employees falls inside it.

What does the project cost and how long does it take?

A scoped integration — employee questions, time off and documents, with the agent living in Slack or Teams — is a 4 to 8 week project and lands in the €15,000-40,000 range typical of a custom agent for a small or mid-sized company. Most of that cost is permission design, loading internal policies and testing, not the technical connection. Annual maintenance runs 10-20% of the build and covers API changes, policy updates and behavioural tuning.

Extending afterwards to onboarding and reporting usually costs less than the first block, because authentication, the permission layer and the channel are already in place. That is the normal pattern: the first use case pays for the infrastructure and the following ones ride on it.

Before signing anything, get the permission map settled: who can ask what, what the agent may write, and what always escalates to a human. That design is what separates an uneventful rollout from an incident, and we cover it in depth in AI agent governance and permissions. If you would rather work it through with a team that integrates these systems every week, that is what we do from our AI agency in Madrid.

Frequently asked questions

Do I need a specific Factorial plan to use the API?

Access to the public API and to integrations depends on your contracted plan and active modules, so the first step of any project is confirming it with your Factorial contact or in the admin panel. What is common to every case is that you need administrator rights to generate credentials — this is not something an employee can set up alone.

Can the agent see my employees' salaries?

Only if you grant it payroll scopes, and most use cases do not need them. Our default recommendation is to exclude payroll and performance from the conversational agent's credentials and, if the need ever arises, create a separate, audited credential for aggregate reporting.

What happens when Factorial changes its API?

It is date-versioned, which means older versions keep working while supported and new capabilities arrive in new versions. Even so, annual maintenance exists precisely for this: reviewing deprecation notices, migrating versions and testing that nothing broke before an employee notices.

Does this still work if we also run an ERP or a CRM?

Yes, and it is usually the norm: the same assistant can query Factorial for HR matters and another system for financial ones, as long as each connection carries its own permissions. What we do not recommend is a single all-powerful agent with access to everything; a set of specialised agents is both safer and easier to maintain.

How do I stop the agent inventing a policy that doesn't exist?

By restricting it to the policies you have loaded, requiring it to cite the source, and making it escalate whenever it finds no documentary backing. In practice the project usually exposes a pre-existing problem: internal policies that are out of date or scattered. Tidying them up is part of the work, and it is one of those tasks companies postpone for years until automation forces the issue.