Skip to main content
By default, the Lucca API responds with the JSON representation of the requested resource, nothing more. But you may request for complementary includes, such as:
You can retrieve multiple types of includes by chaining the query parameter values: ?include=totalCount,embedded,links.
Access rights are evaluated when including embedded resources, thus you may not systematically retrieve them even when including them.

About Embedded

When adding ?include=embedded to your HTTP GET requests, the Lucca API will attempt to include the representations of related resource in the response. For example: you may retrieve the first and last name of the employee when retrieving his leaves. Notes:
  • Embedded resources may not actually be included in responses if you do not have access to them.
  • The included representation may be partial, i.e. only give you a subset of the resource properties.
  • It may also be stale from cache in the very short term.
  • You cannot choose which resources to embed. The list of available resources is dictated by each API endpoint. Including embedded resource is a binary affair: do include them, or do not.
In order to avoid duplicates, embedded resources representations are formatted as a double-level dictionary: indexed by resource type (e.g. leave, employee, etc…) then by id.
Links are objects that represent navigational references to other resources and/or actions on the target resource. Examples are:
  • links to the previous and next pages of a collection.
  • link to the approval process of a leave-request.
These can be used to reduce coupling between the client and server implementations, as well as to predict access: the next page link will be null whenever there’s no next page, the link to the approval process will be null whenever the leave-request is already approved or you have insufficient rights to approve it. By default, links are omitted from responses, but may be included through the include query parameter. Links come in three shapes, depending on what they lead to. Most links only hold an href: the absolute URL of the related resource or action, to follow as is rather than build yourself. A null link means the resource or action is not available to you.
On a collection, links.prev and links.next lead to the previous and next pages. Besides href, they hold the cursor of that page. Read more in Paging. A resource that references files, such as an employment’s document, an employee’s portrait or an employee-attribute whose value is a file, returns one download link per file under links.files, indexed by file id. The url of a file reference does not give access to the file: go through its link.
To download a file:
  1. Read the resource with ?include=links, and take the entry of links.files whose key is the id of the file reference. Every file reference has an entry, wherever it sits in the resource.
  2. Follow its href with the same Authorization header. Your access token needs the files.readonly scope: the token in href only grants access to this one file, for your API client, and does not authenticate you on its own.
  3. The response holds the file content whatever your Accept header, with its name and content type in the Content-Disposition and Content-Type headers.
File links expire at expiresAt: do not store them, read the resource again to get a fresh one. An entry is null when you may not download that file.
Read more in Get Started With Files.