> ## 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 Employee Competence > Partially update an existing Employee Competence. Each property in the request replaces that property's whole timeline; properties not included are left untouched. ## OpenAPI ````yaml https://api.twine.se/spec/openapi.json patch /v1/org/employee-competences/{employee_competence_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/employee-competences/{employee_competence_id}: patch: tags: - Employee Competences summary: Update Employee Competence description: >- Partially update an existing Employee Competence. Each property in the request replaces that property's whole timeline; properties not included are left untouched. operationId: patchEmployeeCompetence parameters: - description: '' in: path name: employee_competence_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/EmployeeCompetenceUpsertRequest' description: Employee Competence Upsert Request required: false responses: '200': content: application/json: schema: $ref: '#/components/schemas/EmployeeCompetenceResponse' description: 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 '404': content: application/json: schema: $ref: '#/components/schemas/NotFoundError' description: Not Found Response '500': content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' description: Internal Error Response callbacks: {} components: schemas: EmployeeCompetenceUpsertRequest: description: Represents a request to upsert an employee-competence assignment properties: data: $ref: '#/components/schemas/EmployeeCompetenceUpsert' job_options: $ref: '#/components/schemas/EmployeeCompetenceJobOptions' required: - data title: EmployeeCompetenceUpsertRequest type: object EmployeeCompetenceResponse: description: An employee-competence assignment response properties: data: $ref: '#/components/schemas/EmployeeCompetence' required: - data title: EmployeeCompetenceResponse 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 NotFoundError: description: Resource not found error properties: code: example: 404 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: Not Found type: string required: - code - message - errors title: NotFoundError type: object EmployeeCompetenceUpsert: description: >- An object representing an upsertable employee-competence assignment. Creating requires `employee_id` and `competence_id`. properties: competence_id: description: >- The UUID of the catalogue competence this assignment refers to. Specific for Twine example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b nullable: true type: string employee_id: description: >- The UUID of the employee this assignment belongs to. Specific for Twine example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b nullable: true type: string mappings: description: Cross-system identity links to set on the assignment items: $ref: '#/components/schemas/EmployeeCompetenceMapping' nullable: true type: array properties: $ref: '#/components/schemas/TerseEmployeeCompetenceProperties' source_system: $ref: '#/components/schemas/SystemSlug' required: - source_system title: EmployeeCompetenceUpsert type: object EmployeeCompetenceJobOptions: description: >- Represents options for the resulting Job when upserting employee competences. Changes propagate through the competence-assignment domain, which needs its own domain mapping — writing an assignment never re-replicates the employee. properties: domain_mapping_id: description: >- The specific domain mapping ID to use when queueing the replication job. If not provided, jobs will be queued for all outgoing Competence Assignment domain mappings with Twine configured as source. example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b format: uuid nullable: true type: string queue_job: description: >- Whether to queue a replication job to propagate the changes made in this call. Defaults to true. Will queue jobs for all outgoing Competence Assignment domain mappings with Twine configured as source unless `domain_mapping_id` is specified. example: true type: boolean schedule_in: default: 60 description: >- Delay before the queued job runs, in seconds. Defaults to 60. A caller that writes in batches sets its own window here — assignments written before the job starts join it rather than queueing another. Pass 0 to run as soon as a worker is free. example: 0 nullable: true type: integer title: EmployeeCompetenceJobOptions type: object EmployeeCompetence: description: >- An employee-competence assignment — one employee holding one catalogue competence properties: competence_id: description: >- The UUID of the catalogue competence this assignment refers to. Specific for Twine example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b nullable: true type: string employee_id: description: >- The UUID of the employee this assignment belongs to. Specific for Twine example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b nullable: true type: string id: description: The employee-competence assignment's UUID. Specific for Twine example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b nullable: true type: string inserted_at: description: Inserted timestamp example: '2021-06-01T12:00:00Z' format: date-time nullable: true type: string mappings: items: $ref: '#/components/schemas/EmployeeCompetenceMapping' nullable: true type: array org_id: description: The assignment's organization UUID. Specific for Twine example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b nullable: true type: string properties: $ref: '#/components/schemas/EmployeeCompetenceProperties' source_system: $ref: '#/components/schemas/SystemSlug' updated_at: description: Last updated timestamp example: '2021-06-01T12:00:00Z' format: date-time nullable: true type: string valid_from: description: Date the assignment becomes valid example: '2021-06-01' format: date nullable: true type: string valid_to: description: Date the assignment stops being valid example: '2024-06-01' format: date nullable: true type: string required: - id - org_id title: EmployeeCompetence type: object EmployeeCompetenceMapping: description: Cross-system identity link for an employee-competence assignment properties: external_id: description: The employee-competence assignment's ID in the mapped system example: EMP-COMP-1024 type: string id: description: The mapping's UUID. Specific for Twine example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b nullable: true type: string status: description: Whether the mapping is currently active enum: - active - inactive example: active type: string status_updated_at: description: When the mapping's status last changed format: date-time nullable: true type: string system_integration_id: description: The system integration UUID the external_id belongs to example: 018eae56-8f9d-7ca0-bea3-17f3db6cf75b type: string required: - external_id - system_integration_id title: EmployeeCompetenceMapping type: object TerseEmployeeCompetenceProperties: description: > Date-tracked properties for an Employee Competence. * Only used for creating/updating * Dated property `null` values will be ignored. To reset a dated property, send `[]` instead of `null` nullable: true properties: custom_properties: additionalProperties: $ref: '#/components/schemas/DatedCustomProperties' nullable: true type: object issued_by: example: - valid_from: '2021-06-01' value: null items: $ref: '#/components/schemas/TerseDatedStringProperty' nullable: true type: array level: description: Free-form proficiency — translated per target by property mappings example: - valid_from: '2021-06-01' value: null items: $ref: '#/components/schemas/TerseDatedStringProperty' nullable: true type: array notes: example: - valid_from: '2021-06-01' value: null items: $ref: '#/components/schemas/TerseDatedStringProperty' nullable: true type: array source_external_id: example: - valid_from: '2021-06-01' value: null items: $ref: '#/components/schemas/TerseDatedStringProperty' nullable: true type: array valid_from: example: - valid_from: '2021-06-01' value: '2021-06-01T12:00:00Z' items: $ref: '#/components/schemas/TerseDatedDateProperty' nullable: true type: array valid_to: example: - valid_from: '2021-06-01' value: '2021-06-01T12:00:00Z' items: $ref: '#/components/schemas/TerseDatedDateProperty' nullable: true type: array title: TerseEmployeeCompetenceProperties type: object 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 EmployeeCompetenceProperties: description: Date-tracked properties for an Employee Competence nullable: true properties: custom_properties: additionalProperties: $ref: '#/components/schemas/DatedCustomProperties' nullable: true type: object issued_by: example: - valid_from: '2021-06-01' value: null items: $ref: '#/components/schemas/DatedProperty' nullable: true type: array level: description: Free-form proficiency — translated per target by property mappings example: - valid_from: '2021-06-01' value: null items: $ref: '#/components/schemas/DatedProperty' nullable: true type: array notes: example: - valid_from: '2021-06-01' value: null items: $ref: '#/components/schemas/DatedProperty' nullable: true type: array source_external_id: example: - valid_from: '2021-06-01' value: null items: $ref: '#/components/schemas/DatedProperty' nullable: true type: array valid_from: example: - valid_from: '2021-06-01' value: '2021-06-01T12:00:00Z' items: $ref: '#/components/schemas/DatedProperty' nullable: true type: array valid_to: example: - valid_from: '2021-06-01' value: '2021-06-01T12:00:00Z' items: $ref: '#/components/schemas/DatedProperty' nullable: true type: array title: EmployeeCompetenceProperties type: object DatedCustomProperties: items: $ref: '#/components/schemas/DatedProperty' title: DatedCustomProperties type: array TerseDatedStringProperty: description: A date-tracked property with a string type properties: id: description: >- Discriminator for identifiable values. Usually the ID from the source system nullable: true type: string valid_from: format: date nullable: true type: string value: nullable: true type: string required: - value title: TerseDatedStringProperty type: object TerseDatedDateProperty: description: A date-tracked property with a date type properties: id: description: >- Discriminator for identifiable values. Usually the ID from the source system nullable: true type: string valid_from: format: date nullable: true type: string value: format: date nullable: true type: string required: - value title: TerseDatedDateProperty type: object DatedProperty: description: A date-tracked property with a generic/unknown type properties: id: description: >- Discriminator for identifiable values. Usually the ID from the source system nullable: true type: string key: description: The property key type: string type: description: The value's scalar type enum: - enum - time - datetime - date - boolean - float - integer - number - string nullable: true type: string valid_from: format: date nullable: true type: string value: anyOf: - nullable: true type: string - format: date nullable: true type: string - format: date-time nullable: true type: string - nullable: true type: integer - nullable: true type: number - nullable: true type: boolean - items: type: string nullable: true type: array - items: format: date type: string nullable: true type: array - items: format: date-time type: string nullable: true type: array - items: type: integer nullable: true type: array - items: type: number nullable: true type: array - items: type: boolean nullable: true type: array required: - key - type - valid_from - value - id title: DatedProperty type: object securitySchemes: BearerAuth: bearerFormat: JWT description: Bearer token for authentication scheme: bearer type: http ````