--- title: Lucca API Integration on Truto slug: lucca category: HRIS canonical: "https://truto.one/integrations/detail/lucca/" --- # Lucca API Integration on Truto **Category:** HRIS **Status:** Generally available ## Unified APIs ### Unified HRIS API - **Companies** — Companies represent the companies in HRIS - **Employees** — Represents an employee in HRIS - **Employments** — Employments represent a job position at a company. - **Groups** — Groups represent the groups for an Employee - **Job Roles** — Represent the job roles in a company - **Locations** — Locations represent the locations in HRIS ## MCP-ready AI tools Truto exposes 35 tools for Lucca that AI agents can call directly. - **list_all_lucca_employees** — List employees in Lucca. Returns id, type, url, remoteId, portrait, givenName, familyName, employeeNumber, status, email, birthDay, phoneNumber, applicableEmployment, applicableJobPosition, createdAt, lastUpdatedAt, and links fields in the response. - **get_single_lucca_employee_by_id** — Get detailed information about a specific employee in Lucca using id. Returns fields such as id, type, url, remoteId, portrait, givenName, familyName, employeeNumber, status, email, birthDay, phoneNumber, applicableEmployment, applicableJobPosition, createdAt, lastUpdatedAt, links, and embedded with employment and job-position information. - **list_all_lucca_legal_entities** — List legal-entities in Lucca. Returns a paginated array of legal-entity objects with fields: id, type, url, legalName, remoteId, isArchived, countryCode, currencyCode, taxIdentificationNumber, industryCode, createdAt, lastUpdatedAt, lastArchivedAt, and links (including businessEstablishments) in the response. - **get_single_lucca_legal_entity_by_id** — Get a specific legal-entity in Lucca by id. Returns id, type, url, legalName, remoteId, isArchived, countryCode, currencyCode, taxIdentificationNumber, industryCode, createdAt, lastUpdatedAt, lastArchivedAt, links, and embedded fields. - **list_all_lucca_business_establishments** — List business-establishments in Lucca. Returns id, type, url, name, remoteId, legalEntity, taxIdentificationNumber, address, timezoneId, holidaysCalendar, isArchived, lastArchivedAt, createdAt, lastUpdatedAt fields for each business-establishment. - **get_single_lucca_business_establishment_by_id** — Retrieve a business-establishment in Lucca by id. Returns id, type, url, name, remoteId, legalEntity, taxIdentificationNumber, address, timezoneId, holidaysCalendar, isArchived, lastArchivedAt, createdAt, lastUpdatedAt, links, and embedded fields in the response. - **list_all_lucca_departments** — List departments in Lucca. Returns items with fields: id (department identifier), type (resource type), url (department URL), name, remoteId, isArchived, description, parent, level (department depth), manager, sortOrder, and links. Response also includes totalCount and pagination links. - **get_single_lucca_department_by_id** — Get a department in Lucca by id. Returns id, type, url, name, description, remoteId, isArchived, parent, level, manager, sortOrder, links, and embedded fields in the response. - **list_all_lucca_employee_personal_records** — List employee-personal-records in Lucca. Returns id, type, url, associated employee, title, legalGender, birthDate, insuranceNumber, nationalitiesCountryCodes, bankAccount, phoneNumber, email, and links for each record in the response. - **get_single_lucca_employee_personal_record_by_id** — Retrieve an employee-personal-record in Lucca by id. Returns fields such as id, type, url, employee, title, legalGender, birthDate, insuranceNumber, nationalitiesCountryCodes, bankAccount, phoneNumber, email, links, and embedded (which includes related employee details). - **list_all_lucca_employments** — List employments in Lucca. Returns items with id, employee, legalEntity, start and end dates, template, createdAt, lastUpdatedAt, document, and resource links in the response. - **get_single_lucca_employment_by_id** — Get details about a specific employment in Lucca using id. Returns id, type, url, remoteId, employee, legalEntity, start, end, document, template, createdAt, lastUpdatedAt, links, and embedded fields in the response. - **list_all_lucca_job_positions** — List job-positions in Lucca. Returns job-positions with fields including id, employment, startsOn, endsOn, businessEstablishment, department, jobTitle, jobQualification, manager, occupationCategory, workingTimeArrangement, notes, changedAttributes, createdAt, and lastUpdatedAt. - **get_single_lucca_job_position_by_id** — Get a job-position in Lucca by id. Returns job-position details including id, type, url, employment, employee, startsOn, endsOn, businessEstablishment, jobTitle, jobQualification, manager, occupationCategory, workingTimeArrangement, department, document, notes, changedAttributes, createdAt, lastUpdatedAt, links, and embedded resources. - **list_all_lucca_probationary_periods** — List probationary-periods in Lucca. Returns id, type, url, employment, startsOn, endsOn, initialEndsOn, extendedEndsOn, createdAt, lastUpdatedAt, and links fields for each probationary-period. - **get_single_lucca_probationary_period_by_id** — Get a probationary-period in Lucca by id. Returns id, type, url, employment reference, startsOn, endsOn, initialEndsOn, extendedEndsOn, createdAt, lastUpdatedAt, links, and embedded fields in the response. - **list_all_lucca_occupation_categories** — List occupation-categories in Lucca. Returns each occupation-category's id, type, url, title, businessEstablishments, and t9n fields in the response. - **get_single_lucca_occupation_category_by_id** — Get a specific occupation-category in Lucca by id. Returns fields: id (identifier), type (always 'occupation-category'), url (resource URL), title (unique name), businessEstablishments (applicable business-establishments or null), t9n (translations), links, and embedded. - **list_all_lucca_professions** — List professions in Lucca. Returns id, type, url, title, isArchived, t9n, and links fields for each profession. - **get_single_lucca_profession_by_id** — Get details about a specific profession in Lucca by id. Returns id, type, url, title, isArchived, t9n (translations), links, and embedded fields in the response. - **list_all_lucca_job_qualifications** — List job-qualifications in Lucca. Returns a paginated array of job-qualification objects including id, type, url, title, profession, rank, t9n, createdAt, lastUpdatedAt, and links fields in the response. - **get_single_lucca_job_qualification_by_id** — Get a job-qualification in Lucca by id. Returns id, type, url, title (unique), profession (profession id, type, url), rank, createdAt, lastUpdatedAt, and links in the response. - **list_all_lucca_employment_templates** — List employment-templates in Lucca. Returns id, type, url, title, legalEntities, term, and source for each employment-template in the response. - **get_single_lucca_employment_template_by_id** — Get an employment-template in Lucca by id. Returns id, type, url, title, legalEntities (array of legal-entity references), term, source, t9n (translations), createdAt, lastUpdatedAt, links (extensionDefinitions), and embedded fields. - **list_all_lucca_webhook_endpoints** — List webhook-endpoints in Lucca. Returns id, type, url, webhookUrl, topics, status fields for each webhook-endpoint in the response. Requires no parameters. - **get_single_lucca_webhook_endpoint_by_id** — Get a webhook-endpoint in Lucca by id. Returns fields including id, type, url, apiVersion, webhookUrl, topics, status, contentType, createdAt, lastUpdatedAt, and links in the response. - **create_a_lucca_webhook_endpoint** — Create a webhook-endpoint in Lucca. Returns id, type, url, apiVersion, webhookUrl, topics, status, contentType, secret, createdAt, lastUpdatedAt, and links in the response. All returned fields are required for the created resource. - **update_a_lucca_webhook_endpoint_by_id** — Update a webhook-endpoint in Lucca. Requires id. Returns id, type, url, apiVersion, webhookUrl, topics, status, contentType, createdAt, lastUpdatedAt, and links fields in the response. - **delete_a_lucca_webhook_endpoint_by_id** — Delete a webhook-endpoint in Lucca. Requires id. No content is returned in the response upon successful deletion. - **list_all_lucca_webhook_deliveries** — List webhook-deliveries in Lucca. Returns an array of webhook-delivery objects with fields: id (unique identifier), type, url, nextAttemptAt (next attempt timestamp), attemptsCount, status, event (event reference), webhookEndpoint (endpoint reference), and links (attempt URLs). - **get_single_lucca_webhook_delivery_by_id** — Get details about a specific webhook-delivery in Lucca. Requires id. Returns id, type, url, nextAttemptAt (next planned attempt UTC), attemptsCount (number of attempts), status (delivered/undelivered/failed), event reference, webhookEndpoint reference, links, and embedded event. - **lucca_webhook_deliveries_ping** — Send a ping event to a webhook-endpoint in Lucca. Requires webhook_endpoint_id. Returns id, type, url, nextAttemptAt (timestamp of next attempt), attemptsCount, status (delivered/undelivered/failed), event (reference), webhookEndpoint (reference), links (e.g., attempts URL), and embedded event in the response. - **list_all_lucca_webhook_delivery_attempts** — List webhook-delivery-attempts in Lucca. Returns id (attempt identifier), type (resource type), url (resource URL), signature, webhookDelivery (delivery reference), isSuccessful (status), responseStatusCode, errorResponseBody, createdAt, links, and embedded objects in the response. - **get_single_lucca_webhook_delivery_attempt_by_id** — Get a webhook-delivery-attempt in Lucca by id. Returns id, type, url, signature, webhookDelivery, isSuccessful, responseStatusCode, errorResponseBody, createdAt, links, and embedded containing webhook-delivery and event data. - **get_single_lucca_portrait_by_id** — Retrieve a portrait in Lucca by id. Returns id, type, url, employee, fileName, contentType, createdAt, links, and embedded fields in JSON. To download the image file, set Accept: image/* header. ## How it works 1. **Link your customer's Lucca account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Lucca.** The Proxy API is a 1-to-1 mapping of the Lucca API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Automate employee provisioning and deprovisioning** — SaaS companies offering identity, access, or IT asset management can sync Lucca's employee lifecycle data — including hire dates, department assignments, and termination status — to automatically provision or revoke accounts, licenses, and equipment without manual HR handoffs. - **Mirror complex organizational structures** — Products that need to enforce policies, route approvals, or segment dashboards by org structure can pull Lucca's legal entities, business establishments, and department hierarchies to accurately represent multi-entity, multi-location companies common in European mid-market. - **Trigger real-time workflows on HR events** — Instead of polling for changes, SaaS apps can programmatically create and manage Lucca webhook endpoints through Truto to react instantly when employees are created, roles change, or probation periods end — powering onboarding automations, review cycle setup, and compliance alerts. - **Sync job and career data for workforce planning** — Resource planning, performance management, and compensation platforms can leverage Lucca's granular distinction between employments, job positions, probationary periods, and manager hierarchies to build accurate career timelines and reporting chains. - **Enforce role-based policies using HR metadata** — Travel, expense, or benefits platforms can pull occupation categories, job qualifications, and legal entity details from Lucca to dynamically apply the correct policy tier based on an employee's role, seniority, and jurisdiction. ## What you can build - **One-click org chart sync** — Automatically build and maintain your product's organizational hierarchy by syncing Lucca departments, legal entities, and business establishments through Truto's Unified HRIS API for Companies, Groups, and Locations. - **Real-time employee lifecycle webhooks** — Programmatically register, update, and monitor Lucca webhook endpoints and delivery attempts directly from your app to trigger onboarding, offboarding, or role-change workflows the moment they happen. - **Manager hierarchy mapping for approval chains** — Pull job positions with manager relationships from Lucca to automatically configure multi-level approval workflows in your product without customers manually setting up reporting lines. - **Probation period tracking and review triggers** — Sync probationary period start and end dates from Lucca to automatically schedule check-ins, generate review templates, or flag compliance deadlines inside your platform. - **Employee profile enrichment with portraits** — Fetch employee profile photos via Lucca's portrait API to populate user avatars across your product, giving customers a more personalized and familiar experience without manual uploads. - **Dynamic policy assignment by job qualification and entity** — Combine Lucca's occupation categories, job qualifications, and legal entity data to automatically assign the correct expense limits, travel tiers, or benefit plans based on each employee's role and jurisdiction. ## FAQs ### What authentication methods does the Lucca integration support through Truto? Truto handles the authentication flow with Lucca on your behalf. Your end users connect their Lucca accounts through Truto's embedded linking experience, and Truto manages token storage, refresh, and session management so you never deal with auth directly. ### Which Lucca data models map to Truto's Unified HRIS API? Lucca's Legal Entities map to the Unified Companies API, Employees and Employee Personal Records map to the Unified Employees API, Employments map to the Unified Employments API, Departments map to the Unified Groups API, Job Positions and Job Qualifications map to the Unified Job Roles API, and Business Establishments map to the Unified Locations API. ### Can I receive real-time updates from Lucca instead of polling? Yes. Lucca exposes a full webhook infrastructure. Through Truto, you can create, update, delete, and list webhook endpoints, as well as inspect webhook deliveries and individual delivery attempts. You can also use the ping endpoint to test connectivity. ### Does the integration support write operations? For core HR data like employees and departments, the current integration supports read operations (list and get by ID). Write operations are available for webhook management — you can create, update, and delete webhook endpoints programmatically. ### How does Truto handle pagination and rate limits for Lucca? Truto abstracts away Lucca's API-specific pagination logic and rate limiting. When you call a list endpoint through Truto, pagination is handled automatically so you receive complete datasets without managing cursors or page tokens yourself. ### Can I access Lucca's granular job data like probationary periods and occupation categories? Yes. Beyond standard employee and employment data, the integration exposes probationary periods, occupation categories, professions, job qualifications, and employment templates — giving you fine-grained career and compliance data that many HRIS integrations don't surface.