canonical: https://jentic.com/apis/example.ilucca.net/lucca-directory # Example Ilucca Directory-v3 Lucca Directory v3 is the user-records API for the Lucca HR suite. It exposes the canonical employee directory - names, identifiers, and profile attributes - that other Lucca modules (Cleemy, Timmi, Organization) reference by userId. Agents use it to resolve user identities, list employees, and look up profile details when wiring HR workflows together. ## For AI agents Read and update Lucca employee profiles to resolve userIds and look up directory information across the Lucca HR suite. ## Scope Does not handle payroll, expenses, or org-structure data - use for Lucca user record lookups and updates only. ## Capabilities - List Lucca employees with paging for full-directory exports - Retrieve a single user profile by userId for identity resolution - Update specific user profile attributes through the directory - Look up directory entries by query parameters during agent workflows ## Use cases ### User identity resolution across Lucca Other Lucca APIs (Cleemy, Timmi Absences, Timmi Timesheet) reference users by numeric userId. An integration agent calls Directory v3 to translate userIds into human-readable employee profiles, so HR reports and AI assistants can render names instead of opaque ids. Example prompt: Call GET /api/v3/users/1234 and return the user's display name, email, and department for use in an expense claim summary. ### HR data export and sync An IT operations agent runs a nightly export of the Lucca directory into a downstream HRIS or data warehouse. Using paged GET /api/v3/users calls, the agent retrieves the full employee list and writes it to the target system without manual CSV downloads. Example prompt: Page through GET /api/v3/users in batches of 100 until the directory is exhausted, then upsert each record into the corporate data warehouse. ### Profile updates from a chat agent An employee asks an HR assistant to update a phone number or job title. The assistant calls the Lucca Directory update endpoint to apply the change, keeping the canonical record in sync without an HR admin opening the Lucca UI. Example prompt: Update user 1234's job title to 'Senior Engineer' via the Directory v3 user-update endpoint and confirm the change is reflected on subsequent GET. ### AI agent identity layer via Jentic An AI assistant accessed through Jentic uses Directory v3 as its identity layer for the Lucca suite. Before submitting expenses, requesting leave, or filing timesheets on behalf of a user, the assistant resolves the user's Lucca id once and reuses it across all sibling operations. Example prompt: Use Jentic to search for 'find a Lucca user by email', load the directory operation, and resolve a known email to a Lucca userId for downstream Cleemy and Timmi calls. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /api/v3/users | List Lucca users with paging | | GET | /api/v3/users/{userId} | Retrieve a single user by id | ## Key resources - **Users** — Employee directory entries with profile attributes referenced across the Lucca suite ## Why Jentic - **Setup:** Wiring the Lucca Directory API by hand means learning its header API key auth on your ilucca.net tenant host and tracking the /api/v3/users read endpoints yourself. Through Jentic you install once, import Directory from the API Directory, store the API key once, and your agent calls it. - **Permission scoping:** Directory puts the user id in the URL path (/api/v3/users/{userId}), so a rule can pin your agent to one user record. You choose the operations it may call, and since both endpoints are read GETs the agent looks up user data and changes nothing unless you add write operations. - **Credential handling:** Your Lucca API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'look up an employee' or 'list users', and Jentic returns the matching Directory operation with its input schema so the agent calls /api/v3/users without browsing the reference docs. ## Related APIs - **Lucca Organization** — Provides departments and org structure that pair with directory user records - **Cleemy Expenses** — Consumes Lucca userIds when creating expense items and claims - **BambooHR** — All-in-one HRIS with employee directory plus PTO and onboarding - **Personio** — European HRIS with employee records, absences, and recruiting in one API ## FAQ ### What authentication does the Lucca Directory API use? Lucca Directory v3 uses an API key passed in the Authorization header. Through Jentic, the key is stored in your Jentic One instance and exchanged for a scoped token at call time, so the raw secret never reaches the agent. ### Can I list all Lucca employees through the Directory API? Yes. GET /api/v3/users returns the directory with paging parameters, so an agent can iterate the full employee list in batches without hitting per-request size limits. ### How do I resolve a Lucca userId to a name? Call GET /api/v3/users/{userId} with the numeric id. The response includes the user's display name, email, and core profile attributes, which agents can use to label expense claims, leave requests, or timesheet entries. ### What are the rate limits for the Lucca Directory API? The OpenAPI spec does not publish explicit rate limits. Lucca enforces tenant-level throttling, so agents should handle 429 responses by backing off and respecting any Retry-After header before retrying. ### How do I look up a user via Jentic? Run pip install jentic, search for 'lookup a Lucca user by id', load the user-detail operation, and execute it with the userId. Jentic supplies the input schema and returns the parsed response so the agent can act on the profile data. ### Does Lucca Directory cover departments and org structure? No. Directory v3 covers user records only. Department trees, axes, and organizational structures live in the Lucca Organization API, which is separately listed in the Jentic API Directory. ### Can I limit what my agent is allowed to do with the Lucca Directory API? Yes. Because you run Jentic One yourself, your own rules decide which Directory operations and credentials the agent may use, so you can allow only GET /api/v3/users and GET /api/v3/users/{userId} and leave everything else off. Since the user id sits in the URL path, a rule can even pin the agent to a single user record rather than the whole directory. Both exposed endpoints are read-only GETs, so the agent looks up user data and changes nothing unless you add write operations. Your Lucca API key stays with your instance and is supplied only at call time, never in the agent's prompt or logs.