> 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/data-models/custom-fields.md). # Custom fields SameSystem supports custom fields, referred to as **Extra fields** in the SameSystem user interface. Custom fields allow customers to store additional information that is not part of the standard SameSystem data model. Custom fields can be associated with **users** and/or **contracts**, depending on how the Extra field has been configured in SameSystem. Examples of information stored in custom fields could include: * Employee benefits * Payroll-specific information * Internal classifications * Parking areas * External system attributes * Other customer-specific employee or contract information ### Custom fields in integrations Custom fields can be retrieved through the API v2 Users endpoints. Each custom field has an internal SameSystem `id`. However, these IDs are client-specific. The same logical field may therefore have different IDs for different SameSystem clients. For example: | Client: | Field: | SameSystem ID: | | -------- | ----------------- | -------------- | | Client A | Employee benefits | `14507` | | Client B | Employee benefits | `18234` | This makes it difficult to build a generic integration based on the internal field ID. To solve this, SameSystem allows you to configure your own **Custom ID** for an Extra field. The Custom ID provides a stable identifier that can be used by your integration across multiple SameSystem clients. For example: `employeeBenefits` The same `customId` can then be configured for the corresponding Extra field for each client, allowing your integration logic to remain unchanged. > **Best practice:** For integrations used across multiple SameSystem clients, always configure and use a `customId` instead of relying on the internal SameSystem field `id`. ### Configuring a custom ID The Custom ID is configured in SameSystem when configuring the Extra field. Choose an identifier that is unique, descriptive, and suitable for use by integration code, for example: * `employeeBenefits` * `payrollGroup` * `assignedParkingArea` * `externalCostCenter` Once configured, the `customId` can be used when reading and writing custom field values through the API. ### Adding custom field values When creating or updating a user or contract, a custom field can be identified using either its `customId` or its internal SameSystem `id`. #### Using `customId` – Recommended ```json { "customFields": { "customId": "employeeBenefits", "value": "Test" } } ``` Using `customId` is recommended because the integration does not need to know the client-specific SameSystem field ID. #### Using the SameSystem field ID Alternatively, the internal SameSystem field ID can be used: ```json { "customFields": { "id": "14507", "value": "Test" } } ``` This can be suitable for a client-specific integration, but the ID should not be assumed to be the same for another SameSystem client. ### Retrieving custom fields Custom fields must be explicitly included when retrieving users. Add the required custom field properties to the `fields[User]` query parameter: ``` ?fields[User]=customFields.extraField.customId,customFields.extraField.id,customFields.extraField.name,customFields.selectedChoices.label,customFields.selectedChoices.value,customFields.value ``` The following properties are available: | Field | Description: | | ------------------------------------ | -------------------------------------------------------------------------------- | | `customFields.extraField.customId` | Your integration-specific identifier. Blank if no Custom ID has been configured. | | `customFields.extraField.id` | SameSystem's internal field identifier. | | `customFields.extraField.name` | Name of the Extra field in SameSystem. | | `customFields.value` | Value stored in the field. | | `customFields.selectedChoices.value` | Value of the selected option for selection fields. | | `customFields.selectedChoices.label` | Display label of the selected option for selection fields. | #### Example response The following example contains two Extra fields. The first field has the Custom ID `employeeBenefits`, while the second does not have a Custom ID configured: ```json { "customFields": [ { "value": "Free soft drinks", "extraField": { "customId": "employeeBenefits", "name": "Employee benefits", "id": "14507" }, "selectedChoices": null }, { "value": "P2", "extraField": { "customId": null, "name": "Assigned parking area", "id": "14707" }, "selectedChoices": [ { "label": "Parking Area P2", "value": "P2" } ] } ] } ``` Integration code can identify the first field using: `employeeBenefits` rather than the client-specific SameSystem ID: `14507` --- # 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/data-models/custom-fields.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.