Quinyx Employee API
The Employee API from Quinyx — 2 operation(s) for employee.
OpenAPI Specification
openapi: 3.1.0
info:
title: Quinyx Absence Schedules Employee API
version: v2
x-service: absence-schedule
description: null
servers:
- url: https://api.quinyx.com
description: Production API
- url: https://api-rc.quinyx.com
description: RC API
tags:
- name: Employee
paths:
/hr/v3/employees/{id}:
get:
tags:
- Employee
summary: Get an employee
description: Retrieves a single employee by its identifier.
operationId: getEmployee
parameters:
- name: id
in: path
description: Employee identifier
required: true
schema:
description: An identifier that can be either a Quinyx ID or a prefixed external ID string.
oneOf:
- type: string
description: The Quinyx ID of the resource.
pattern: ^[0-9]+$
- type: string
description: The external string ID, which must start with 'badgeNumber:'.
example: badgeNumber:1234
pattern: ^badgeNumber:[a-zA-Z0-9._-]{1,64}$
examples:
internal-id:
summary: Internal ID
description: The internal ID of the resource
value: '12345'
badge-number:
summary: Badge number
description: Badge number prefixed with 'badgeNumber:', 1-64 characters long, consisting of alphanumerics and . _ -
value: badgeNumber:B001
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/employee_IntegrationEmployeeResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
oneOf:
- $ref: '#/components/schemas/employee_ProblemDetail'
- $ref: '#/components/schemas/employee_ValidationError'
examples:
badRequestProblemDetail:
summary: Bad request
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/bad-request
title: Bad Request
status: 400
detail: The request is invalid or malformed
instance: /hr/v3/employees/{id}
badRequestValidationError:
summary: Bad request
description: Example ValidationError response
value:
type: https://developer.quinyx.com/api/problems/bad-request
title: Bad Request
status: 400
errors:
- detail: name is mandatory
pointer: '#/name'
instance: /hr/v3/employees/{id}
'401':
description: Unauthorized
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
unauthorized:
summary: Unauthorized
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/unauthorized
title: Unauthorized
status: 401
detail: Access token not set or invalid, and the requested resource could not be returned
instance: /hr/v3/employees/{id}
'403':
description: Forbidden
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
forbidden:
summary: Forbidden
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/forbidden
title: Forbidden
status: 403
detail: The resource could not be returned as the requestor is not authorized
instance: /hr/v3/employees/{id}
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
notFound:
summary: Not found
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/not-found
title: Not Found
status: 404
detail: The requested resource was not found
instance: /hr/v3/employees/{id}
'500':
description: Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
serverError:
summary: Server error
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/server-error
title: Server Error
status: 500
detail: The server encountered an unexpected error
instance: /hr/v3/employees/{id}
security:
- OAuth2ClientCredentials:
- hr:employees:read
x-audience: public
x-resource-group: HR
x-resource: Employee
put:
tags:
- Employee
summary: Update an employee
description: Updates the specified employee with the provided attributes and returns it
operationId: updateEmployee
parameters:
- name: id
in: path
description: Employee identifier
required: true
schema:
description: An identifier that can be either a Quinyx ID or a prefixed external ID string.
oneOf:
- type: string
description: The Quinyx ID of the resource.
pattern: ^[0-9]+$
- type: string
description: The external string ID, which must start with 'badgeNumber:'.
example: badgeNumber:1234
pattern: ^badgeNumber:[a-zA-Z0-9._-]{1,64}$
examples:
internal-id:
summary: Internal ID
description: The internal ID of the resource
value: '12345'
badge-number:
summary: Badge number
description: Badge number prefixed with 'badgeNumber:', 1-64 characters long, consisting of alphanumerics and . _ -
value: badgeNumber:B001
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/employee_IntegrationEmployeeUpdateRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/employee_IntegrationEmployeeResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
oneOf:
- $ref: '#/components/schemas/employee_ProblemDetail'
- $ref: '#/components/schemas/employee_ValidationError'
examples:
badRequestProblemDetail:
summary: Bad request
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/bad-request
title: Bad Request
status: 400
detail: The request is invalid or malformed
instance: /hr/v3/employees/{id}
badRequestValidationError:
summary: Bad request
description: Example ValidationError response
value:
type: https://developer.quinyx.com/api/problems/bad-request
title: Bad Request
status: 400
errors:
- detail: name is mandatory
pointer: '#/name'
instance: /hr/v3/employees/{id}
'401':
description: Unauthorized
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
unauthorized:
summary: Unauthorized
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/unauthorized
title: Unauthorized
status: 401
detail: Access token not set or invalid, and the requested resource could not be returned
instance: /hr/v3/employees/{id}
'403':
description: Forbidden
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
forbidden:
summary: Forbidden
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/forbidden
title: Forbidden
status: 403
detail: The resource could not be returned as the requestor is not authorized
instance: /hr/v3/employees/{id}
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
notFound:
summary: Not found
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/not-found
title: Not Found
status: 404
detail: The requested resource was not found
instance: /hr/v3/employees/{id}
'500':
description: Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
serverError:
summary: Server error
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/server-error
title: Server Error
status: 500
detail: The server encountered an unexpected error
instance: /hr/v3/employees/{id}
security:
- OAuth2ClientCredentials:
- hr:employees:update
x-audience: public
x-resource-group: HR
x-resource: Employee
delete:
tags:
- Employee
summary: Delete an employee
description: Permanently deletes an employee
operationId: deleteEmployee
parameters:
- name: id
in: path
description: Employee identifier
required: true
schema:
description: An identifier that can be either a Quinyx ID or a prefixed external ID string.
oneOf:
- type: string
description: The Quinyx ID of the resource.
pattern: ^[0-9]+$
- type: string
description: The external string ID, which must start with 'badgeNumber:'.
example: badgeNumber:1234
pattern: ^badgeNumber:[a-zA-Z0-9._-]{1,64}$
examples:
internal-id:
summary: Internal ID
description: The internal ID of the resource
value: '12345'
badge-number:
summary: Badge number
description: Badge number prefixed with 'badgeNumber:', 1-64 characters long, consisting of alphanumerics and . _ -
value: badgeNumber:B001
responses:
'200':
description: OK
'401':
description: Unauthorized
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
unauthorized:
summary: Unauthorized
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/unauthorized
title: Unauthorized
status: 401
detail: Access token not set or invalid, and the requested resource could not be returned
instance: /hr/v3/employees/{id}
'403':
description: Forbidden
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
forbidden:
summary: Forbidden
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/forbidden
title: Forbidden
status: 403
detail: The resource could not be returned as the requestor is not authorized
instance: /hr/v3/employees/{id}
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
notFound:
summary: Not found
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/not-found
title: Not Found
status: 404
detail: The requested resource was not found
instance: /hr/v3/employees/{id}
'500':
description: Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
serverError:
summary: Server error
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/server-error
title: Server Error
status: 500
detail: The server encountered an unexpected error
instance: /hr/v3/employees/{id}
security:
- OAuth2ClientCredentials:
- hr:employees:delete
x-audience: public
x-resource-group: HR
x-resource: Employee
patch:
tags:
- Employee
summary: Partially update an employee
description: Partially updates the specified employee with the provided attributes and returns it.
operationId: patchEmployee
parameters:
- name: id
in: path
description: Employee identifier
required: true
schema:
description: An identifier that can be either a Quinyx ID or a prefixed external ID string.
oneOf:
- type: string
description: The Quinyx ID of the resource.
pattern: ^[0-9]+$
- type: string
description: The external string ID, which must start with 'badgeNumber:'.
example: badgeNumber:1234
pattern: ^badgeNumber:[a-zA-Z0-9._-]{1,64}$
examples:
internal-id:
summary: Internal ID
description: The internal ID of the resource
value: '12345'
badge-number:
summary: Badge number
description: Badge number prefixed with 'badgeNumber:', 1-64 characters long, consisting of alphanumerics and . _ -
value: badgeNumber:B001
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/employee_IntegrationEmployeePatchRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/employee_IntegrationEmployeeResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
oneOf:
- $ref: '#/components/schemas/employee_ProblemDetail'
- $ref: '#/components/schemas/employee_ValidationError'
examples:
badRequestProblemDetail:
summary: Bad request
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/bad-request
title: Bad Request
status: 400
detail: The request is invalid or malformed
instance: /hr/v3/employees/{id}
badRequestValidationError:
summary: Bad request
description: Example ValidationError response
value:
type: https://developer.quinyx.com/api/problems/bad-request
title: Bad Request
status: 400
errors:
- detail: name is mandatory
pointer: '#/name'
instance: /hr/v3/employees/{id}
'401':
description: Unauthorized
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
unauthorized:
summary: Unauthorized
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/unauthorized
title: Unauthorized
status: 401
detail: Access token not set or invalid, and the requested resource could not be returned
instance: /hr/v3/employees/{id}
'403':
description: Forbidden
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
forbidden:
summary: Forbidden
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/forbidden
title: Forbidden
status: 403
detail: The resource could not be returned as the requestor is not authorized
instance: /hr/v3/employees/{id}
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
notFound:
summary: Not found
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/not-found
title: Not Found
status: 404
detail: The requested resource was not found
instance: /hr/v3/employees/{id}
'500':
description: Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
serverError:
summary: Server error
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/server-error
title: Server Error
status: 500
detail: The server encountered an unexpected error
instance: /hr/v3/employees/{id}
security:
- OAuth2ClientCredentials:
- hr:employees:update
x-audience: public
x-resource-group: HR
x-resource: Employee
/hr/v3/employees:
get:
tags:
- Employee
summary: List employees
description: Returns a paginated list of employees.
operationId: getEmployees
parameters:
- name: idIn
in: query
required: false
schema:
type: array
items:
type: integer
format: int32
maxItems: 50
- name: pageToken
in: query
description: Cursor for the next page of results.
required: false
schema:
type: string
example: eyJpZCI6MTAwfQ
- name: pageSize
in: query
description: Maximum number of items to return.
required: false
schema:
type: integer
format: int32
default: 50
example: 50
maximum: 100
minimum: 1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/employee_CursorPageIntegrationEmployeeResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
oneOf:
- $ref: '#/components/schemas/employee_ProblemDetail'
- $ref: '#/components/schemas/employee_ValidationError'
examples:
badRequestProblemDetail:
summary: Bad request
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/bad-request
title: Bad Request
status: 400
detail: The request is invalid or malformed
instance: /hr/v3/employees
badRequestValidationError:
summary: Bad request
description: Example ValidationError response
value:
type: https://developer.quinyx.com/api/problems/bad-request
title: Bad Request
status: 400
errors:
- detail: name is mandatory
pointer: '#/name'
instance: /hr/v3/employees
'401':
description: Unauthorized
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
unauthorized:
summary: Unauthorized
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/unauthorized
title: Unauthorized
status: 401
detail: Access token not set or invalid, and the requested resource could not be returned
instance: /hr/v3/employees
'403':
description: Forbidden
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
forbidden:
summary: Forbidden
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/forbidden
title: Forbidden
status: 403
detail: The resource could not be returned as the requestor is not authorized
instance: /hr/v3/employees
'500':
description: Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
serverError:
summary: Server error
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/server-error
title: Server Error
status: 500
detail: The server encountered an unexpected error
instance: /hr/v3/employees
security:
- OAuth2ClientCredentials:
- hr:employees:read
x-audience: public
x-resource-group: HR
x-resource: Employee
post:
tags:
- Employee
summary: Create an employee
description: Creates and returns the created employee.
operationId: createEmployee
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/employee_IntegrationEmployeeCreateRequest'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/employee_IntegrationEmployeeResponse'
'400':
description: Bad Request
content:
application/problem+json:
schema:
oneOf:
- $ref: '#/components/schemas/employee_ProblemDetail'
- $ref: '#/components/schemas/employee_ValidationError'
examples:
badRequestProblemDetail:
summary: Bad request
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/bad-request
title: Bad Request
status: 400
detail: The request is invalid or malformed
instance: /hr/v3/employees
badRequestValidationError:
summary: Bad request
description: Example ValidationError response
value:
type: https://developer.quinyx.com/api/problems/bad-request
title: Bad Request
status: 400
errors:
- detail: name is mandatory
pointer: '#/name'
instance: /hr/v3/employees
'401':
description: Unauthorized
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
unauthorized:
summary: Unauthorized
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/unauthorized
title: Unauthorized
status: 401
detail: Access token not set or invalid, and the requested resource could not be returned
instance: /hr/v3/employees
'403':
description: Forbidden
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
forbidden:
summary: Forbidden
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/forbidden
title: Forbidden
status: 403
detail: The resource could not be returned as the requestor is not authorized
instance: /hr/v3/employees
'500':
description: Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/employee_ProblemDetail'
examples:
serverError:
summary: Server error
description: Example ProblemDetail response
value:
type: https://developer.quinyx.com/api/problems/server-error
title: Server Error
status: 500
detail: The server encountered an unexpected error
instance: /hr/v3/employees
security:
- OAuth2ClientCredentials:
- hr:employees:create
x-audience: public
x-resource-group: HR
x-resource: Employee
components:
schemas:
employee_UpdateEmergencyContact:
type: object
properties:
nextOfKinName:
type: string
description: Name of the employee's next of kin
example: John Doe
maxLength: 50
minLength: 0
nextOfKinPhone:
type: string
description: Phone number of the employee's next of kin
example: '+46700000000'
maxLength: 20
minLength: 0
legalGuardianName:
type: string
description: Name of the employee's legal guardian
example: Jane Doe
maxLength: 50
minLength: 0
legalGuardianEmail:
type: string
description: Email address of the employee's legal guardian
example: guardian@example.com
maxLength: 50
minLength: 0
required:
- legalGuardianEmail
- legalGuardianName
- nextOfKinName
- nextOfKinPhone
employee_CursorPaginationInfo:
type: object
description: Pagination information for cursor-based pagination.
properties:
nextPageToken:
type: string
description: The token for the next page
example: eyJpZCI6MTIwfQ
previousPageToken:
type: string
description: The token for the previous page
example: eyJpZCI6ODB9
employee_IntegrationEmployeeCreateRequest:
type: object
properties:
badgeNumber:
type: string
description: Unique badge number identifying the employee
example: '001'
maxLength: 20
minLength: 0
email:
type: string
format: email
description: Employee email address
example: employee@example.com
maxLength: 255
minLength: 0
personalInformation:
$ref: '#/components/schemas/employee_CreatePersonalInformation'
contactInformation:
$ref: '#/components/schemas/employee_ContactInformation'
address:
$ref: '#/components/schemas/employee_Address'
employment:
$ref: '#/components/schemas/employee_CreateEmployment'
emergencyContact:
$ref: '#/components/schemas/employee_EmergencyContact'
punchSettings:
$ref: '#/components/schemas/employee_PunchSettings'
required:
- badgeNumber
- email
- employment
- personalInformation
employee_Address:
type: object
properties:
address1:
type: string
description: Primary address line
example: 123 Example Street
maxLength: 50
minLength: 0
address2:
type: string
description: Secondary address line
example: Apt 1
maxLength: 50
minLength: 0
zip:
type: string
description: Postal or ZIP code
example: SE-10000
maxLength: 20
minLength: 0
city:
type: string
description: City of residence
example: Stockholm
maxLength: 50
minLength: 0
country:
type: string
description: Country of residence
example: Sweden
maxLength: 50
minLength: 0
employee_Employment:
type: object
properties:
homeGroupId:
type: string
description:
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/quinyx/refs/heads/main/openapi/quinyx-employee-api-openapi.yml