> For the complete documentation index, see [llms.txt](https://docs.samesystem.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.samesystem.dev/business-guides/employee-lifecycle-management/fetch-employee-data/fetch-user-data.md). # Fetch user data {% hint style="info" %} **Note:** Users can also be fetched using **API v1**. However, for user and contract integrations, we strongly recommend using **API v2**, and this guide therefore describes data fetching using API v2 only. If you need to fetch users using API v1, please refer to the [**API v1 OpenAPI specification**](https://docs.samesystem.dev/api-v1-reference/) for the available endpoint, request parameters, and data model. {% endhint %} If you need to integrate employee data with another system, the API allows you to fetch multiple users or a single user. When fetching multiple users, filters and sorting can be used to limit the returned data and make the integration more efficient. ### Filtering Users #### Filter by last update Use `filter[updatedAtFrom]` to return only users that have been modified since a specified date and time. This is particularly useful for integrations that run regularly, as you can process only users that have changed since the previous synchronization. > **Tip:** Store the timestamp of your last successful synchronization and use it as `updatedAtFrom` for the next request. #### Filter by Status Use `filter[status]` to return users with a specific SameSystem status. For example, an integration may only need to retrieve: * Active users (`ACTIVE`) * Terminated users (`ENDED`) By default the endpoint will return only active users if `filter[status]` is omitted. List of available status:

filter[status]:	Description:
`ACTIVE`	Active users including blocked users. Users that are blocked from login will be an active user, but will have status `BLOCKED` but still returned with `filter[status]=ACTIVE`. You cannot filter by status `BLOCKED`.
`NOT_STARTED`	Users with a future contract that are not yet started.
`ENDED`	Terminated users. Users can have status `FINISHED`.
`DRAFT`	Users without a contract.
`DISABLED`	Soft deleted users. A deleted user exits as a soft deleted user for 24 hours before the user is finally removed. Users will have status `DELETED`.

#### Filter by External Department ID Use `filter[externalDepartmentId]` to return users belonging to a specific department based on the department's external identifier. #### Filter by Department ID Use `filter[departmentId]` to return users belonging to a specific department based on the internal SameSystem department ID. #### Combine Filters Filters can be combined to further limit the result. For example, you can retrieve users from a specific department that have been updated since your last synchronization. ### Sorting The API supports sorting of the returned users. Refer to the API reference for the available sorting parameters and values. ### Selecting Fields The `fields[User]` parameter allows you to specify which fields should be included in the returned user objects. We recommend requesting only the fields required by your integration. This reduces the response payload and can improve processing efficiency. You can include almost any field from the User schema, including fields from related and nested objects.

Examples include: * `contracts` \ All contracts associated with the user, including past, current, and future contracts. * `contract` \ The user's current active contract. * `absenceBalances` \ The user's absence balances. Nested properties can also be requested using their full field path, for example: `contracts.id` ### API Actions The API provides endpoints for:

Fetch multiple users

To fetch data for multiple users in a single call, the following endpoint can be used: GET /{clientToken}/users Refer to the Users API reference for all available filters, fields, sorting options, and request parameters. If you need to fetch custom fields from the user, please see [Custom fields](/business-guides/data-models/custom-fields.md).

Fetch a single user

To fetch data for a single user in a single call, the following endpoint can be used: GET /{clientToken}/users/{id} The parameter `{id}` is the unique id number of the user in SameSystem. The value is present in the user object: `user.id`. \ It can also be a custom Id, like an employee id or payroll number from an external system. If a custom id is used, you must include the parameter `useCustomId=true` in the call. Refer to the Users API reference for all available filters, fields, sorting options, and request parameters. If you need to fetch custom fields from the user, please see [Custom fields](/business-guides/data-models/custom-fields.md). Request body is empty. The response returns an object conforming to the User schema, including only the fields specified in your request.

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.samesystem.dev/business-guides/employee-lifecycle-management/fetch-employee-data/fetch-user-data.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.