> ## Documentation Index > Fetch the complete documentation index at: https://docs.twine.se/llms.txt > Use this file to discover all available pages before exploring further. # Update System Integration > Updates a system integration ## OpenAPI ````yaml https://api.twine.se/spec/openapi.json put /v1/org/system-integrations/{id} openapi: 3.0.3 info: contact: email: help@twine.se name: Twine Support description: >+ # Introduction Welcome to the Twine Public API reference. This API allows you to read data from Twine's system, and to write data back for supported domains. See the Pushing data section below for what can be written. # Versioning The API is versioned. The current version is v1.1, served under the `/v1` path. As the API is subject to change, new versions may be released. Always refer to the latest documentation to ensure you're using the correct version. ## Dated model attributes In v1.1, every entity field is tracked by change date. This allows you to fetch data as it existed at a specific point in time, or retrieve all changes from a specific point in time up to the present. You can also supply a shape to the API to get data in a format that suits your needs. ### Dated values In the v1.1 model, all fields are represented by an array of values with an optional valid_from timestamp. A null value for valid_from indicates that the field value is valid from the beginning of time, meaning it has no recorded history in the system. When multiple values exist in the array, they are sorted in descending order with the most recent value first. The last value may or may not have a null timestamp. An array can never contain more than one value with a null timestamp. # Authentication The Twine public API uses Bearer token authentication. The token should be sent in the `Authorization` header with the value `Bearer `. ## Provisioning a token To provision a token, you must first generate a long-lived refresh token using Twine backoffice. This token can then be used to generate short-lived access tokens. The refresh token should be kept secret and never shared. Follow these steps to obtain an access token: 1. Invoke `/provisioning/refresh-token/begin` using the JTI you received when provisioning the refresh token. 2. The response will contain a `salt` value 3. Concatenate the salt with the refresh token, separated by a colon (`:`) 4. Hash the concatenated string using SHA256, e.g. `sha256 ":"` 5. The hash should be in lower case 6. Invoke `/provisioning/refresh-token/refresh` with the JTI (as `jti`) and the hash (as `signature`) in the body 7. The response will contain an access token ## Legacy tokens Legacy tokens are still supported. These tokens are long-lived and can be used to authenticate against the API. However, we recommend using the new token provisioning system. ## Token expiration Provisioned tokens are short-lived. Decode them to find the expiry time. Legacy tokens have longer expiry times. # Filtering Some endpoints allow filtering on certain fields. Not all fields are filterable, and filter operations may vary between fields. Refer to specific endpoints to discover what is possible. All filters follow the same structure: ```bash GET /v1/org/employees?filters[updated_at][value]=2022-01-01T00:00:00Z&filters[updated_at][op]=gt ``` # Ordering Some endpoints allow ordering on certain fields. Not all fields are orderable. Refer to specific endpoints to discover what is possible. All ordering follows the same structure: ```bash GET /v1/org/employees?order[field]=updated_at&order[direction]=desc ``` # Data reliability A given piece of data is a snapshot of the latest data fetched from the Vendor. In some cases the data returned by Twine will be out of sync with the Vendor. This is due to the nature of the integration and the data provided by the Vendor. Twine will always strive to provide the most accurate data possible. Depending on the Customer, the data may be updated in near real-time, or with a longer delay. # Permissions All API requests are subject to a permissions check. Permissions are configured by Twine staff or an approved external admin. # Rate limiting The API is not currently rate limited. However, you should expect this to change in the near future. At that time you will start receiving 429 Too Many Requests responses. More information will be provided here when rate limiting is implemented. ## Fetching single resources When requesting single resources with inadequate permissions, you will receive a 403 Forbidden in response. ## Fetching lists of resources When requesting a list of resources, the API will filter out resources you do not have access to. This means that the response may contain fewer resources than requested. The API will always return a 200 OK response, even if the list is empty. # Pushing data NOTE: The API currently only supports the `employee` domain for writing data. There are multiple considerations to take into account when writing data to the API. * In order to write data, the role being used must have the `create` and/or `update` permissions for the `employee` domain. * As per the RESTful API design specs, the `POST` method is used to create new resources, while the `PUT` method is used to update existing resources, and the `PATCH` method is used to partially update existing resources. * Even though `PATCH` will not touch unspecified dated properties, it will still replace all entries of targeted dated properties with the new values provided in the request body. This means that if you want to keep existing historical values for a given dated property, you must include them in the request body. This behaviour can be changed in the future given enough demand. * If there are incoming domain mappings for the `employee` domain, you should avoid updating any properties that are mapped in those integrations. Otherwise there will be uncertainty about which integration is responsible for the data. * If there is a configured `twine` integration with outgoing domain mappings for the `employee` domain, a replication job will be created to push the changes to the configured integration. If you want to avoid this, create a condition in the target integration. # Nomenclature Throughout the API, we use the following terms: | Term | Description | |-------------|-------------| | Customer | The entity on whose behalf Twine processes personnel data | | Vendor | Third party supplier of data with which Twine integrates on behalf of Customer | # FAQ ### Do you have a sandbox environment? Yes. Please contact Twine support to get access. ### Are there webhooks? Not yet, but it is on the roadmap. ### How can I keep the response body small? Use the `select` parameter to only fetch the fields you need. This will reduce the response size and speed up the request. Combine this with filtering by `updated_at` to only fetch the data that has changed since your last request. title: | Twine Public API version: | v1.2 x-logo: altText: Twine Logo backgroundColor: '#00000000' url: >- https://images.squarespace-cdn.com/content/v1/63cec8699b6d396be083ed8b/a2746b2d-2582-49f0-93bb-99a8765c5450/LogoTwineHorizontal.png?format=12w servers: - description: Twine Public Production API url: https://api.twine.se variables: {} - description: Twine Public Staging API url: https://api-stage.twine.se variables: {} security: - BearerAuth: [] tags: - description: >+ # Fetching Employees can be retrieved in paginated lists, or one by one. The employee object remains the same in both cases. # Data consistency Twine allows Customers to map their data to their own wishes. In some cases, fields might not contain what you expect. Fields like `first_name` and `private_id_number` are more or less guaranteed to contain what you expect. However, fields like `phone1`, `phone2` might mean different things depending on the Customer. Some Customers will want to store an employee's private phone number in `phone1`, while others will store the work phone number instead. Always refer to the Customer's data mapping (upcoming API endpoint) to understand what the fields contain. name: Employees - description: > # Fetching Organizational units can be retrieved in paginated lists, or one by one. The organizational unit object remains the same in both cases. # Data consistency Twine will attempt to normalize the source system's organizational unit tier. If successful, the `tier` field will contain the normalized tier and be of type [OrganizationalUnitTier](#model/organizationalunittier) name: Organizational Units - description: >+ # Fetching Time reports can be retrieved in paginated lists. # Time types Twine allows Customers to map their time types to their own wishes. In some cases, time types might not contain what you expect. name: Time Reports paths: /v1/org/system-integrations/{id}: put: tags: - SystemIntegrations summary: Update System Integration description: Updates a system integration operationId: updateSystemIntegration parameters: - description: '' in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SystemIntegrationUpdateRequest' description: System Integration Update Request required: false responses: '200': content: application/json: schema: $ref: '#/components/schemas/SystemIntegrationResponse' description: System Integration Response '400': content: application/json: schema: $ref: '#/components/schemas/BadRequestError' description: Bad Request Response '403': content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' description: Forbidden Response '500': content: application/json: schema: $ref: '#/components/schemas/InternalServerError' description: Internal Error Response callbacks: {} components: schemas: SystemIntegrationUpdateRequest: description: Schema for creating a system integration properties: auth: $ref: '#/components/schemas/SystemIntegrationAuth' description: description: Optional description of the system integration nullable: true type: string system_custom: $ref: '#/components/schemas/SystemCustom' required: - auth - system_custom title: SystemIntegrationUpdateRequest type: object SystemIntegrationResponse: description: A response object with a single system integration properties: data: $ref: '#/components/schemas/SystemIntegration' required: - data title: SystemIntegrationResponse type: object BadRequestError: description: Bad request error properties: code: example: 400 type: integer errors: default: [] items: description: Singular error properties: domain: type: string message: type: string reason: type: string required: - domain - reason - message title: InnerError type: object type: array message: example: Bad Request type: string required: - code - message - errors title: BadRequestError type: object ForbiddenError: description: Forbidden error properties: code: example: 403 type: integer errors: default: [] items: description: Singular error properties: domain: type: string message: type: string reason: type: string required: - domain - reason - message title: InnerError type: object type: array message: example: Forbidden type: string required: - code - message - errors title: ForbiddenError type: object InternalServerError: description: Internal server error properties: code: example: 500 type: integer errors: default: [] items: description: Singular error properties: domain: type: string message: type: string reason: type: string required: - domain - reason - message title: InnerError type: object type: array message: example: Internal Server Error type: string required: - code - message - errors title: InternalServerError type: object SystemIntegrationAuth: description: Authentication schema for a System Integration discriminator: mapping: aboard: $ref: '#/components/schemas/TeamTailorAboardAuth' agda_ps: $ref: '#/components/schemas/AgdaPsAuth' alexis_hr: $ref: '#/components/schemas/SimployerOneAuth' entra_id: $ref: '#/components/schemas/EntraIdAuth' evity: $ref: '#/components/schemas/EvityHrAuth' flex_hrm: $ref: '#/components/schemas/FlexHRMAuth' fortnox: $ref: '#/components/schemas/FortnoxAuth' hailey_hr: $ref: '#/components/schemas/HaileyHRAuth' heartpace: $ref: '#/components/schemas/HeartpaceAuth' hibob: $ref: '#/components/schemas/HibobAuth' hogia_open_hr: $ref: '#/components/schemas/HogiaOpenHrAuth' huma_hr: $ref: '#/components/schemas/HumaHRAuth' kontek: $ref: '#/components/schemas/KontekAuth' pe_accounting: $ref: '#/components/schemas/KleerAuth' people_core: $ref: '#/components/schemas/PeopleCoreAuth' personio: $ref: '#/components/schemas/PersonioAuth' s3: $ref: '#/components/schemas/S3Auth' sftp: $ref: '#/components/schemas/SFTPAuth' skovik: $ref: '#/components/schemas/SkovikAuth' teamtailor: $ref: '#/components/schemas/TeamTailorAuth' twenty_four_seven: $ref: '#/components/schemas/TwentyFourSevenAuth' propertyName: slug oneOf: - $ref: '#/components/schemas/HeartpaceAuth' - $ref: '#/components/schemas/TeamTailorAboardAuth' - $ref: '#/components/schemas/TwentyFourSevenAuth' - $ref: '#/components/schemas/TeamTailorAuth' - $ref: '#/components/schemas/SkovikAuth' - $ref: '#/components/schemas/SFTPAuth' - $ref: '#/components/schemas/S3Auth' - $ref: '#/components/schemas/PersonioAuth' - $ref: '#/components/schemas/PeopleCoreAuth' - $ref: '#/components/schemas/KleerAuth' - $ref: '#/components/schemas/KontekAuth' - $ref: '#/components/schemas/HumaHRAuth' - $ref: '#/components/schemas/HogiaOpenHrAuth' - $ref: '#/components/schemas/HibobAuth' - $ref: '#/components/schemas/HaileyHRAuth' - $ref: '#/components/schemas/FortnoxAuth' - $ref: '#/components/schemas/FlexHRMAuth' - $ref: '#/components/schemas/EntraIdAuth' - $ref: '#/components/schemas/EvityHrAuth' - $ref: '#/components/schemas/SimployerOneAuth' - $ref: '#/components/schemas/AgdaPsAuth' title: SystemIntegrationAuth SystemCustom: description: Custom configuration for system integrations. discriminator: mapping: agda_file: $ref: '#/components/schemas/AgdaFileSystemCustom' agda_ps: $ref: '#/components/schemas/AgdaPsSystemCustom' alexis_hr: $ref: '#/components/schemas/SimployerOneSystemCustom' bamboo_hr: $ref: '#/components/schemas/BambooHrSystemCustom' entra_id: $ref: '#/components/schemas/EntraIdSystemCustom' evity: $ref: '#/components/schemas/EvityHrSystemCustom' flex_hrm: $ref: '#/components/schemas/FlexHrmSystemCustom' fortnox: $ref: '#/components/schemas/FortnoxSystemCustom' hailey_hr: $ref: '#/components/schemas/HaileyHrSystemCustom' hibob: $ref: '#/components/schemas/HibobSystemCustom' hogia_file: $ref: '#/components/schemas/HogiaPlusHrSystemCustomSchema' hogia_open_hr: $ref: '#/components/schemas/HogiaOpenHrSystemCustomSchema' huma_hr: $ref: '#/components/schemas/HumaHrSystemCustom' json_file: $ref: '#/components/schemas/JsonFileSystemCustom' kontek: $ref: '#/components/schemas/KontekSystemCustom' manual_download: $ref: '#/components/schemas/ManualDownloadSystemCustom' paxml: $ref: '#/components/schemas/PaxmlSystemCustom' pe_accounting: $ref: '#/components/schemas/KleerSystemCustom' people_core: $ref: '#/components/schemas/PeopleCoreSystemCustom' personio: $ref: '#/components/schemas/PersonioSystemCustom' s3: $ref: '#/components/schemas/S3SystemCustom' sftp: $ref: '#/components/schemas/SftpSystemCustom' skovik: $ref: '#/components/schemas/SkovikSystemCustom' spreadsheet: $ref: '#/components/schemas/SpreadsheetSystemCustom' teamtailor: $ref: '#/components/schemas/TeamtailorSystemCustom' time_recorder: $ref: '#/components/schemas/TimeRecorderSystemCustom' twenty_four_seven: $ref: '#/components/schemas/TwentyFourSevenSystemCustom' twine: $ref: '#/components/schemas/TwineSystemCustom' propertyName: slug oneOf: - $ref: '#/components/schemas/AgdaFileSystemCustom' - $ref: '#/components/schemas/AgdaPsSystemCustom' - $ref: '#/components/schemas/BambooHrSystemCustom' - $ref: '#/components/schemas/SpreadsheetSystemCustom' - $ref: '#/components/schemas/EntraIdSystemCustom' - $ref: '#/components/schemas/EvityHrSystemCustom' - $ref: '#/components/schemas/FlexHrmSystemCustom' - $ref: '#/components/schemas/FortnoxSystemCustom' - $ref: '#/components/schemas/HaileyHrSystemCustom' - $ref: '#/components/schemas/HibobSystemCustom' - $ref: '#/components/schemas/HogiaOpenHrSystemCustomSchema' - $ref: '#/components/schemas/HogiaPlusHrSystemCustomSchema' - $ref: '#/components/schemas/HumaHrSystemCustom' - $ref: '#/components/schemas/JsonFileSystemCustom' - $ref: '#/components/schemas/KleerSystemCustom' - $ref: '#/components/schemas/KontekSystemCustom' - $ref: '#/components/schemas/ManualDownloadSystemCustom' - $ref: '#/components/schemas/PaxmlSystemCustom' - $ref: '#/components/schemas/PeopleCoreSystemCustom' - $ref: '#/components/schemas/PersonioSystemCustom' - $ref: '#/components/schemas/S3SystemCustom' - $ref: '#/components/schemas/SftpSystemCustom' - $ref: '#/components/schemas/SimployerOneSystemCustom' - $ref: '#/components/schemas/SkovikSystemCustom' - $ref: '#/components/schemas/TeamtailorSystemCustom' - $ref: '#/components/schemas/TwentyFourSevenSystemCustom' - $ref: '#/components/schemas/TimeRecorderSystemCustom' - $ref: '#/components/schemas/TwineSystemCustom' title: SystemCustom SystemIntegration: description: An object representing a system integration in Twine. properties: api_client_id: description: >- For integrations using API client id/secret combinations, this is the API client ID. example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b nullable: true type: string api_endpoint_url: description: >- The API endpoint URL for the integration. Not required for all integration types. example: https://your-company.api.example.com/v1 nullable: true type: string domain_mappings: description: >- List of incoming domain mappings associated with this system integration. Not returned when updating. items: $ref: '#/components/schemas/DomainMapping' nullable: true type: array external_org_id: description: >- The external system's internal ID for this customer, where applicable. nullable: true type: string id: description: The system integration's UUID example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string inserted_at: description: Timestamp of when the system integration was created example: '2021-06-01T12:00:00Z' format: date-time type: string org_id: description: The parent organization's UUID example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string property_mappings: description: >- List of property mappings associated with this system integration. Not returned when updating. items: $ref: '#/components/schemas/PropertyMapping' nullable: true type: array system: $ref: '#/components/schemas/System' system_custom: $ref: '#/components/schemas/SystemCustom' system_id: description: The parent system's UUID example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string updated_at: description: Timestamp of when the system integration was last updated example: '2021-06-01T12:00:00Z' format: date-time type: string required: - id - org_id - system_id title: SystemIntegration type: object TeamTailorAboardAuth: description: Schema for TeamTailorAboard authentication properties: api_key: nullable: true type: string slug: description: Discriminator for the type of system integration enum: - aboard type: string required: - api_key - slug title: TeamTailorAboardAuth type: object AgdaPsAuth: description: Schema for AgdaPs authentication properties: api_client_id: description: >- A service account username/email. This is usually supplied by Agda or an accounting firm nullable: true type: string api_client_secret: description: >- A service account password. This is usually supplied by Agda or an accounting firm nullable: true type: string api_key: description: >- API key with access to the Agda PS installation. This is usually supplied by Agda or an accounting firm nullable: true type: string slug: description: Discriminator for the type of system integration enum: - agda_ps type: string required: - api_client_id - api_client_secret - api_key - slug title: AgdaPsAuth type: object SimployerOneAuth: description: Schema for SimployerOne authentication properties: api_key: nullable: true type: string slug: description: Discriminator for the type of system integration enum: - alexis_hr type: string required: - api_key - slug title: SimployerOneAuth type: object EntraIdAuth: description: >- Do not set this if `customer_defined_application` in Entra's configuration is false properties: api_client_secret: description: >- API Key to a customer managed Application. Should not be set for Application managed by Twine nullable: true type: string slug: description: Discriminator for the type of system integration enum: - entra_id type: string required: - api_client_secret - slug title: EntraIdAuth type: object EvityHrAuth: description: Schema for EvityHr authentication properties: api_endpoint_url: nullable: true type: string api_key: nullable: true type: string slug: description: Discriminator for the type of system integration enum: - evity type: string required: - api_key - api_endpoint_url - slug title: EvityHrAuth type: object FlexHRMAuth: description: Schema for FlexHRM authentication properties: api_client_id: description: >- The username/email for the Flex HRM API. This user should have sufficient permissions to access the Flex HRM instance nullable: true type: string api_client_secret: description: Password for the user specified in `api_client_id` nullable: true type: string api_endpoint_url: description: The URL to the Flex HRM instance API nullable: true type: string slug: description: Discriminator for the type of system integration enum: - flex_hrm type: string required: - api_client_id - api_client_secret - api_endpoint_url - slug title: FlexHRMAuth type: object FortnoxAuth: description: Fortnox requires OAuth 2.0 authentication properties: slug: description: Discriminator for the type of system integration enum: - fortnox type: string required: - slug title: FortnoxAuth type: object HaileyHRAuth: description: Schema for HaileyHR authentication properties: api_key: description: API key for Hailey HR nullable: true type: string slug: description: Discriminator for the type of system integration enum: - hailey_hr type: string required: - api_key - slug title: HaileyHRAuth type: object HeartpaceAuth: description: Schema for Heartpace authentication properties: api_key: nullable: true type: string slug: description: Discriminator for the type of system integration enum: - heartpace type: string required: - api_key - slug title: HeartpaceAuth type: object HibobAuth: description: Schema for Hibob authentication properties: api_client_id: description: The service ID for the Hibob API. e.g. "SERVICE-202" nullable: true type: string api_client_secret: description: The secret key for the Hibob API. nullable: true type: string slug: description: Discriminator for the type of system integration enum: - hibob type: string required: - api_client_id - api_client_secret - slug title: HibobAuth type: object HogiaOpenHrAuth: description: Schema for HogiaOpenHr authentication properties: api_client_id: nullable: true type: string api_client_secret: nullable: true type: string api_endpoint_url: nullable: true type: string slug: description: Discriminator for the type of system integration enum: - hogia_open_hr type: string required: - api_client_id - api_client_secret - api_endpoint_url - slug title: HogiaOpenHrAuth type: object HumaHRAuth: description: Schema for HumaHR authentication properties: api_client_secret: description: >- Client Key Secret used by Huma when sending webhook requests. This can be anything you want, but must be kept in sync with the value in Huma. nullable: true type: string api_key: description: >- Webhook Access Key used by Huma when sending webhook requests. This can be anything you want, but must be kept in sync with the value in Huma. nullable: true type: string slug: description: Discriminator for the type of system integration enum: - huma_hr type: string required: - api_key - api_client_secret - slug title: HumaHRAuth type: object KontekAuth: description: Schema for Kontek authentication properties: api_client_id: description: >- The username/email for the Kontek Lön API. This user should have sufficient permissions to access the Kontek Lön instance nullable: true type: string api_client_secret: description: Password for the user specified by `api_client_id` nullable: true type: string api_endpoint_url: description: The URL to the Kontek Lön instance API nullable: true type: string api_key: description: >- Secret access key for the Kontek Lön API. This is supplied by Kontek Lön nullable: true type: string external_org_id: description: Company ID in Kontek Lön nullable: true type: string slug: description: Discriminator for the type of system integration enum: - kontek type: string required: - api_client_id - api_client_secret - api_endpoint_url - api_key - external_org_id - slug title: KontekAuth type: object KleerAuth: description: Schema for Kleer authentication properties: api_key: description: >- The secret API Token for the Kleer API. This is supplied by Kleer customer service. nullable: true type: string external_org_id: description: >- The ID of the organization in Kleer. This is usually supplied together with the API Token. nullable: true type: string slug: description: Discriminator for the type of system integration enum: - pe_accounting type: string required: - api_key - external_org_id - slug title: KleerAuth type: object PeopleCoreAuth: description: Schema for PeopleCore authentication properties: api_client_id: nullable: true type: string api_client_secret: nullable: true type: string slug: description: Discriminator for the type of system integration enum: - people_core type: string required: - api_client_id - api_client_secret - slug title: PeopleCoreAuth type: object PersonioAuth: description: Schema for Personio authentication properties: api_client_id: nullable: true type: string api_client_secret: nullable: true type: string slug: description: Discriminator for the type of system integration enum: - personio type: string required: - api_client_id - api_client_secret - slug title: PersonioAuth type: object S3Auth: description: Schema for S3 authentication properties: api_client_id: nullable: true type: string api_client_secret: nullable: true type: string slug: description: Discriminator for the type of system integration enum: - s3 type: string required: - api_client_id - api_client_secret - slug title: S3Auth type: object SFTPAuth: description: Schema for SFTP authentication properties: api_client_id: description: SFTP Username nullable: true type: string api_client_secret: description: SFTP Password nullable: true type: string slug: description: Discriminator for the type of system integration enum: - sftp type: string required: - api_client_id - api_client_secret - slug title: SFTPAuth type: object SkovikAuth: description: Schema for Skovik authentication properties: api_key: nullable: true type: string slug: description: Discriminator for the type of system integration enum: - skovik type: string required: - api_key - slug title: SkovikAuth type: object TeamTailorAuth: description: Schema for TeamTailor authentication properties: api_endpoint_url: nullable: true type: string api_key: nullable: true type: string slug: description: Discriminator for the type of system integration enum: - teamtailor type: string required: - api_key - api_endpoint_url - slug title: TeamTailorAuth type: object TwentyFourSevenAuth: description: Schema for TwentyFourSeven authentication properties: api_key: nullable: true type: string slug: description: Discriminator for the type of system integration enum: - twenty_four_seven type: string required: - api_key - slug title: TwentyFourSevenAuth type: object AgdaFileSystemCustom: description: Custom configuration for Agda File system integrations. properties: slug: enum: - agda_file nullable: false type: string required: - slug title: AgdaFileSystemCustom type: object AgdaPsSystemCustom: description: Custom configuration for Agda PS system integrations. properties: auth_scheme: description: The authentication scheme to use for this Agda PS integration. enum: - basic - bearer nullable: true type: string slug: enum: - agda_ps nullable: false type: string title: AgdaPsSystemCustom type: object SimployerOneSystemCustom: description: Custom configuration for SimployerOne system integrations. properties: slug: enum: - alexis_hr nullable: false type: string title: SimployerOneSystemCustom type: object BambooHrSystemCustom: description: Custom configuration for BambooHR system integrations. properties: slug: enum: - bamboo_hr nullable: false type: string subdomain: description: The subdomain for the BambooHR account. nullable: true type: string title: BambooHrSystemCustom type: object EntraIdSystemCustom: description: Custom configuration for EntraID system integrations. properties: application_id: description: >- The application ID for the EntraID integration. This is either the ID of a customer-defined application or the ID of a customer-specific application hosted by Twine nullable: true type: string application_permissions: description: The permissions required in the Entra Application. items: type: string nullable: true type: array customer_defined_application: description: Whether to enable API v2 for the EvityHR account. nullable: true type: boolean manual_directory_extension_attributes: description: >- Manually specified directory extension attributes for the EntraID integration. This is sometimes needed when the Graph API does not return these attributes automatically, even though they exist in the customer's directory. items: type: string nullable: true type: array secret_rotation_days: description: >- The number of days before which the secret should be rotated. Note: The secret will likely be rotated before this time. Has no effect if `customer_defined_application` is false. nullable: true type: integer slug: enum: - entra_id nullable: false type: string tenant_id: description: >- The tenant ID for the EntraID integration. Note: This is the customer's tenant ID. nullable: true type: string title: EntraIdSystemCustom type: object EvityHrSystemCustom: description: Custom configuration for EvityHR system integrations. properties: enable_api_v2: description: Whether to enable API v2 for the EvityHR account. nullable: true type: boolean slug: enum: - evity nullable: false type: string title: EvityHrSystemCustom type: object FlexHrmSystemCustom: description: Custom configuration for FlexHrm system integrations. properties: company_nr: description: >- The company number for customer tenant. Reads like a regular number like 12345. nullable: true type: string instance_id: description: >- The instance UUID for customer tenant. Twine will automatically retrieve this value. nullable: true type: string instance_nr: description: >- The instance number for customer tenant. Reads like a regular number like 12345. nullable: true type: string probation_employment_type_id: description: >- The probation employment type UUID for the customer tenant. If this is set, Twine will automatically generate additional employment periods with this as the employment type. Should only be used if the source system cannot provide discreet probationary employment periods. nullable: true type: string slug: enum: - flex_hrm nullable: false type: string title: FlexHrmSystemCustom type: object FortnoxSystemCustom: description: Custom configuration for Fortnox system integrations. properties: insert_zero_salaries: description: >- Whether to insert zero salaries for non-working periods for employees in Fortnox. nullable: true type: boolean scopes: description: >- OAuth scopes requested from Fortnox during authentication. `companyinformation` is always included regardless of this value. items: type: string nullable: true type: array slug: enum: - fortnox nullable: false type: string title: FortnoxSystemCustom type: object HaileyHrSystemCustom: description: Custom configuration for Hailey HR system integrations. properties: slug: enum: - hailey_hr nullable: false type: string use_sandbox_api: default: true description: Whether to use the Hailey HR sandbox API. nullable: true type: boolean title: HaileyHrSystemCustom type: object HibobSystemCustom: description: Custom configuration for Hibob system integrations. properties: enabled_reports: description: A list of report ids that should be enabled for Hibob. items: type: string nullable: true type: array include_private_time_off_requests: default: false description: Whether to include private time off requests. nullable: true type: boolean partner_token_suffix: description: >- The partner token suffix for Hibob. Should be your company name, preferably unchanged once used once. nullable: true type: string slug: enum: - hibob nullable: false type: string title: HibobSystemCustom type: object HogiaPlusHrSystemCustomSchema: description: Custom configuration for Hogia Plus HR File system integrations. properties: slug: enum: - hogia_file nullable: false type: string required: - slug title: HogiaPlusHrSystemCustomSchema type: object HogiaOpenHrSystemCustomSchema: description: Custom configuration for Hogia Open HR File system integrations. properties: slug: enum: - hogia_open_hr nullable: false type: string required: - slug title: HogiaOpenHrSystemCustomSchema type: object HumaHrSystemCustom: description: Custom configuration for Huma HR File system integrations. properties: demo_api: description: >- When true, API calls target Huma's demo environment (demo.openapi.humahr.com) instead of production. Off by default. nullable: true type: boolean last_legacy_webhook_at: description: >- Read-only: when the most recent webhook arrived on the legacy front endpoint. Null once a webhook arrives on the canonical perimeter endpoint. format: date-time nullable: true type: string legacy_webhook_endpoint: description: >- Read-only signal: true when webhooks are still arriving on the legacy front endpoint rather than the canonical perimeter endpoint. Cleared automatically once a webhook arrives on the canonical endpoint. nullable: true type: boolean slug: enum: - huma_hr nullable: false type: string use_webhook_data: description: >- Temporary migration toggle. When true, webhook payloads carry and drive data directly. When false and API credentials are configured, webhooks only trigger an API-backed sync. nullable: true type: boolean required: - slug title: HumaHrSystemCustom type: object JsonFileSystemCustom: description: Custom configuration for JSON file system integrations. properties: input_shape: description: >- How records are read: top-level `array`, `wrapped` array (see records_path), or `jsonl`. enum: - array - wrapped - jsonl type: string link_path: description: Optional JSONPath (per record) used as the entity link id. nullable: true type: string output_records_key: description: >- For output_shape `wrapped`: the key the records array is nested under. nullable: true type: string output_shape: description: Shape of the exported file. enum: - array - wrapped - jsonl type: string records_path: description: >- For input_shape `wrapped`: JSONPath to the records array (e.g. `$.employees`). nullable: true type: string slug: enum: - json_file nullable: false type: string sources: description: The field sources exposed to the property mapper. items: description: >- A group of fields read from each record (scalar) or from a nested array (list). properties: base_path: description: >- List sources only: JSONPath (per record) selecting the array elements. nullable: true type: string end_date_path: description: >- JSONPath whose value becomes the (exclusive) end-date on every DatedProperty. nullable: true type: string fields: description: The fields exposed by this source. items: description: A single mappable field within a JSON file source. properties: id: description: >- Stable id for the field; generated server-side if omitted. nullable: true type: string name: description: Display name shown in the property mapper. nullable: true type: string path: description: >- JSONPath to the value, relative to the record (scalar source) or to each array element (list source). nullable: true type: string title: JsonFileCustomField type: object type: array id: description: Stable id for the source; generated server-side if omitted. nullable: true type: string id_path: description: >- JSONPath whose value becomes the `id` on every DatedProperty (groups parallel value histories). nullable: true type: string ignore: description: Skip this source when parsing. nullable: true type: boolean kind: description: >- `scalar` reads fields off each record; `list` iterates a nested array. enum: - scalar - list type: string name: description: Display name of the source. nullable: true type: string start_date_path: description: >- JSONPath whose value becomes `valid_from` on every DatedProperty. nullable: true type: string title: JsonFileCustomSource type: object type: array title: JsonFileSystemCustom type: object KontekSystemCustom: description: Custom configuration for Kontek system integrations. properties: slug: enum: - kontek nullable: false type: string required: - slug title: KontekSystemCustom type: object ManualDownloadSystemCustom: description: Custom configuration for manual_download file_area integrations. properties: notification_emails: description: >- Email addresses to notify when a new file becomes available for download. Dispatch is not yet enabled. items: type: string nullable: true type: array retention_days: default: 30 description: >- Number of days generated files are retained in internal storage and available for download. maximum: 365 minimum: 1 nullable: true type: integer slug: enum: - manual_download nullable: false type: string title: ManualDownloadSystemCustom type: object PaxmlSystemCustom: description: Custom configuration for Paxml system integrations. properties: report_date_range_strategy: description: The report date range parsing strategy to use for this integration. enum: - auto - header - range - range_rounded nullable: true type: string slug: enum: - paxml nullable: false type: string title: PaxmlSystemCustom type: object KleerSystemCustom: description: Custom configuration for Kleer system integrations. properties: new_customer_project_default_name: description: Default name for new customer projects. nullable: true type: string slug: enum: - pe_accounting nullable: false type: string sync_new_customer_project: default: false description: Whether to sync new customer projects. nullable: true type: boolean use_test_api: default: true description: Whether to use Kleer's test API. nullable: true type: boolean variable_pay_date_range_end: description: Day of month to end syncing variable pay. nullable: true type: integer variable_pay_date_range_start: description: Day of month to start syncing variable pay. nullable: true type: integer title: KleerSystemCustom type: object PeopleCoreSystemCustom: description: Custom configuration for PeopleCore system integrations. properties: scopes: description: The permission scopes to use for this integration. items: type: string nullable: true type: array slug: enum: - people_core nullable: false type: string title: PeopleCoreSystemCustom type: object PersonioSystemCustom: description: Custom configuration for Personio system integrations. properties: compensation_history_months: default: 0 description: >- How many months of compensation history to retrieve, counting back from the current month. Personio caps a single compensation query at one calendar month, so each month is fetched separately. nullable: true type: integer has_compensation_anchor_engine: default: false description: >- Whether a compensation anchor engine is configured. The engine derives a per-employee start date for the compensation window and is edited in the app, not over this API. readOnly: true type: boolean partner_id: description: The Personio partner ID to use for this integration. nullable: true type: string slug: enum: - personio nullable: false type: string title: PersonioSystemCustom type: object S3SystemCustom: description: Custom configuration for S3 system integrations. properties: s3_host: description: The S3 host to connect to. nullable: true type: string s3_region: default: us-east-1 description: The S3 region to connect to. nullable: true type: string slug: enum: - s3 nullable: false type: string title: S3SystemCustom type: object SftpSystemCustom: description: Custom configuration for SFTP system integrations. properties: sftp_host: description: The SFTP host to connect to. nullable: true type: string sftp_port: default: 22 description: The SFTP port to connect to. nullable: true type: integer slug: enum: - sftp nullable: false type: string title: SftpSystemCustom type: object SkovikSystemCustom: description: Custom configuration for Skovik system integrations. properties: slug: enum: - skovik nullable: false type: string required: - slug title: SkovikSystemCustom type: object SpreadsheetSystemCustom: description: Custom configuration for Spreadsheet system integrations. properties: column_order_type: description: The naming scheme used in the XLSX enum: - a1 - r1c1 type: string quote_char: default: '"' description: The character used to quote values in the CSV type: string separator: default: ',' description: The character used to separate values in the CSV type: string sheets: description: >- The sheets to process in the spreadsheet file (CSV/XLSX/ODS). For a CSV file there should only be 1 sheet. items: description: Custom configuration for Spreadsheet system integrations - Sheet. properties: column_names: description: >- The names of the columns to include in the integration. This is not required for the functionality, but can be used to provide better context in the UI. items: type: string nullable: true type: array end_date_column_index: description: >- Index of the column whose value becomes the end-date (exclusive) for every DatedProperty extracted from this row. nullable: true type: integer exclude_row_indexes: default: - 0 description: The indexes of the rows to exclude from processing items: type: integer nullable: true type: array id_column_index: description: >- Index of the column whose value becomes the `id` on every DatedProperty extracted from this row. Use to differentiate parallel value histories (e.g. salary type) within a multirow sheet. nullable: true type: integer ignore: description: Whether to ignore this sheet nullable: true type: boolean link_column_index: description: >- The index of the column that links multiple rows to the same entity. Required if multirows is true. nullable: true type: integer multirows: description: >- If true, indicated that entities can span multiple rows. Should be specified together with link_column_index. nullable: true type: boolean name: description: The name of the sheet nullable: true type: string nr_of_columns: description: The number of columns to read from the sheet nullable: true type: integer start_date_column_index: description: >- Index of the column whose value becomes `valid_from` on every DatedProperty extracted from this row. nullable: true type: integer title: SpreadsheetCustomSheet type: object type: array slug: enum: - spreadsheet nullable: false type: string title: SpreadsheetSystemCustom type: object TeamtailorSystemCustom: description: Custom configuration for Teamtailor system integrations. properties: filter_on_stage_types: description: The authentication scheme to use for this Teamtailor integration. enum: - basic - bearer nullable: true type: string slug: enum: - teamtailor nullable: false type: string title: TeamtailorSystemCustom type: object TimeRecorderSystemCustom: description: Custom configuration for Time Recorder system integrations. properties: slug: enum: - time_recorder nullable: false type: string required: - slug title: TimeRecorderSystemCustom type: object TwentyFourSevenSystemCustom: description: Custom configuration for Twenty Four Seven system integrations. properties: absence_replication: $ref: '#/components/schemas/TwentyFourSevenAbsenceReplication' country_code: description: >- Auto-detected from Payday's organization endpoint on credential save. Drives country-specific V2 payload handling. enum: - SE - 'NO' nullable: true type: string designate_primary_employment: description: Whether Twine designates the primary employment for each employee. nullable: true type: boolean primary_employment_date_offset: $ref: '#/components/schemas/TwentyFourSevenPrimaryEmploymentDateOffset' slug: enum: - twenty_four_seven nullable: false type: string use_v2_replication_pipeline: description: >- Opt-in to the V2 replication pipeline. Requires country_code to be set. nullable: true type: boolean required: - slug title: TwentyFourSevenSystemCustom type: object TwineSystemCustom: description: Custom configuration for Twine system integrations. properties: slug: enum: - twine nullable: false type: string required: - slug title: TwineSystemCustom type: object DomainMapping: description: An object representing a domain mapping. properties: all_conditions_must_apply: description: >- Whether every condition must match (AND) rather than any one of them (OR). Has no effect when `conditions` is empty. example: false nullable: false type: boolean conditions: description: List of conditions associated with this domain mapping. items: $ref: '#/components/schemas/Condition' nullable: true type: array description: description: Free-text description of the mapping. example: Employees from the HR system into payroll nullable: true type: string enabled: description: Whether the domain mapping is enabled example: true nullable: false type: boolean from_domain: description: The source domain for the mapping. enum: - finance - employee_competence - competence - expense_transaction - salary_transaction - file_transfer - project - org_unit - customer - schedule - time_report - employee example: employee title: Domain type: string id: description: The sync trigger's UUID example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string inserted_at: description: Timestamp of when the domain mapping was created example: '2021-06-01T12:00:00Z' format: date-time type: string mode: description: >- `default` is a full read/write mapping. `update_existing_only` syncs updates onto existing Twine entities only — unmapped incoming entities are dropped and replication is refused. enum: - update_existing_only - default example: default nullable: false type: string org_id: description: The parent organization's UUID example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string source_system_integration_id: description: 'The source system integration''s UUID. ' example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string sync_triggers: description: List of sync triggers associated with this domain mapping. items: $ref: '#/components/schemas/SyncTrigger' nullable: true type: array target_system_integration_id: description: 'The source system integration''s UUID. ' example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string to_domain: description: The target domain for the mapping. enum: - finance - employee_competence - competence - expense_transaction - salary_transaction - file_transfer - project - org_unit - customer - schedule - time_report - employee example: employee title: Domain type: string updated_at: description: Timestamp of when the domain mapping was last updated example: '2021-06-01T12:00:00Z' format: date-time type: string required: - id - org_id - source_system_integration_id - target_system_integration_id - from_domain - to_domain - enabled title: DomainMapping type: object PropertyMapping: description: An object representing a property mapping in Twine. properties: common_domain: description: The common/Twine domain enum: - finance - employee_competence - competence - expense_transaction - salary_transaction - file_transfer - project - org_unit - customer - schedule - time_report - employee example: employee nullable: false title: Domain type: string common_path: description: The common path associated with the property mapping. example: - salary_amount items: description: A segment of the common path example: salary_amount nullable: false type: string nullable: false type: array converters: description: >- The list of converters associated with the property mapping. The order of converters matters, as they are applied sequentially. items: $ref: '#/components/schemas/PropertyMappingConverter' nullable: true type: array enabled: description: Whether the property mapping is enabled example: true nullable: false type: boolean engine: description: >- The engine configuration for the property mapping. If set, this takes precedence over converters. nullable: true oneOf: - $ref: '#/components/schemas/PropertyMappingEngineV2' type: object id: description: The property mapping's UUID example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string org_id: description: The organization ID associated with the property mapping example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string reference_domain: description: The reference domain enum: - finance - employee_competence - competence - expense_transaction - salary_transaction - file_transfer - project - org_unit - customer - schedule - time_report - employee example: employee nullable: true title: Domain type: string system_domain: description: The system domain enum: - finance - employee_competence - competence - expense_transaction - salary_transaction - file_transfer - project - org_unit - customer - schedule - time_report - employee example: employee nullable: false title: Domain type: string system_integration_id: description: The system integration ID associated with the property mapping example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string system_path: description: >- The system path associated with the property mapping. The validity of this value depends on the underlying system and system domain example: - salaries - '[]' - amount items: description: A segment of the system path example: salaries nullable: false type: string nullable: false type: array version: description: The version of the property mapping. The latest version is 2. example: 2 nullable: false type: integer required: - id - org_id - system_integration_id - system_domain - common_domain - system_path - common_path title: PropertyMapping type: object System: description: An object representing an integrated system in Twine. properties: description: description: >- Public-facing prose describing what the integration does (Markdown). `null` when the system has no authored description. example: >- The Spreadsheet integration lets Twine exchange employee data as spreadsheet files... nullable: true type: string domains: description: >- The data domains this system supports and in which direction. `null` when the system has not yet declared its domain capabilities. example: - capability: read domain: employee - capability: write domain: time_report items: 771609c6-02d0-440d-8040-6f0bd04de16a nullable: true type: array id: description: >- The system's UUID. This identifier is persistent across all integrations, and should be regarded as well-known. example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string kind: $ref: '#/components/schemas/SystemKind' logo_url: description: URL to the system's logo image example: https://example.com/logos/system-logo.png format: uri nullable: true type: string name: description: The name of the system example: Evity HR nullable: false type: string slug: $ref: '#/components/schemas/SystemSlug' status: description: >- Lifecycle status: `available` systems can be integrated today, `planned` systems are in the catalog but not yet implemented, `deprecated` systems still operate but are closed to new integrations. Always set on the systems catalog endpoint; `null` on embedded system objects. enum: - available - planned - deprecated example: available nullable: true type: string required: - id - name - slug - kind title: System type: object TwentyFourSevenAbsenceReplication: description: Absence replication configuration for V2 pipeline. nullable: true properties: group_by_field: description: Field used to group consecutive absences. enum: - comment - source_external_id - source_external_ids - target_time_type_id nullable: true type: string group_consecutive: description: >- Whether to merge consecutive daily TimeReports sharing the grouping field into a single Payday absence. nullable: true type: boolean title: TwentyFourSevenAbsenceReplication type: object TwentyFourSevenPrimaryEmploymentDateOffset: description: Date offset applied when designating primary employment. nullable: true properties: day: default: 0 nullable: true type: integer month: default: 0 nullable: true type: integer week: default: 0 nullable: true type: integer year: default: 0 nullable: true type: integer title: TwentyFourSevenPrimaryEmploymentDateOffset type: object Condition: description: A condition for filtering data. properties: apply_on_actions: description: List of actions the condition applies to items: enum: - create - update type: string nullable: false type: array condition: description: V2 Graph Engine condition type: object description: description: A brief description of the condition nullable: true type: string domain: description: The data domain enum: - finance - employee_competence - competence - expense_transaction - salary_transaction - file_transfer - project - org_unit - customer - schedule - time_report - employee example: employee title: Domain type: string enabled: default: true description: Whether the condition is enabled type: boolean id: description: The condition's UUID. example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string required: - id - condition - domain - apply_on_actions - enabled title: Condition type: object SyncTrigger: description: An object representing a sync trigger in a domain mapping. properties: cron_expression: description: >- The cron expression for the scheduled trigger. If null, the trigger can only be run manually example: 0 0 * * * nullable: true type: string domain_configuration: description: The domain-specific configuration for the sync trigger. nullable: true oneOf: - $ref: '#/components/schemas/SyncTriggerTimeReportSettings' type: object domain_mapping_id: description: The parent domain mapping's UUID example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string id: description: The sync trigger's UUID example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string last_sync_ended_at: description: >- The last time the sync was completed. It is possible for this timestamp to be earlier than `last_sync_started_at`, which would indicate a failed sync example: '2023-01-01T00:00:00Z' format: date-time nullable: true type: string last_sync_started_at: description: The last time the sync was started. example: '2023-01-01T00:00:00Z' format: date-time nullable: true type: string next_sync_at: description: >- The next scheduled sync time. This is not an exact point in time as the sync will most likely be started shortly afterwards. example: '2023-01-01T00:00:00Z' format: date-time nullable: true type: string org_id: description: The parent organization's UUID example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string parent_id: description: The parent trigger's UUID example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: true type: string system_integration_id: description: The parent system integration's UUID example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: false type: string required: - id - org_id - system_integration_id - domain_mapping_id title: SyncTrigger type: object PropertyMappingConverter: description: An object representing a property mapping converter in Twine. properties: converter: description: >- The logical name of the converter. The validity of this value depends on the system being used. TODO: Add direction to endpoint for fetching all available converters. example: string_to_integer nullable: true type: string pod_id: description: >- The ID of the Graph Engine pod associated with the converter. Cannot be set if `converter` is defined example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b nullable: true type: string title: PropertyMappingConverter type: object PropertyMappingEngineV2: description: An object representing a property mapping engine in Twine. properties: description: description: A description of the property mapping engine. example: This engine maps properties from one format to another. nullable: true type: string domain: description: The data domain enum: - finance - employee_competence - competence - expense_transaction - salary_transaction - file_transfer - project - org_unit - customer - schedule - time_report - employee example: employee title: Domain type: string engine: description: The JSON representation of the engine configuration. nullable: false type: object version: default: '2' description: The version of the property mapping engine. example: '2' nullable: false type: string required: - engine - domain - version title: PropertyMappingEngineV2 type: object SystemKind: description: System kind enum: - other - expenses - time_tracking - file_area - iam - bi - accounting - payroll - hris - ats - hub title: SystemKind type: string SystemSlug: description: System slug enum: - twine - twenty_four_seven - timeplan - time_recorder - tidsbanken - teamtailor - spreadsheet - sp_payroll - skovik - simployer_classic - sftp_server - sftp - scim - s3 - quinyx - personio - people_core - pe_accounting - payzlip - paxml - nmbrs - medvind_wfm - manual_download - looker - kontek - kleer - json_file - huma_hr - hogia_open_hr - hogia_file - hibob - heartpace - hailey_hr - fortnox - flex_hrm - evity - entra_id - catalyst_one - bamboo_hr - alexis_hr - agda_ps - agda_file - aboard title: SystemSlug type: string SyncTriggerTimeReportSettings: description: An object representing the time report settings for a sync trigger. properties: domain: default: time_report description: Must always be `time_report` type: string from_date: description: Explicit from date for the time report sync format: date nullable: true type: string from_date_engine: description: >- Dynamic configuration for the from date. Should not be specified if from_date is set, and vice versa. nullable: true type: object to_date: description: Explicit to date for the time report sync format: date nullable: true type: string to_date_engine: description: >- Dynamic configuration for the to date. Should not be specified if to_date is set, and vice versa. nullable: true type: object title: SyncTriggerTimeReportSettings type: object securitySchemes: BearerAuth: bearerFormat: JWT description: Bearer token for authentication scheme: bearer type: http ````