---
openapi: 3.0.3
info:
description: |-
JISR use two type of server hosting one is on AWS and another hosted on local server.
**How to check hostname:**
Open jisr site on the webpage and check does the url has domain name .jisr.net.sa meaning your site hosted on local server other wise hosted on Aws.
AWS endpoint URL ==> [https://api.jisr.net](https://api.jisr.net)
local endpoint URL ==> [https://api.jisr.net.sa/api/](https://api.jisr.net.sa/api/)
title: JisrOpenApi
version: 1.0.0
servers:
- url: https://apis.jisr.net/api
components:
parameters:
AccessTokenHeader:
name: Access-Token
in: header
required: true
description: JWT access token generated from the Open API Session endpoint.
schema:
type: string
ApiVersionHeader:
name: api-version
in: header
required: true
description: Supported Open API version. Only `1` is currently supported.
schema:
type: string
example: '1'
SlugHeader:
name: slug
in: header
required: true
description: Organization slug (subdomain) used to resolve the tenant.
schema:
type: string
example: abcd
responses:
BadRequest:
description: Invalid or missing request parameters.
content:
application/json:
schema:
"$ref": "#/components/schemas/OpenApiErrorResponse"
examples:
missingParameter:
summary: Missing required parameter
value:
success: false
error: Parameter status is required
status_code: 400
invalidType:
summary: Invalid parameter type
value:
success: false
error: '"value" is not a valid String'
status_code: 400
Unauthorized:
description: Authentication or organization resolution failed.
content:
application/json:
schema:
"$ref": "#/components/schemas/OpenApiErrorResponse"
examples:
invalidSlug:
summary: Unknown organization slug
value:
success: false
error: Organization not found with given subdomain
schemas:
AttendanceLogsCreateRequest:
type: object
required:
- data
properties:
data:
type: array
description: Batch of punches to process asynchronously. Maximum 100 items
per request.
maxItems: 100
items:
"$ref": "#/components/schemas/AttendancePunchCreateItem"
AttendanceLogsCreateResponse:
allOf:
- "$ref": "#/components/schemas/OpenApiSuccessEnvelope"
- type: object
properties:
message:
type: string
nullable: true
description: Processing confirmation message. The create endpoint returns
a non-null message on success.
example: Creating punches on processing
data:
type: object
nullable: true
example:
AttendanceLogsListResponse:
allOf:
- "$ref": "#/components/schemas/OpenApiSuccessEnvelope"
- type: object
properties:
data:
type: object
properties:
punches:
type: array
items:
"$ref": "#/components/schemas/AttendancePunchItem"
pagination:
"$ref": "#/components/schemas/OpenApiPagination"
required:
- punches
- pagination
AttendancePunchCreateItem:
type: object
description: Payload for a single punch submitted to the create endpoint.
required:
- punch_time
- terminal_sn
- id
- emp_code
properties:
punch_time:
type: string
format: date-time
description: Timestamp when the punch occurred.
example: '2023-01-01T11:30:00'
terminal_sn:
type: string
description: Unique identifier of the punch device.
example: ZKT-001
id:
type: integer
description: Unique punch identifier generated by the device.
example: 5467897
emp_code:
type: string
description: Employee code. Must be sent as a string, including numeric
codes.
example: '199'
AttendancePunchItem:
type: object
description: A single attendance punch returned by the list endpoint.
properties:
id:
type: integer
description: Internal punch record identifier.
example: 360257
punch_time:
type: string
format: date-time
example: '2023-11-01T00:00:00.000Z'
employee_code:
type: string
description: Employee code associated with the punch.
example: '199'
terminal_sn:
type: string
nullable: true
description: Device serial number when available.
example: ZKT-001
clocking_id:
type: integer
description: Punch identifier generated by the source device.
example: 5467897
error:
type: string
description: Localized error message. Present only when `status=failed`.
example: Employee not found
AttendanceSummaryRecord:
type: object
description: Attendance summary metrics for a single employee within the requested
period.
properties:
id:
type: string
description: Employee public identifier (UUID).
example: 38a001d2-402b-41cb-884f-8040cf9365f8
code:
type: string
description: Employee code.
example: '100'
name:
type: string
description: Employee full name in English.
example: Waleed Abdullah
total_working_hours:
type: string
description: Total working hours (HH:MM).
example: '18:57'
total_working_hours_inside_the_shifts:
type: string
example: '15:03'
late_arrival:
type: string
example: '1:30'
excuse_late_arrival:
type: string
example: '0:30'
early_departure:
type: string
example: '0:27'
excuse_early_departure:
type: string
example: '0:30'
extra_working_time:
type: string
example: '1:57'
approved_overtime:
type: string
example: '0:06'
absence:
type: number
example: 22
no_records:
type: number
example: 44
leave_days:
type: number
example: 3
off_days:
type: number
example: 4
full_day_excuses:
type: number
example: 0
businiess_trip_days:
type: number
description: Number of business trip days. Note the response key uses the
legacy spelling `businiess_trip_days` (not `business_trip_days`).
example: 0
late_arrival_days:
type: number
example: 1
early_departure_days:
type: number
example: 1
AttendanceSummaryResponse:
allOf:
- "$ref": "#/components/schemas/OpenApiSuccessEnvelope"
- type: object
properties:
data:
type: object
properties:
records:
type: array
items:
"$ref": "#/components/schemas/AttendanceSummaryRecord"
pagination:
"$ref": "#/components/schemas/OpenApiPagination"
required:
- records
- pagination
EmployeeLeaveSummaryItem:
type: object
description: Annual leave balance summary for a single employee.
properties:
id:
type: string
description: Leave summary record identifier (UUID).
example: 0b7c8400-5039-4ab4-8662-541826055c25
leave_days:
type: number
description: Annual leave entitlement for the year.
example: 30
previous_year_balance:
type: number
description: Carried-forward balance from the previous leave year.
example: 10
opening_balance:
type: number
description: Opening balance for the current leave cycle.
example: 0
manual_balance_adjustment:
type: number
description: Manual adjustments applied to the leave balance.
example: 0
used:
type: number
description: Leave days already taken.
example: 0
year_end_balance:
type: number
description: Projected balance at year end after reservations.
example: 40
pending:
type: number
description: Leave days pending approval.
example: 15.5
total_reserved_balances:
type: number
description: Total leave days reserved by pending or approved requests.
example: 0
unpaid_leave_deduction:
type: number
description: Leave days deducted as unpaid leave.
example: 0
employee_code:
type: string
description: Employee code.
example: '9'
leave_type:
type: string
description: Leave type name.
example: Annual
from:
type: string
format: date
description: Leave cycle start date.
effective_starting_balance:
type: number
description: Effective starting balance used for leave calculations.
year_starting_balance:
type: number
description: Balance at the start of the leave year.
EmployeeLeavesSummaryResponse:
allOf:
- "$ref": "#/components/schemas/OpenApiSuccessEnvelope"
- type: object
properties:
data:
type: object
properties:
leaves_summary:
type: array
items:
"$ref": "#/components/schemas/EmployeeLeaveSummaryItem"
pagination:
"$ref": "#/components/schemas/OpenApiPagination"
required:
- leaves_summary
- pagination
JournalEntryItem:
type: object
properties:
id:
type: string
format: uuid
description: May appear in examples; not always returned by the API.
journal_type:
type: string
description: |
Human-readable journal label in the export (locale-specific).
Not the same as the create-request `journal_type` enum.
In Swagger UI, example **GET#show** is the full response; examples **GET#response_label_*** are
minimal and only list possible label strings for this field.
example: Monthly Payroll
pay_period_start:
type: string
pay_period_end:
type: string
subsidiary:
type: string
nullable: true
separation_value:
type: string
nullable: true
cost_center:
type: string
nullable: true
cost_center_code:
type: string
nullable: true
employee_name:
type: string
nullable: true
total_credit:
type: number
format: double
total_debit:
type: number
format: double
journal_lines:
type: array
items:
"$ref": "#/components/schemas/JournalLineItem"
pagination:
"$ref": "#/components/schemas/JournalLinesPagination"
JournalExportCreateRequest:
type: object
description: |
**POST request body** (`multipart/form-data`) for `POST /openapi/v1/accounting/journals`.
In Swagger UI this appears under **Request body**, not under Parameters.
Prefer example **request_full_reference_regular** (or **request_full_reference_out_of_payroll**).
Organization `slug` is usually sent as a **query** or **header** parameter instead of a form field.
required:
- journal_type
- paygroup_id
- pay_period_from
properties:
journal_type:
type: string
description: |
Journal export type (request parameter). Allowed values match `JournalExportRequest::JOURNAL_TYPES`.
Open API **rejects** `vacation_settlement` and `end_of_service` (HTTP 400).
Response `journals[].journal_type` is a separate display label (see GET response examples).
enum:
- regular
- ajeer
- gosi
- accrual
- vacation_accrual
- eos_accrual
- ticket
- vacation_settlement
- end_of_service
- out_of_payroll
- expense
example: regular
paygroup_id:
type: string
format: uuid
description: Pay group GUID (not numeric id).
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from:
type: string
description: Start of pay period (`YYYY/MM/DD` or ISO date string accepted
by the API).
example: 2025/01/01
pay_period_to:
type: string
description: Required when `journal_type` is `out_of_payroll`; must be on
or after `pay_period_from`.
example: 2025/01/31
transaction_ids:
type: array
description: Optional for `out_of_payroll` — payroll transaction GUIDs to
include.
items:
type: string
format: uuid
slug:
type: string
description: Organization slug (optional in body if sent via header/query).
example: global_testing_organization
JournalExportOpenApiErrorEnvelope:
description: |
Error envelope for journal export Open API responses when `data` may include
`journal_export_request` (e.g. GET failed export). POST validation errors use
`OpenApiErrorResponse` only.
allOf:
- "$ref": "#/components/schemas/OpenApiErrorResponse"
- type: object
properties:
data:
nullable: true
type: object
JournalExportOpenApiSuccessEnvelope:
description: |
Success envelope for journal export Open API responses (`POST` / `GET` journals).
Extends the shared success envelope with a required `data` object.
allOf:
- "$ref": "#/components/schemas/OpenApiSuccessEnvelope"
- type: object
required:
- data
properties:
data:
type: object
JournalExportRequest:
type: object
properties:
source:
type: string
enum:
- open_api
example: open_api
status:
type: string
description: Export job lifecycle. Poll `GET /openapi/v1/accounting/journals/{id}`
until `completed` or `failed`.
enum:
- pending
- processing
- completed
- completed_with_errors
- failed
- archived
created_at:
type: string
updated_at:
type: string
id:
type: string
format: uuid
journal_preparation_errors:
nullable: true
description: Error detail when preparation or export failed; null when not
applicable.
oneOf:
- type: string
- type: object
total_journals:
type: integer
journals:
type: array
nullable: true
items:
"$ref": "#/components/schemas/JournalEntryItem"
JournalExportRequestFailedResponse:
allOf:
- "$ref": "#/components/schemas/JournalExportOpenApiErrorEnvelope"
- type: object
properties:
data:
type: object
properties:
journal_export_request:
"$ref": "#/components/schemas/JournalExportRequest"
required:
- journal_export_request
required:
- data
JournalExportRequestResponse:
allOf:
- "$ref": "#/components/schemas/JournalExportOpenApiSuccessEnvelope"
- type: object
properties:
data:
type: object
properties:
journal_export_request:
"$ref": "#/components/schemas/JournalExportRequest"
required:
- journal_export_request
JournalLineItem:
type: object
properties:
account_id:
type: string
nullable: true
account_name:
type: string
nullable: true
transaction_name:
type: string
nullable: true
cost_center_items:
type: array
description: |
Tracking dimension values for the line. Responses may use either shape:
- an array of **name strings**, or
- an array of **objects** with `name` and `code`.
items:
oneOf:
- type: string
- type: object
properties:
name:
type: string
nullable: true
code:
type: string
nullable: true
employee_name:
type: string
nullable: true
employee_id:
type: string
nullable: true
credit_amount:
type: number
format: double
debit_amount:
type: number
format: double
narrative:
type: string
nullable: true
JournalLinesPagination:
type: object
properties:
page:
type: integer
rpp:
type: integer
total_pages:
type: integer
total_records:
type: integer
next_page:
type: integer
nullable: true
previous_page:
type: integer
nullable: true
OpenApiErrorResponse:
type: object
description: Standard error envelope for Open API requests.
properties:
success:
type: boolean
example: false
error:
type: string
description: Human-readable validation or business error message.
example: Parameter status is required
status_code:
type: integer
example: 400
required:
- success
- error
OpenApiPagination:
type: object
description: Standard pagination metadata returned by list endpoints.
properties:
current_page:
type: integer
example: 1
next_page:
type: integer
nullable: true
description: Next page number, or null when on the last page.
example:
previous_page:
type: integer
nullable: true
description: Previous page number, or null when on the first page.
example:
total_pages:
type: integer
example: 1
per_page:
type: integer
example: 100
total_entries:
type: integer
example: 25
required:
- current_page
- next_page
- previous_page
- total_pages
- per_page
- total_entries
OpenApiSuccessEnvelope:
type: object
description: Standard success envelope for Open API requests.
properties:
success:
type: boolean
example: true
message:
type: string
nullable: true
example:
required:
- success
paths:
"/openapi/v1/accrual_transactions":
get:
tags:
- Accruals
summary: List Accrual Transactions
description: |-
# **Request** ### GET /openapi/v1/accrual_transactions
This endpoint retrieves accrual transactions based on the provided parameters.
The request includes the following:
### HEADERS
| name | **Required** | description | **Type** | **Example** | **default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| api-version | Yes | Supported API version s | Integer | 1 | | currently supported is 1 only |
| Slug | Yes | Organization slug name | String | abcd | | |
| Access-Token | Yes | Used to allow an application to access an API it generated from Session API | String | eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRp
ZmllciI6OTAwMDAxNCwiYXBpX2tleV9pZCI6MSwic291cm
NlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhd
CI6MTY5OTYwMjF4NiwiZXhwIjoxNzAyMTk0Njg2fQ.upSy
VVcRrBe2SNUvjnAlDq7NO-N_tenPnGF6zNs1KZU | | |
| source | No | the source type of Open Api | String | open_api | open_api | Supported values:
\- open_api
\- external_aggregator |
| username | Conditional:
if the source type: external_aggregator | the name of the external service | String | workable | | |
---
#### Query Parameters
| **name** | **Required** | **Description** | **Type** | **Example** | **Default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| rpp | No | control the limit of the shown result per page | Integer | 50 | 100 | Minimum: 1
Maximum: 100 |
| page | No | choose the required page | Integer | 5 | 1 | |
| accrual_type | Yes | Types of transactions, must be within these types: \[vacations, end_of_service, tickets_provision\] | String | | |
| paygroup_id | Yes | | string | 56f6e9cc-0d45-4133-b23b-aeaf2b8e6992 | | |
| pay_period | Yes | 1st day of a confirmed month | Date | 2022-03-01 | | |
| employee_ids | No | filter by employee ids | Array | \[dfa893d5-284a-4be8-800c-e2287852177a\] | | If this param not found it'll fetch all transactions within that settlement |
---
#### Request Body
- `accrual_type` (string, optional): Type of accrual.
- `paygroup_id` (string, required): Paygroup Id.
- `pay_period` (string, required): Pay period filter.
- `page` (number, optional): Page number for paginated results.
- `rpp` (number, optional): Records per page for pagination.
- `employee_ids` (array, optional): Array of employee IDs.
#### Examples of Response
1. If successful:
``` json
{
"success": true,
"message": null,
"data": {
"pay_period": "",
"employees": [
{
"id": "",
"code": "",
"full_name_en": "",
"full_name_ar": "",
"is_active": true,
"status": "",
"payment_type": "",
"payment_type_i18n": "",
"business_unit": null,
"grade": null,
"country": null,
"gosi_info": {
"name_i18n": "",
"gosi_number": ""
},
"accrual": {
"amount": 0,
"downgrade_amount": 0,
"vacation_days": 0,
"has_vacation_days": true
}
}
],
"pagination": {
"total_pages": 0,
"per_page": 0,
"total_entries": 0
}
}
}
```
1. If failed:
``` json
{
"success": false,
"error": "Couldn't find data with the provided period. Please make sure the provided date is the 1st day of a confirmed month",
"status_code": 400
}
```
operationId: listAccrualTransactions
parameters:
- name: accrual_type
in: query
description: 'Required. Valid types are: [vacations, end_of_service, tickets_provision]'
schema:
type: string
- name: paygroup_id
in: query
description: Required. Paygroup identifier.
schema:
type: string
- name: pay_period
in: query
description: Required, 1st day of a confirmed month.
schema:
type: string
- name: page
in: query
description: Pagination
schema:
type: string
- name: rpp
in: query
description: Pagination (no. of records per page. Default is 100)
schema:
type: string
- name: employee_ids[]
in: query
description: Filter by an array of employee_ids
schema:
type: string
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
data:
type: object
properties:
pay_period:
type: string
example: 2023-01-01 - 2023-01-31
employees:
type: array
example:
- accrual:
amount: 27123.29
downgrade_amount: 0
has_vacation_days: false
vacation_days: 0
business_unit:
code: '895478215882'
country:
full_name_ar: مراد
full_name_en: Morad Aljibly
gosi_info:
gosi_number: '60001234'
name_i18n: " 1 Al-salem"
grade:
id: b07874d9-6026-4e87-a78d-db5ad71ef198
is_active: true
payment_type: Cash
payment_type_i18n: Cash
status: active
items:
type: object
properties:
accrual:
type: object
properties:
amount:
type: number
example: 27123.29
downgrade_amount:
type: number
example: 0.0
has_vacation_days:
type: boolean
example: false
vacation_days:
type: number
example: 0.0
business_unit:
type: object
nullable: true
example: 'null'
code:
type: string
example: '895478215882'
country:
type: object
nullable: true
example: 'null'
full_name_ar:
type: string
example: مراد
full_name_en:
type: string
example: Morad Aljibly
gosi_info:
type: object
properties:
gosi_number:
type: string
example: '60001234'
name_i18n:
type: string
example: " 1 Al-salem"
grade:
type: object
nullable: true
example: 'null'
id:
type: string
example: b07874d9-6026-4e87-a78d-db5ad71ef198
is_active:
type: boolean
example: true
payment_type:
type: string
example: Cash
payment_type_i18n:
type: string
example: Cash
status:
type: string
example: active
pagination:
type: object
properties:
per_page:
type: number
example: 10.0
total_entries:
type: number
example: 1.0
total_pages:
type: number
example: 1.0
'400':
description: Failed Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Couldn't find data with the provided period. Please make
sure the provided date is the 1st day of a confirmed month
data:
type: object
nullable: true
example: 'null'
"/openapi/v1/attendance_logs":
get:
tags:
- Attendance Log
summary: List
description: |-
# **Request**
`GET /openapi/v1/attendance_logs`
This API endpoint retrieves the status of punches whether it's failed or success .
The request includes the following:
### HEADERS
| name | **Required** | description | **Type** | **Example** | **default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| api-version | Yes | Supported API version s | Integer | 1 | | currently supported is 1 only |
| Slug | Yes | Organization slug name | String | abcd | | |
| Access-Token | Yes | Used to allow an application to access an API it generated from Session API | String | eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRp
ZmllciI6OTAwMDAxNCwiYXBpX2tleV9pZCI6MSwic291cm
NlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhd
CI6MTY5OTYwMjF4NiwiZXhwIjoxNzAyMTk0Njg2fQ.upSy
VVcRrBe2SNUvjnAlDq7NO-N_tenPnGF6zNs1KZU | | |
| source | No | the source type of Open Api | String | open_api | open_api | Supported values:
\- open_api
\- external_aggregator |
| username | Conditional:
if the source type: external_aggregator | the name of the external service | String | workable | | |
#### Query Parameters
| **name** | **Required** | **Description** | **Type** | **Example** | **Default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| status | Yes | Specifies the type of punches to be retrieved | String | success | | Currently support only success or failed |
| limit | No | controll the limit of the shown result per page | Integer | 50 | 100 | Minimum: 1
Maximum: 100 |
| page | No | choose the required page | Integer | 5 | 1 | |
| from | No | choose the start date time | DateTime | 2023-1-1 11:30:00 | 1 hour ago | |
| to | No | choose the end date time | DateTime | 2023-10-1 12:30:00 | Current time | |
---
# Response
- Success Response
The success response of the API represented as the following:
```
{
"success": true,
"message": null,
"data": {
"punches": [
{
"id": 360257,
"punch_time": "2023-11-01T00:00:00.000Z",
"employee_code": 199,
"terminal_sn": null,
"clocking_id": 5467897
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"previous_page": null,
"total_pages": 1,
"per_page": 50,
"total_entries": 1
}
}
}
```
This contain the following:
| **key** | **Description** | **value** |
| --- | --- | --- |
| success | represent the status of the API response | true |
| message | show additional message | null |
| data | show the required data to fetch, and contain two values type:
\+ punches: contain array of all punches details
pagination: contain additional field to navigate data through the api | hash of data |
| Status_code | the status code of the api request | 200 |
Leave summary description:
- `id`: The unique identifier of a punch.
- `punch_time`: the time when the punch created
- `terminal_sn`: Unique identifier for punch device.
- `clocking_id`: Unique The unique identifier of a punch generated by punch mdevice.
- `manual_balance_adjustment`: The manual adjustment made to the leave balance.
---
Pagination:
- `current_page`: The current page of the results.
- `next_page`: The URL of the next page of results, if available.
- `previous_page`: The URL of the previous page of results, if available.
- `total_pages`: The total number of pages.
- `per_page`: The number of results per page.
- `total_entries`: The total number of entries across all pages.
---
### Error Response
The success response of the API represented as the following:
```
{
"success": false,
"error": "error message",
"status_code": 400
}
```
This response contain the following:
| **name** | **Description** | **Value** |
| --- | --- | --- |
| success | represent the status of the API response | false |
| error | represent the error reason acquired during the request | error_messages |
| status_code | the status code of the api requests | error_status_code |
error_messages
| **message** | **Reason** |
| --- | --- |
| Parameter {field_name} is required | The field name is required |
| "value" is not a valid {type} | the value passed is not in valid type |
| invalid api version | invalid `api-version` header passed or api-version header was not passed at all |
| Organization not found with given subdomain | invalid `Slug` header value |
| Permission denied. Please contact your Administrator | `Slug` Header is missing or your organization doesn't support open api feature |
| This call requires login | `Access-Token` is missing or invalid |
| Your account has been logged out. Please, log in again | previously logged out or expired token |
| Your account temporary suspended, please contact account manager | The organization account is suspended |
| Bad credentials | the credentials is not suited on that organization |
| invalid external aggregator | the aggregator name is not valid within that organization |
| Unable to authenticate employee | api-key is not active or valid |
Please note that the values for properties like `id`, `punch_time`, `employee_code`, `terminal_sn`, and `clocking_id` may vary in the actual response and should not be considered as fixed values.
operationId: list1
parameters:
- name: from
in: query
schema:
type: string
- name: to
in: query
schema:
type: string
- name: status
in: query
schema:
type: string
- name: page
in: query
schema:
type: string
- name: limit
in: query
schema:
type: string
- name: Slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: 'Success Punches: Failed Punches'
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
pagination:
type: object
properties:
current_page:
type: number
example: 1
next_page:
type: object
nullable: true
example: 'null'
per_page:
type: number
example: 50
previous_page:
type: object
nullable: true
example: 'null'
total_entries:
type: number
example: 4
total_pages:
type: number
example: 1
punches:
type: array
example:
- clocking_id: 5467897
employee_code: 199
id: 360257
punch_time: '2023-11-01T00:00:00.000Z'
terminal_sn:
- clocking_id: 5467897
employee_code: 199
id: 360258
punch_time: '2023-01-01T11:30:00.000Z'
terminal_sn:
- clocking_id: 5467897
employee_code: 199
id: 360259
punch_time: '2023-01-01T00:00:00.000Z'
terminal_sn:
- clocking_id: 5467897
employee_code: 199
id: 360260
punch_time: '2023-01-01T11:30:00.000Z'
terminal_sn:
items:
type: object
properties:
clocking_id:
type: number
example: 5467897
employee_code:
type: number
example: 199
id:
type: number
example: 360257
punch_time:
type: string
example: '2023-11-01T00:00:00.000Z'
terminal_sn:
type: object
nullable: true
example: 'null'
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
'400':
description: Invalid Token
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Parameter limit cannot be greater than 100
status_code:
type: number
example: 400
success:
type: boolean
example: false
'401':
description: Invalid Slug
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Organization not found with given subdomain
success:
type: boolean
example: false
post:
tags:
- Attendance Log
summary: Create
description: |-
# **Request**
`POST /openapi/v1/attendance_logs`
This API endpoint create group of punches
The request includes the following:
### HEADERS
| name | **Required** | description | **Type** | **Example** | **default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| api-version | Yes | Supported API version s | Integer | 1 | | currently supported is 1 only |
| Slug | Yes | Organization slug name | String | abcd | | |
| Access-Token | Yes | Used to allow an application to access an API it generated from Session API | String | eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRp
ZmllciI6OTAwMDAxNCwiYXBpX2tleV9pZCI6MSwic291cm
NlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhd
CI6MTY5OTYwMjF4NiwiZXhwIjoxNzAyMTk0Njg2fQ.upSy
VVcRrBe2SNUvjnAlDq7NO-N_tenPnGF6zNs1KZU | | |
| source | No | the source type of Open Api | String | open_api | open_api | Supported values:
\- open_api
\- external_aggregator |
| username | Conditional:
if the source type: external_aggregator | the name of the external service | String | workable | | |
#### Query Parameters
| **name** | **Required** | **Description** | **Type** | **Additional Notes** |
| --- | --- | --- | --- | --- |
| data | Yes | contain array of punches params | Array | \+ Currently support only success |
Punch Params:
| Name | **Required** | Description | **Type** | **Additional Notes** |
| --- | --- | --- | --- | --- |
| terminal_sn | Yes | Unique identifier for punch device | String | \+ organization may have multiple punch devices |
| punch_time | Yes | The time were punch created | DateTime | |
| id | Yes | Unique identifier for each punch generated by punch device | Integer | |
| emp_code | Yes | code number for the employee who whom the punch come from | Integer | |
# Response
- Success Response
The success response of the API represented as the following:
```
{
"success": true,
"message": "Creating punches on processing",
"data": null
}
```
This contain the following:
| **key** | **Description** | **value** |
| --- | --- | --- |
| success | represent the status of the API response | true |
| message | show additional message | null |
| data | null | |
---
### Error Response
The success response of the API represented as the following:
```
{
"success": false,
"error": "Number of punches exceeds allowed limit: 100",
"data": null
}
```
This response contain the following:
| **name** | **Description** | **Value** |
| --- | --- | --- |
| success | represent the status of the API response | false |
| error | represent the error reason acquired during the request | error_messages |
| status_code | the status code of the api requests | error_status_code |
error_messages
| **message** | **Reason** |
| --- | --- |
| Number of punches exceeds allowed limit: 100 | Number of punches sent with the request has exceeded the maximum |
| | The field name is required |
| "value" is not a valid {type} | the value passed is not in valid type |
| invalid api version | invalid `api-version` header passed or api-version header was not passed at all |
| Organization not found with given subdomain | invalid `Slug` header value |
| Permission denied. Please contact your Administrator | `Slug` Header is missing or your organization doesn't support open api feature |
| This call requires login | `Access-Token` is missing or invalid |
| Your account has been logged out. Please, log in again | previously logged out or expired token |
| Your account temporary suspended, please contact account manager | The organization account is suspended |
| Bad credentials | the credentials is not suited on that organization |
| invalid external aggregator | the aggregator name is not valid within that organization |
| Unable to authenticate employee | api-key is not active or valid |
operationId: create1
parameters:
- name: Slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
data:
type: array
example:
- emp_code: 199
id: 5467897
punch_time: '2023-1-1 11:30:00'
terminal_sn: '1'
items:
type: object
properties:
emp_code:
type: number
example: 199
id:
type: number
example: 5467897
punch_time:
type: string
example: '2023-1-1 11:30:00'
terminal_sn:
type: string
example: '1'
required: false
responses:
'201':
description: Create Punches
content:
application/json:
schema:
type: object
properties:
data:
type: object
nullable: true
example: 'null'
message:
type: string
example: Creating punches on processing
success:
type: boolean
example: true
'400':
description: Exceed Limit
content:
application/json:
schema:
type: object
properties:
data:
type: object
nullable: true
example: 'null'
error:
type: string
example: 'Number of punches exceeds allowed limit: 100'
success:
type: boolean
example: false
'401':
description: Invalid Slug
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Organization not found with given subdomain
success:
type: boolean
example: false
"/openapi/v1/attendance/summary":
get:
tags:
- Attendance
summary: Summary
description: |-
# **Request**
`GET /openapi/v1/attendance/summary`
This endpoint retrieves the attendance summary for employees within a specified date range default is current month. The request have ability to filter by employee ID, status, from date, to date, page, and (rpp) results per page
The request includes the following:
### HEADERS
| name | **Required** | description | **Type** | **Example** | **default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| api-version | Yes | Supported API version s | Integer | 1 | | currently supported is 1 only |
| Slug | Yes | Organization slug name | String | abcd | | |
| Access-Token | Yes | Used to allow an application to access an API it generated from Session API | String | eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRp
ZmllciI6OTAwMDAxNCwiYXBpX2tleV9pZCI6MSwic291cm
NlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhd
CI6MTY5OTYwMjF4NiwiZXhwIjoxNzAyMTk0Njg2fQ.upSy
VVcRrBe2SNUvjnAlDq7NO-N_tenPnGF6zNs1KZU | | |
| source | No | the source type of Open Api | String | open_api | open_api | Supported values:
\- open_api
\- external_aggregator |
| username | Conditional:
if the source type: external_aggregator | the name of the external service | String | workable | | |
#### Query Parameters
| **name** | **Required** | **Description** | **Type** | **Example** | **Default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| rpp | No | control the limit of the shown result per page | Integer | 50 | 100 | Minimum: 1
Maximum: 100 |
| page | No | choose the required page | Integer | 5 | 1 | |
| employee_id | no | Unique id of the employee | String | bab6cd98-7246-4cfc-a576-19bc00391792 | | UUID type |
| from | No | This filter use to get period from specific date | Date | 2023/01/01 | | |
| to | No | This filter use to get period to specific date | Date | | | |
| status | No | This filter use to filter employees by there status and support two values (active - inactive) | string | active | | must be within \[active, inactive\] |
---
# Response
- Success Response
The success response of the API represented as the following:
Plain Text
```
{
"success": true,
"message": null,
"data": {
"records": [
{
"id": "38a001d2-402b-41cb-884f-8040cf9365f8",
"code": "100",
"name": "Waleed Abdullah",
"total_working_hours": "18:57",
"total_working_hours_inside_the_shifts": "15:03",
"late_arrival": "1:30",
"excuse_late_arrival": "0:30",
"early_departure": "0:27",
"excuse_early_departure": "0:30",
"extra_working_time": "1:57",
"approved_overtime": "0:06",
"absence": 22,
"no_records": 44,
"leave_days": 3,
"off_days": 4,
"full_day_excuses": 0,
"businiess_trip_days": 0,
"late_arrival_days": 1,
"early_departure_days": 1
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"previous_page": null,
"total_pages": 1,
"per_page": 100,
"total_entries": 1
}
}
}
```
This contain the following:
| **key** | **Description** | **value** |
| --- | --- | --- |
| success | represent the status of the API response | true |
| message | show additional message | null |
| data | show the required data to fetch, and contain basic info all of the employees | hash of data |
| Status_code | the status code of the api request | 200 |
---
Pagination:
- `current_page`: The current page of the results.
- `next_page`: The URL of the next page of results, if available.
- `previous_page`: The URL of the previous page of results, if available.
- `total_pages`: The total number of pages.
- `per_page`: The number of results per page.
- `total_entries`: The total number of entries across all pages.
---
### Error Response
The success response of the API represented as the following:
Plain Text
```
{
"success": false,
"error": "error message",
"status_code": 400
}
```
This response contain the following:
| **name** | **Description** | **Value** |
| --- | --- | --- |
| success | represent the status of the API response | false |
| error | represent the error reason acquired during the request | error_messages |
| status_code | the status code of the api requests | error_status_code |
error_messages
| **message** | **Reason** |
| --- | --- |
| Parameter {field_name} is required | The field name is required |
| "value" is not a valid {type} | the value passed is not in valid type |
| invalid api version | invalid `api-version` header passed or api-version header was not passed at all |
| Organization not found with given subdomain | invalid `Slug` header value |
| Permission denied. Please contact your Administrator | `Slug` Header is missing or your organization doesn't support open api feature |
| This call requires login | `Access-Token` is missing or invalid |
| Your account has been logged out. Please, log in again | previously logged out or expired token |
| Your account temporary suspended, please contact account manager | The organization account is suspended |
| Bad credentials | the credentials is not suited on that organization |
| invalid external aggregator | the aggregator name is not valid within that organization |
| Unable to authenticate employee | api-key is not active or valid |
Please note that some of the values for properties may vary in the actual response and should not be considered as fixed values.
operationId: summary1
parameters:
- name: from
in: query
schema:
type: string
- name: to
in: query
schema:
type: string
- name: employee_id
in: query
schema:
type: string
- name: status
in: query
schema:
type: string
- name: page
in: query
schema:
type: string
- name: rpp
in: query
schema:
type: string
- name: slug
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
responses:
'200':
description: Summary
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
pagination:
type: object
properties:
current_page:
type: number
example: 1
next_page:
type: object
nullable: true
example: 'null'
per_page:
type: number
example: 100
previous_page:
type: object
nullable: true
example: 'null'
total_entries:
type: number
example: 1
total_pages:
type: number
example: 1
records:
type: array
example:
- absence: 22
approved_overtime: '0:06'
businiess_trip_days: 0
code: '100'
early_departure: '0:27'
early_departure_days: 1
excuse_early_departure: '0:30'
excuse_late_arrival: '0:30'
extra_working_time: '1:57'
full_day_excuses: 0
id: 38a001d2-402b-41cb-884f-8040cf9365f8
late_arrival: '1:30'
late_arrival_days: 1
leave_days: 3
name: Waleed Abdullah
no_records: 44
off_days: 4
total_working_hours: '18:57'
total_working_hours_inside_the_shifts: '15:03'
items:
type: object
properties:
absence:
type: number
example: 22
approved_overtime:
type: string
example: '0:06'
businiess_trip_days:
type: number
example: 0
code:
type: string
example: '100'
early_departure:
type: string
example: '0:27'
early_departure_days:
type: number
example: 1
excuse_early_departure:
type: string
example: '0:30'
excuse_late_arrival:
type: string
example: '0:30'
extra_working_time:
type: string
example: '1:57'
full_day_excuses:
type: number
example: 0
id:
type: string
example: 38a001d2-402b-41cb-884f-8040cf9365f8
late_arrival:
type: string
example: '1:30'
late_arrival_days:
type: number
example: 1
leave_days:
type: number
example: 3
name:
type: string
example: Waleed Abdullah
no_records:
type: number
example: 44
off_days:
type: number
example: 4
total_working_hours:
type: string
example: '18:57'
total_working_hours_inside_the_shifts:
type: string
example: '15:03'
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
"/openapi/v1/audit_events":
get:
tags:
- Audit Event
summary: List Audit Events
description: |-
# **Request**
`GET /openapi/v1/audit_events`
This API endpoint retrieves a paginated list of audit events.
### HEADERS
| name | **Required** | description | **Type** | **Example** | **Additional Notes** |
|--------------|--------------|---------------------------------------------|-----------|-------------|---------------------|
| api-version | Yes | Supported API version | Integer | 1 | Only 1 is supported |
| Slug | Yes | Organization slug name | String | abcd | |
| Access-Token | Yes | JWT for authentication | String | ... | |
### Query Parameters
| name | **Required** | Description | **Type** | **Example** | **Notes** |
|---------------------|--------------|---------------------------------------------|--------------------|------------------------------------|------------|
| filter[module_name] | No | Filter by module name | Array | filter[module_name]['security'] | |
| filter[event_name] | No | Filter by event name | Array | filter[event_name]['login'] | |
| filter[event_type] | No | Filter by event type | Array | filter[event_type]['updated'] | |
| filter[from_date] | No | Filter by created_at >= from (ISO8601) | String (date-time) | 2025-09-01T00:00:00Z | |
| filter[to_date] | No | Filter by created_at <= to (ISO8601) | String (date-time) | 2025-09-10T23:59:59Z | |
| page | No | Page number for pagination | Integer | 1 | |
| per_page | No | Number of items per page | Integer | 20 | |
---
# Response
- Success Response Example
```json
{
"success": true,
"message": null,
"data": {
"audit_events": [
{
"id": 123,
"module_name_i18n": "Security",
"feature_name_i18n": "Role",
"action_name_i18n": "Updated",
"actor": {
"id": 456,
"full_name_i18n": "John Doe"
},
"success": true,
"created_at": "2025-09-09T12:34:56Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"previous_page": null,
"total_pages": 1,
"total_count": 1
}
}
}
```
parameters:
- in: query
name: filter[module_name]
style: deepObject
explode: true
schema:
type: array
items:
type: string
example: security
description: Filter by module name (e.g. `filter[module_name]['security']`).
- in: query
name: filter[event_name]
style: deepObject
explode: true
schema:
type: array
items:
type: string
example: login
description: Filter by event name (e.g. `filter[event_name]['login']`).
- in: query
name: filter[event_type]
style: deepObject
explode: true
schema:
type: array
items:
type: string
example: updated
description: Filter by event type (e.g. `filter[event_type]['updated']`).
- in: query
name: filter[from_date]
schema:
type: string
example: '2025-09-01T00:00:00Z'
description: Filter by created_at >= from (ISO8601).
- in: query
name: filter[to_date]
schema:
type: string
example: '2025-09-10T23:59:59Z'
description: Filter by created_at <= to (ISO8601).
- in: query
name: page
schema:
type: integer
default: 1
description: Page number for pagination.
- in: query
name: per_page
schema:
type: integer
default: 20
description: Number of items per page.
responses:
'200':
description: A list of audit events.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
nullable: true
data:
type: object
properties:
audit_events:
type: array
items:
"$ref": "#/components/schemas/AuditEvent"
pagination:
"$ref": "#/components/schemas/Pagination"
'401':
description: Unauthorized
'500':
description: Server error
"/openapi/v1/auth":
post:
tags:
- Authentication
summary: Session
description: |-
# **Request**
`POST /openapi/v1/auth`
This API used to generate **Access-Token** to access open API on system based on permissions assigned to API key
#### Headers Parameters
| **Name** | **Description** |
| --- | --- |
| slug | Organization slug |
| api-key | Used to provide project authorization |
| secret | Organization secret or External aggregator secret |
| api-version | Supported version (1) |
| source | open_api or external_aggregator |
| username | This field needed if source is external_aggregator |
# Response
- Success Response
```
{
"success": true,
"message": "Logged in successfully",
"data": "eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRpZmllciI6OTAwMDM1MSwiYXBpX2tleV9pZCI6MSwic291cmNlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhdCI6MTY4NTAxNjcxNywiZXhwIjoxNjg3NjA4NzE3fQ.azC8d26U9sF397_g5LG9cjLkX1NNj5AwnLEnVzoCOjs"
}
```
operationId: session
parameters:
- name: slug
in: header
schema:
type: string
- name: api-key
in: header
schema:
type: string
- name: secret
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
responses:
'200':
description: Session
content:
application/json:
schema:
type: object
properties:
data:
type: string
example: eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRpZmllciI6OTAwMDM1MSwiYXBpX2tleV9pZCI6MSwic291cmNlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhdCI6MTY4NTAxNjcxNywiZXhwIjoxNjg3NjA4NzE3fQ.azC8d26U9sF397_g5LG9cjLkX1NNj5AwnLEnVzoCOjs
message:
type: string
example: Logged in successfully
success:
type: boolean
example: true
'401':
description: Invalid Slug
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: اسم الشركة غير صحيح
success:
type: boolean
example: false
"/openapi/v1/employee_leaves/summary":
get:
tags:
- Employee Leave
summary: Get annual leave summary
operationId: getEmployeeLeavesSummary
description: |-
Returns paginated annual leave balance summaries for employees.
## Overview
- Only `leave_type=annual` is currently supported.
- Filter by `employee_codes` to target specific employees.
- When `employee_codes` is omitted or empty, summaries for **all** employees are returned.
- Maximum **100** employee codes per request.
- The `id` field in each summary is the leave record UUID.
## Authentication
| Header | Required | Description |
|--------|----------|-------------|
| `api-version` | Yes | API version (`1`) |
| `slug` | Yes | Organization slug |
| `Access-Token` | Yes | JWT from the Session API |
## Common errors
| Error | Cause |
|-------|-------|
| `Parameter leave_type must be within ["annual"]` | Unsupported leave type |
| `employee_codes can't be more than 100 per request` | Too many codes in one request |
parameters:
- "$ref": "#/components/parameters/ApiVersionHeader"
- "$ref": "#/components/parameters/SlugHeader"
- "$ref": "#/components/parameters/AccessTokenHeader"
- name: leave_type
in: query
required: true
description: Leave type to summarize. Only `annual` is supported.
schema:
type: string
enum:
- annual
- name: employee_codes
in: query
description: Filter by employee codes. Use repeated query parameters (e.g.
`employee_codes=1&employee_codes=2`).
style: form
explode: true
schema:
type: array
items:
type: string
example:
- '1'
- '2'
- name: page
in: query
description: Page number (1-based).
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
description: Number of records per page.
schema:
type: integer
minimum: 1
maximum: 100
default: 100
responses:
'200':
description: Leave summaries retrieved successfully.
content:
application/json:
schema:
"$ref": "#/components/schemas/EmployeeLeavesSummaryResponse"
'400':
"$ref": "#/components/responses/BadRequest"
'401':
"$ref": "#/components/responses/Unauthorized"
"/openapi/v1/employees":
get:
tags:
- Employees
summary: List
description: |-
# **Request**
`GET /openapi/v1/employees`
This API used to get all active employees basic info
**Note:** If the API key has the "Get Employee Financial Info" permission, the response will include additional financial fields for each employee:
- `basic_salary`: Employee's basic salary
- `first_salary_pay_date`: Date of first salary payment
- `last_salary_pay_date`: Contract end date (last salary payment date)
- `bank`: Employee bank details object (`name`, `account_title`, `iban`). Requires the **"Get Employee Financial Info"** permission.
**Note:** If the API key has the "Get Employee Accounting Info" permission, the response will include additional accounting fields for each employee:
- `subsidiary_id`: Employee's subsidiary ID
- `tracking_dimension_mappings`: Employee's tracking dimension mappings
These fields will be omitted if the API key does not have the required permission.
The request includes the following:
### HEADERS
| name | **Required** | description | **Type** | **Example** | **default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| api-version | Yes | Supported API version s | Integer | 1 | | currently supported is 1 only |
| Slug | Yes | Organization slug name | String | abcd | | |
| Access-Token | Yes | Used to allow an application to access an API it generated from Session API | String | eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRp
ZmllciI6OTAwMDAxNCwiYXBpX2tleV9pZCI6MSwic291cm
NlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhd
CI6MTY5OTYwMjF4NiwiZXhwIjoxNzAyMTk0Njg2fQ.upSy
VVcRrBe2SNUvjnAlDq7NO-N_tenPnGF6zNs1KZU | | |
| source | No | the source type of Open Api | String | open_api | open_api | Supported values:
\- open_api
\- external_aggregator |
| username | Conditional:
if the source type: external_aggregator | the name of the external service | String | workable | | |
#### Query Parameters
| **name** | **Required** | **Description** | **Type** | **Example** | **Default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| rpp | No | control the limit of the shown result per page | Integer | 50 | 100 | Minimum: 1
Maximum: 100 |
| page | No | choose the required page | Integer | 5 | 1 | |
| id | Yes | Unique id of the employee | String | bab6cd98-7246-4cfc-a576-19bc00391792 | | UUID type |
| date | No | This filter use to get employees who created at this date and on | Date | 2023/01/01 | | |
| status | No | This filter use to filter employees by there status and support two values (active - inactive) | string | active | | must be within \[active, inactive\] |
| terminate_date\[from\] | No | This filter use to get employees who got offboarded from specific date and on | Date | 2022/01/01 | | |
| terminate_date\[to\] | No | This filter use to get employees who got offboarded until specific date | Date | 2023/12/01 | | |
| delete_date\[from\] | No | This filter use to get employees who got deleted from system from specific date and on | Date | 2022/01/01 | | |
| delete_date\[to\] | No | This filter use to get employees who got deleted from system until specific date | Date | 2023/12/01 | | |
| joining_date\[from\] | No | This filter use to get employees who joined from specific date and on | Date | 2022/01/01 | | |
| joining_date\[to\] | No | This filter use to get employees who joined until specific date | Date | 2023/12/01 | | |
---
# Response
- Success Response
The success response of the API represented as the following:
Plain Text
```
{
"success": true,
"message": null,
"data": {
"employees": [
{
"id": "bab6cd98-7246-4cfc-a576-19bc00391792",
"code": 165,
"full_name_en": "Veenu George",
"full_name_ar": "فينو جورج",
"gender": "Male",
"marital_status": "Single",
"telephone": "99999999999",
"email": "test@abcd.net",
"personal_email": "veenu.george@gmail.com",
"avatar": "https://abcd-public.s3.me-south-1.amazonaws.com/images/employee.png",
"is_active": true,
"status": "active",
"joining_date": "2017-05-21",
"date_of_birth": "1982-04-20",
"passport_number": "1111111111",
"line_manager": {
"id": "8b5f7e1a-2cd3-4ad0-b9c4-745734jbhjb",
"name": "Majed Bazibidy"
},
"is_invited": true,
"last_active_time": "23 Jun 2022 12:44 PM",
"working_experience_period": "6 Years - 3 Months - 10 Days",
"created_at": "May 14, 2019",
"address": {
"id": 68799,
"home_address1": "55 West 25th Street",
"home_address2": null,
"home_city": "Minneapolis",
"home_postal_code": null,
"home_country": "Yemen",
"saudi_address1": null,
"saudi_address2": null,
"saudi_city": "mukalla",
"saudi_postal_code": "65432",
"saudi_country": null,
"employee_id": 36826,
"status": "Pending",
"home_po_box": null,
"created_at": "2023-08-29T08:49:11.141Z",
"updated_at": "2023-08-29T09:52:22.285Z",
"building_number": 23456,
"street_name": "first",
"district": "Al-code"
},
"job_title": {
"id": 14330,
"name_en": "Salesman",
"name_ar": "Salesman"
},
"business_unit": {
"id": "c33f90d6-85d8-4f99-baae-d6543bd96ab8",
"name_en": "Central sales Dep",
"name_ar": "Central sales Dep in Arabic"
},
"department": {
"id": 10171,
"name_en": "Central sales Dep",
"name_ar": "Central sales Dep"
},
"employment_type": {
"id": 78,
"name_en": "Full Time",
"name_ar": "دوام كامل"
},
"location": {
"id": 6589,
"address_en": "CR- Deryah-1",
"address_ar": "CR- Deryah-1"
},
"nationality": {
"id": 161,
"name_en": "Singaporean",
"name_ar": "سنغافوري"
},
"document_number": "1070400252"
}
]
}
}
```
This contain the following:
| **key** | **Description** | **value** |
| --- | --- | --- |
| success | represent the status of the API response | true |
| message | show additional message | null |
| data | show the required data to fetch, and contain basic info all of the employees | hash of data |
| Status_code | the status code of the api request | 200 |
---
Pagination:
- `current_page`: The current page of the results.
- `next_page`: The URL of the next page of results, if available.
- `previous_page`: The URL of the previous page of results, if available.
- `total_pages`: The total number of pages.
- `per_page`: The number of results per page.
- `total_entries`: The total number of entries across all pages.
---
### Error Response
The success response of the API represented as the following:
Plain Text
```
{
"success": false,
"error": "error message",
"status_code": 400
}
```
This response contain the following:
| **name** | **Description** | **Value** |
| --- | --- | --- |
| success | represent the status of the API response | false |
| error | represent the error reason acquired during the request | error_messages |
| status_code | the status code of the api requests | error_status_code |
error_messages
| **message** | **Reason** |
| --- | --- |
| Parameter {field_name} is required | The field name is required |
| "value" is not a valid {type} | the value passed is not in valid type |
| invalid api version | invalid `api-version` header passed or api-version header was not passed at all |
| Organization not found with given subdomain | invalid `Slug` header value |
| Permission denied. Please contact your Administrator | `Slug` Header is missing or your organization doesn't support open api feature |
| This call requires login | `Access-Token` is missing or invalid |
| Your account has been logged out. Please, log in again | previously logged out or expired token |
| Your account temporary suspended, please contact account manager | The organization account is suspended |
| Bad credentials | the credentials is not suited on that organization |
| invalid external aggregator | the aggregator name is not valid within that organization |
| Unable to authenticate employee | api-key is not active or valid |
Please note that some of the values for properties may vary in the actual response and should not be considered as fixed values.
operationId: list
parameters:
- name: page
in: query
schema:
type: string
- name: rpp
in: query
schema:
type: string
- name: date
in: query
schema:
type: string
- name: status
in: query
schema:
type: string
- name: terminate_date[from]
in: query
schema:
type: string
- name: terminate_date[to]
in: query
schema:
type: string
- name: delete_date[from]
in: query
schema:
type: string
- name: delete_date[to]
in: query
schema:
type: string
- name: joining_date[from]
in: query
schema:
type: string
- name: joining_date[to]
in: query
schema:
type: string
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: Success Response By External aggregator
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
employees:
type: array
example:
- address:
avatar:
code: 43
created_at: May 14, 2019
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10620
name_ar: تطوير الأعمال
name_en: Business Development
code: DEPT-001
document_number: '1075662542'
email: o.ghazali@abcd.net
personal_email: fariz.alshomer@gmail.com
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: فارس محمد الشومر t
full_name_en: Fariz Alshomer
gender: Female
id: f664cdf1-5911-4f67-bf40-244ef23040a9
is_active: false
is_invited: true
job_title:
id: 15205
name_ar: مسؤول تطوير الأعمال
name_en: Business Development Officer
joining_date: '2022-01-05'
date_of_birth: '1982-04-20'
last_active_time: 14 Sep 2022 10:41 AM
line_manager:
full_name: Hassan Bahlewah
guid: 651cf929-5207-42e5-bb70-3a1531468e5b
location:
id: 736
name_ar: أليم
name_en: ALEEM
marital_status: Single
nationality:
id: 136
name_ar: عماني
name_en: Omani
passport_number: '1234565653378'
status: inactive
telephone: '12345678'
terminate_date: '2022-10-26'
working_experience_period: Year - 11 Months - 8 Days
- address:
avatar:
code: 77
created_at: May 14, 2019
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10499
name_ar: Service
name_en: Service
code: DEPT-006
document_number: '2378311134'
email: bamohammad@abcd.net
personal_email: ali.alsheiba@gmail.com
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: علي محمد الشيبة
full_name_en: Ali Mohammed Al Sheiba
gender: Male
id: 0a61a200-5cc9-4fb9-a334-ef23df811dbe
is_active: false
is_invited: true
job_title:
id: 14980
name_ar: Software Developer
name_en: Software Developer
joining_date: '2020-01-01'
date_of_birth: '1982-04-20'
last_active_time: 25 Sep 2022 4:27 PM
line_manager:
full_name: Mohamed Bajobair
guid: f0a3deb1-11c5-4137-bb8d-1530f239efa3
location:
id: 98
name_ar: أبحر
name_en: Obhor
marital_status: Single
nationality:
id: 55
name_ar: مصرى
name_en: Egyptian
passport_number: a13568099
status: inactive
telephone: '8801441730'
terminate_date: '2022-06-01'
working_experience_period: 3 Years - 11 Months - 12 Days
- address:
avatar:
code: 1261
created_at: March 10, 2020
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10467
name_ar: accountant
name_en: accountant
code: DEPT-001
document_number: '8766545432'
email:
personal_email:
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: تتتتتتتتتن اتتتتتتتتتت
full_name_en: عاتتتتتتتتتتتتتتت لاااااااااااااا
gender:
id: 8494bbcb-db13-44af-b697-9706aaa3f5a3
is_active: false
is_invited: false
job_title:
id: 14327
name_ar: Accounting Manager
name_en: Accounting Manager
joining_date: '2020-03-01'
date_of_birth: '1982-04-20'
last_active_time: The employee has never logged in to his
account
line_manager:
full_name:
guid:
location:
id: 872
name_ar: البقيع
name_en: Al Baqeaa
marital_status:
nationality:
id: 14
name_ar: البحريني
name_en: Bahraini
passport_number: ''
status: inactive
telephone: ''
terminate_date: '2023-07-15'
working_experience_period: 3 Years - 9 Months - 12 Days
- address:
avatar:
code: 119
created_at: May 14, 2019
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10171
name_ar: Central sales Dep
name_en: Central sales Dep
code: DEPT-002
document_number: '2295073429'
email:
personal_email:
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: قوربيت سنق
full_name_en: Gurpreet Singh
gender: Male
id: 203702b8-5776-46a1-ad02-aa850b27dd0a
is_active: false
is_invited: false
job_title:
id: 14330
name_ar: Salesman
name_en: Salesman
joining_date: '2023-01-01'
date_of_birth: '1982-04-20'
last_active_time: The employee has never logged in to his
account
line_manager:
full_name:
guid:
location:
id: 6596
name_ar: CR- Rabwah / Khurais
name_en: CR- Rabwah / Khurais
marital_status: Married
nationality:
id: 193
name_ar: يمني
name_en: Yemeni
passport_number: '3886792'
status: inactive
telephone: ''
terminate_date: '2023-06-11'
working_experience_period: 11 Months - 12 Days
- address:
avatar:
code: 72
created_at: May 14, 2019
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10499
name_ar: Service
name_en: Service
code: DEPT-006
document_number: '2363725132'
email: abcd_muk@outlook.com
personal_email: yogesh.thakur@outlook.com
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: يوقش تاقور
full_name_en: Yogesh Thakur
gender: Male
id: 8b6fb80c-6bfc-454b-a289-ad8cc7a6a155
is_active: false
is_invited: true
job_title:
id: 14983
name_ar: Sr. QA Analyst
name_en: Sr. QA Analyst
joining_date: '2015-07-06'
date_of_birth: '1982-04-20'
last_active_time: 06 Sep 2021 12:11 PM
line_manager:
full_name:
guid:
location:
id: 6735
name_ar: اا
name_en: Malaz
marital_status: Single
nationality:
id: 81
name_ar: هندي
name_en: Indian
passport_number: '3456788'
status: inactive
telephone: ''
terminate_date: '2023-02-22'
working_experience_period: 8 Years - 5 Months - 7 Days
- address:
avatar:
code: 138
created_at: May 14, 2019
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10182
name_ar: corporate sales Dep
name_en: corporate sales Dep
code: DEPT-004
document_number: '2403139559'
email: m.sheikh@abcd.net
personal_email: eme.saleh@gmail.com
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: ايمان صالح الجوهي
full_name_en: eme saleh
gender: Male
id: 81229ebc-cc53-4c11-b704-9a123eeff2b6
is_active: false
is_invited: true
job_title:
id: 14331
name_ar: corporate sales officer
name_en: corporate sales officer
joining_date: '2016-09-01'
date_of_birth: '1982-04-20'
last_active_time: 24 Jan 2023 3:04 PM
line_manager:
full_name:
guid:
location:
id: 6569
name_ar: CR- Riyadh corporate sales
name_en: CR- Riyadh corporate sales
marital_status: Single
nationality:
id: 55
name_ar: مصرى
name_en: Egyptian
passport_number: a010617554
status: inactive
telephone: ''
terminate_date: '2023-01-10'
working_experience_period: 7 Years - 3 Months - 12 Days
- address:
avatar:
code: 75
created_at: May 14, 2019
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 46910
name_ar: الإدارة العليا
name_en: Higher ManagementHigher Management
code: DEPT-003
document_number: '2160136830'
email:
personal_email:
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: عثمان البكري
full_name_en: Othman Mokhtar Mohammed
gender: Male
id: 3302a957-b39a-4f89-a022-de61ef367532
is_active: false
is_invited: true
job_title:
id: 14975
name_ar: QA Trainee
name_en: QA Trainee
joining_date: '2016-01-01'
date_of_birth: '1982-04-20'
last_active_time: 23 Oct 2023 11:36 AM
line_manager:
full_name:
guid:
location:
id: 6735
name_ar: اا
name_en: Malaz
marital_status: Single
nationality:
id: 175
name_ar: سوري
name_en: Syrian
passport_number: n011490005
status: inactive
telephone: ''
terminate_date: '2023-10-31'
working_experience_period: 7 Years - 11 Months - 12 Days
- address:
avatar:
code: 9353974150243
created_at: January 22, 2023
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10171
name_ar: Central sales Dep
name_en: Central sales Dep
code: DEPT-002
document_number: '6933769557'
email: test@test.com
personal_email: test.personal@test.com
employment_type:
id: 7808
name_ar: مقاول
name_en: Contractor
full_name_ar: test test test
full_name_en: test test test
gender:
id: f0024492-9907-48ae-ba3d-23f933ce50cb
is_active: false
is_invited: true
job_title:
id: 14327
name_ar: Accounting Manager
name_en: Accounting Manager
joining_date: '2023-01-01'
date_of_birth: '1982-04-20'
last_active_time: The employee has never logged in to his
account
line_manager:
full_name:
guid:
location:
id: 6593
name_ar: "CR- Buraida\t-1"
name_en: "CR- Buraida\t-1"
marital_status:
nationality:
id: 55
name_ar: مصرى
name_en: Egyptian
passport_number:
status: inactive
telephone: ''
terminate_date: '2023-02-07'
working_experience_period: 11 Months - 12 Days
- address:
avatar:
code: 21
created_at: March 23, 2022
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 1354
name_ar: جيسر
name_en: abcd
code: DEPT-005
document_number: '273842853892'
email: m.bamatraf@abcd.net
personal_email: cyper.commander@gmail.com
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: Cyper Commander
full_name_en: Cyper Commander
gender:
id: c77c4bd9-8e31-44df-a6ce-9ea82f06ed9e
is_active: false
is_invited: true
job_title:
id:
name_ar:
name_en:
joining_date: '2021-01-10'
date_of_birth: '1982-04-20'
last_active_time: 14 Sep 2022 11:02 AM
line_manager:
full_name: Hassan Bahlewah
guid: 651cf929-5207-42e5-bb70-3a1531468e5b
location:
id: 8392
name_ar: المكلا
name_en: Mukall
marital_status:
nationality:
id: 14
name_ar: البحريني
name_en: Bahraini
passport_number:
status: inactive
telephone: ''
terminate_date: '2022-10-16'
working_experience_period: 2 Years - 11 Months - 3 Days
- address:
avatar:
code: 129859487263664
created_at: September 10, 2023
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10467
name_ar: accountant
name_en: accountant
code: DEPT-001
document_number: '12345678123'
email: pretty.saeed@gmail.com
personal_email: pretty.test@hotmail.com
employment_type:
id: 7808
name_ar: مقاول
name_en: Contractor
full_name_ar: Pretty Test
full_name_en: Pretty Test
gender:
id: 0fa160bd-e5cc-4f74-b026-3c54606ebe95
is_active: false
is_invited: true
job_title:
id: 15213
name_ar: Analyst (Pharma)
name_en: Analyst (Pharma)
joining_date: '2023-09-01'
date_of_birth: '1982-04-20'
last_active_time: '08 Nov 2023 3:55 PM'
line_manager:
full_name:
guid:
location:
id: 736
name_ar: أليم
name_en: ALEEM
marital_status:
nationality:
id: 55
name_ar: مصرى
name_en: Egyptian
passport_number:
status: inactive
telephone: ''
terminate_date: '2023-10-31'
working_experience_period: 3 Months - 12 Days
- address:
avatar:
code: 88
created_at: May 14, 2019
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10498
name_ar: Management department
name_en: Management department
code: DEPT-005
document_number: '2394049619'
email:
personal_email:
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: محمد باجبير
full_name_en: Mohamed Bajobair
gender: Male
id: 82b07c4c-26d4-48df-846b-1c0b0cded30b
is_active: false
is_invited: false
job_title:
id: 14985
name_ar: Marketing Specialist
name_en: Marketing Specialist
joining_date: '2017-09-24'
date_of_birth: '1982-04-20'
last_active_time: 19 Dec 2022 10:53 AM
line_manager:
full_name:
guid:
location:
id: 694
name_ar: العليا
name_en: Olaya
marital_status: Married
nationality:
id: 55
name_ar: مصرى
name_en: Egyptian
passport_number: a15182018
status: inactive
telephone: ''
terminate_date: '2022-12-18'
working_experience_period: 6 Years - 2 Months - 19 Days
- address:
avatar:
code: 93
created_at: May 14, 2019
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 3449
name_ar: Operations
name_en: Operations
code: DEPT-003
document_number: '2399023700'
email: ammar@aa.net
personal_email: salem.mohamed@gmail.com
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: سالم محمد
full_name_en: Salem Mohamed
gender: Male
id: 92e5fdbd-7d3c-46f0-9ae2-e7629f5d526f
is_active: false
is_invited: false
job_title:
id: 14986
name_ar: Branches Supervisor
name_en: Branches Supervisor
joining_date: '2018-12-02'
date_of_birth: '1982-04-20'
last_active_time: 23 Oct 2023 11:40 AM
line_manager:
full_name:
guid:
location:
id: 6737
name_ar: JED Admin
name_en: JED Admin
marital_status: Single
nationality:
id: 55
name_ar: مصرى
name_en: Egyptian
passport_number: a16548471
status: inactive
telephone: ''
terminate_date: '2023-10-30'
working_experience_period: 5 Years - 11 Days
- address:
building_number: 123
created_at: '2023-05-30T05:38:09.706Z'
district: الاالاال
employee_id: 39167
home_address1:
home_address2:
home_city:
home_country:
home_po_box:
home_postal_code:
id: 63740
saudi_address1:
saudi_address2:
saudi_city: تلتتلتتل
saudi_country:
saudi_postal_code: ٢٣٤٥
status: Pending
street_name: الاالالاالاالاال
updated_at: '2023-05-30T05:38:09.706Z'
avatar:
code: 3
created_at: July 2, 2019
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 750
name_ar: الدعم الفني
name_en: customer success
code: DEPT-004
document_number: '12365985689'
email:
personal_email:
employment_type:
id: 104
name_ar: موظف أجير
name_en: Ajeer
full_name_ar: اروى سعد داود
full_name_en: Arwa Saad
gender: Female
id: e16bf25f-86dd-413a-818a-8d50cc9feade
is_active: false
is_invited: true
job_title:
id: 276
name_ar: 'المدير التنفيذي '
name_en: CEO
joining_date: '2020-01-01'
date_of_birth: '1982-04-20'
last_active_time: 06 Sep 2021 12:11 PM
line_manager:
full_name: Mohammed Ahmed BaHashwan
guid: f50f709c-9e25-458f-8833-648de89a34d1
location:
id: 872
name_ar: البقيع
name_en: Al Baqeaa
marital_status: Single
nationality:
id: 155
name_ar: سعودي
name_en: Saudi
passport_number: '123445'
status: inactive
telephone: ''
terminate_date: '2022-02-12'
working_experience_period: 3 Years - 11 Months - 12 Days
- address:
avatar:
code: 1262
created_at: January 19, 2020
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10467
name_ar: accountant
name_en: accountant
code: DEPT-001
document_number: '121213233243500'
email:
personal_email:
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: اب ج د
full_name_en: ABC DEF
gender:
id: 87f22efb-5ce8-4d2b-8bdf-a9e698f8fe5b
is_active: false
is_invited: false
job_title:
id: 1833
name_ar: 'محاسب '
name_en: Accountant
joining_date: '2020-01-01'
date_of_birth: '1982-04-20'
last_active_time: The employee has never logged in to his
account
line_manager:
full_name:
guid:
location:
id: 736
name_ar: أليم
name_en: ALEEM
marital_status:
nationality:
id: 1
name_ar: الأفغاني
name_en: Afghan
passport_number: ''
status: inactive
telephone: ''
terminate_date: '2022-01-31'
working_experience_period: 3 Years - 11 Months - 12 Days
- address:
avatar:
code: 94
created_at: May 14, 2019
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10620
name_ar: تطوير الأعمال
name_en: Business Development
code: DEPT-001
document_number: '1236598652'
email: albandri@abcd.net
personal_email: albandari.khaled@gmail.com
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: البندري خالد
full_name_en: Albandari Khaled
gender: Female
id: 93ac2f58-a00d-49b2-a6df-7097c9727f15
is_active: false
is_invited: true
job_title:
id: 884
name_ar: مستشار موارد بشرية
name_en: HR Consultant
joining_date: '2019-02-28'
date_of_birth: '1982-04-20'
last_active_time: The employee has never logged in to his
account
line_manager:
full_name:
guid:
location:
id: 1338
name_ar: الياسمين
name_en: Al yasimin
marital_status: Single
nationality:
id: 155
name_ar: سعودي
name_en: Saudi
passport_number: m7043480
status: inactive
telephone: ''
terminate_date: '2022-12-31'
working_experience_period: 4 Years - 9 Months - 15 Days
- address:
avatar:
code: 99786
created_at: December 21, 2021
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10171
name_ar: Central sales Dep
name_en: Central sales Dep
code: DEPT-002
document_number: '454545334444'
email:
personal_email:
employment_type:
id: 141
name_ar: موظف عن بعد
name_en: Remote
full_name_ar: Abeer mohammed salem eshaq
full_name_en: Abeer mohammed salem eshaq
gender:
id: 7206029c-4caf-4309-b4cf-45b53604a70c
is_active: false
is_invited: false
job_title:
id:
name_ar:
name_en:
joining_date: '2021-12-22'
date_of_birth: '1982-04-20'
last_active_time: The employee has never logged in to his
account
line_manager:
full_name:
guid:
location:
id: 736
name_ar: أليم
name_en: ALEEM
marital_status:
nationality:
id: 9
name_ar: " لأرميني"
name_en: Armenian
passport_number:
status: inactive
telephone: ''
terminate_date: '2023-03-02'
working_experience_period: Year - 11 Months - 21 Days
- address:
avatar:
code: 9
created_at: July 22, 2019
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10622
name_ar: Pharma Lab
name_en: Pharma Lab
code: DEPT-003
document_number: '1234567'
email: yunes@abcd.net
personal_email: younes.employee@gmail.com
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: يونس موظف
full_name_en: Younes Employee
gender: Male
id: e0173068-3793-407a-8ad3-7e42d41ff878
is_active: false
is_invited: true
job_title:
id: 15209
name_ar: Pharmaceutical Lab Manager
name_en: Pharmaceutical Lab Manager
joining_date: '2021-12-08'
date_of_birth: '1982-04-20'
last_active_time: 06 Sep 2021 12:11 PM
line_manager:
full_name: Yasser Mohammed
guid: 1efd85e4-300a-4a61-873d-80e638be4f0a
location:
id: 6772
name_ar: الندوة
name_en: Al Nadweh
marital_status: Married
nationality:
id: 14
name_ar: البحريني
name_en: Bahraini
passport_number: o143318
status: inactive
telephone: ''
terminate_date: '2022-12-14'
working_experience_period: 2 Years - 5 Days
- address:
avatar:
code: 62
created_at: May 14, 2019
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10498
name_ar: Management department
name_en: Management department
code: DEPT-005
document_number: '2324380415'
email:
personal_email:
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: محمد غسان الجخلب
full_name_en: Mohammed Ghassan Eljakhlab
gender: Male
id: 9f96007c-e9f0-4e71-a720-c5385005d709
is_active: false
is_invited: true
job_title:
id: 14978
name_ar: Product Manager
name_en: Product Manager
joining_date: '2011-01-01'
date_of_birth: '1982-04-20'
last_active_time: 06 Sep 2021 12:11 PM
line_manager:
full_name:
guid:
location:
id: 694
name_ar: العليا
name_en: Olaya
marital_status: Single
nationality:
id: 55
name_ar: مصرى
name_en: Egyptian
passport_number: ''
status: inactive
telephone: '539391878'
terminate_date: '2022-02-27'
working_experience_period: 12 Years - 11 Months - 12 Days
- address:
avatar:
code: 4240266548201
created_at: January 10, 2023
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 10467
name_ar: accountant
name_en: accountant
code: DEPT-001
document_number: '382376432765'
email:
personal_email:
employment_type:
id: 7808
name_ar: مقاول
name_en: Contractor
full_name_ar: New Employee
full_name_en: New Employee
gender:
id: 35b0b925-1d17-4bdf-9e11-4e01f2e8d783
is_active: false
is_invited: false
job_title:
id:
name_ar:
name_en:
joining_date: '2022-01-15'
date_of_birth: '1982-04-20'
last_active_time: The employee has never logged in to his
account
line_manager:
full_name:
guid:
location:
id: 12020
name_ar: الحرم
name_en: Alharam
marital_status:
nationality:
id: 2
name_ar: " الألبانية"
name_en: Albanian
passport_number:
status: inactive
telephone: ''
terminate_date: '2022-12-15'
working_experience_period: Year - 10 Months - 28 Days
- address:
avatar:
code: 6586328500461
created_at: October 3, 2022
delete_date:
business_unit:
id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
department:
id: 347
name_ar: أداره
name_en: Management
code: DEPT-006
document_number: '01144919197'
email: ahmed.shaalan@abcd.net
personal_email: ahmed.shaalan@gmail.com
employment_type:
id: 78
name_ar: دوام كامل
name_en: Full Time
full_name_ar: احمدد
full_name_en: ahmed shaalan
gender:
id: c9219aee-8952-492e-afbf-0fbeead620af
is_active: false
is_invited: true
job_title:
id: 1833
name_ar: 'محاسب '
name_en: Accountant
joining_date: '2022-10-03'
date_of_birth: '1982-04-20'
last_active_time: 18 Dec 2022 11:13 AM
line_manager:
full_name:
guid:
location:
id: 12020
name_ar: الحرم
name_en: Alharam
marital_status:
nationality:
id: 55
name_ar: مصرى
name_en: Egyptian
passport_number:
status: inactive
telephone: ''
terminate_date: '2022-10-10'
working_experience_period: Year - 2 Months - 10 Days
items:
type: object
properties:
address:
type: object
properties: {}
nullable: true
example:
avatar:
type: object
nullable: true
example: 'null'
code:
type: number
example: 43
created_at:
type: string
example: May 14, 2019
delete_date:
type: object
nullable: true
example: 'null'
business_unit:
type: object
properties:
id:
type: string
example: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en:
type: string
example: Business Development
name_ar:
type: string
example: تطوير الأعمال
department:
type: object
properties:
id:
type: number
example: 10620
name_ar:
type: string
example: تطوير الأعمال
name_en:
type: string
example: Business Development
document_number:
type: string
example: '1075662542'
email:
type: string
nullable: true
example: o.ghazali@abcd.net
personal_email:
type: string
nullable: true
example: ibraheem.personal@gmail.com
employment_type:
type: object
properties:
id:
type: number
example: 78
name_ar:
type: string
example: دوام كامل
name_en:
type: string
example: Full Time
full_name_ar:
type: string
example: فارس محمد الشومر t
full_name_en:
type: string
example: Fariz Alshomer
gender:
type: string
nullable: true
example: Female
id:
type: string
example: f664cdf1-5911-4f67-bf40-244ef23040a9
is_active:
type: boolean
example: false
is_invited:
type: boolean
example: true
job_title:
type: object
properties:
id:
type: number
nullable: true
example: 15205
name_ar:
type: string
nullable: true
example: مسؤول تطوير الأعمال
name_en:
type: string
nullable: true
example: Business Development Officer
joining_date:
type: string
example: '2022-01-05'
last_active_time:
type: string
example: 14 Sep 2022 10:41 AM
line_manager:
type: object
properties:
full_name:
type: string
nullable: true
example: Hassan Bahlewah
guid:
type: string
nullable: true
example: 651cf929-5207-42e5-bb70-3a1531468e5b
location:
type: object
properties:
id:
type: number
example: 736
name_ar:
type: string
example: أليم
name_en:
type: string
example: ALEEM
marital_status:
type: string
nullable: true
example: Single
nationality:
type: object
properties:
id:
type: number
example: 136
name_ar:
type: string
example: عماني
name_en:
type: string
example: Omani
passport_number:
type: string
nullable: true
example: '1234565653378'
status:
type: string
example: inactive
telephone:
type: string
example: '12345678'
terminate_date:
type: string
example: '2022-10-26'
working_experience_period:
type: string
example: Year - 11 Months - 8 Days
basic_salary:
type: number
nullable: true
example: 5000.0
description: Employee's basic salary. Only included
when the API key has "Get Employee Financial Info"
permission.
first_salary_pay_date:
type: string
nullable: true
example: October 31, 2019
description: Date of first salary payment. Only included
when the API key has "Get Employee Financial Info"
permission.
last_salary_pay_date:
type: string
nullable: true
example: October 31, 2025
description: Date of last salary payment (contract end
date). Only included when the API key has "Get Employee
Financial Info" permission.
bank:
type: object
nullable: true
description: Employee bank details. Only included when
the API key has the "Get Employee Financial Info"
permission. Omitted entirely without that permission.
properties:
name:
type: string
nullable: true
example: Al Rajhi Bank
description: Bank name. Requires "Get Employee Financial
Info" permission.
account_title:
type: string
nullable: true
example: Veenu George
description: Bank account holder name. Requires
"Get Employee Financial Info" permission.
iban:
type: string
nullable: true
example: SA0380000000608010167519
description: Employee IBAN number. Requires "Get
Employee Financial Info" permission.
subsidiary_id:
type: string
example: e21de38e-2989-4072-b4e8-11211104c284
description: Employee's subsidiary ID. Only included
when the API key has "Get Employee Accounting Info"
permission.
tracking_dimension_mappings:
type: array
items:
type: object
properties:
tracking_dimension_value_id:
type: string
example: 9016d3e3-3379-4f71-b11d-70083e814dfe
allocation:
type: number
example: 100
created_at:
type: string
example: 2026/03/26
updated_at:
type: string
example: 2026/03/26
description: Employee's tracking dimension mappings.
Only included when the API key has "Get Employee Accounting
Info" permission.
pagination:
type: object
properties:
current_page:
type: number
example: 1
next_page:
type: number
example: 2
per_page:
type: number
example: 20
previous_page:
type: object
nullable: true
example: 'null'
total_entries:
type: number
example: 28
total_pages:
type: number
example: 2
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
post:
tags:
- Employees
summary: Create
description: |-
# **Request**
`POST /openapi/v1/employees`
This API used to create new employee on abcd system
The request includes the following:
### HEADERS
| name | **Required** | description | **Type** | **Example** | **default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| api-version | Yes | Supported API version s | Integer | 1 | | currently supported is 1 only |
| Slug | Yes | Organization slug name | String | abcd | | |
| Access-Token | Yes | Used to allow an application to access an API it generated from Session API | String | eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRp
ZmllciI6OTAwMDAxNCwiYXBpX2tleV9pZCI6MSwic291cm
NlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhd
CI6MTY5OTYwMjF4NiwiZXhwIjoxNzAyMTk0Njg2fQ.upSy
VVcRrBe2SNUvjnAlDq7NO-N_tenPnGF6zNs1KZU | | |
| source | No | the source type of Open Api | String | open_api | open_api | Supported values:
\- open_api
\- external_aggregator |
| username | Conditional:
if the source type: external_aggregator | the name of the external service | String | workable | | |
#### Body Parameters
| **Name** | **Description** |
| --- | --- |
| code | Unique identifier assigned to each employee within an organization |
| full_name_en | Full name of employee on English language at least contain two parts |
| full_name_ar | Full name of employee on Arabic language at least contain two parts |
| department_id | Department id get this value from lookups |
| employment_type_id | Employment type id get this value from lookups |
| location_id | Location id get this value from lookups |
| joining_date | The date that employee join the organization |
| email | Employee email |
| personal_email | Employee personal email. Optional. Must be a valid email, unique among the organization's active employees, and is stored lowercased. |
| gender | Allowed gender on abcd system (Male - Female) |
| marital_status | Allowed marital status on abcd system (Single - Married - Divorced - Widowed) |
| document_number | Employee Identifier number (ID - Iqama) |
| nationality_id | Nationality id get this value from lookups |
| contract_type | Allowed contract type on abcd system (Fixed term - Indefinite) |
| contract_period | Allowed contract period on abcd system (1 year - 2 years - Custom) |
| end_date | It represent the end date of the contract |
---
# Response
- Success Response
Plain Text
```
{
"success": true,
"message": "Employee registered successfully",
"data": {
"employee": {
"id": null,
"code": 65458232,
"full_name_en": "Ibraheem Ahemd Salim",
"full_name_ar": "سالم إبراهيم أحمد",
"gender": "Male",
"marital_status": "Single",
"telephone": "",
"email": "ibrahemsalsdaem@ahmed.com",
"personal_email": "ibraheem.personal@gmail.com",
"avatar": "https://abcd-public.s3.me-south-1.amazonaws.com/images/employee.png",
"is_active": true,
"status": "active",
"joining_date": "2023-12-12",
"passport_number": null,
"line_manager": null,
"is_invited": true,
"last_active_time": "The employee has never logged in to his account",
"working_experience_period": "Not joined yet",
"created_at": "August 30, 2023",
"address": null,
"job_title": null,
"business_unit": {
"id": "c33f90d6-85d8-4f99-baae-d6543bd96ab8",
"name_en": "business-unit-open-api-1",
"name_ar": "business-unit-open-api-1-ar"
},
"department": {
"id": 10467,
"name_en": "accountant",
"name_ar": "accountant"
},
"employment_type": {
"id": 104,
"name_en": "Ajeer",
"name_ar": "موظف أجير"
},
"location": {
"id": 872,
"address_en": "Al Baqeaa",
"address_ar": "البقيع"
},
"nationality": {
"id": 4,
"name_en": "American",
"name_ar": " أمريكي"
},
"document_number": "32584167917"
}
}
}
```
---
This response contain the following:
| **name** | **Description** | **Value** |
| --- | --- | --- |
| success | represent the status of the API response | false |
| error | represent the error reason acquired during the request | error_messages |
| status_code | the status code of the api requests | error_status_code |
error_messages
| **message** | **Reason** |
| --- | --- |
| Parameter {field_name} is required | The field name is required |
| "value" is not a valid {type} | the value passed is not in valid type |
| invalid api version | invalid `api-version` header passed or api-version header was not passed at all |
| Organization not found with given subdomain | invalid `Slug` header value |
| Permission denied. Please contact your Administrator | `Slug` Header is missing or your organization doesn't support open api feature |
| This call requires login | `Access-Token` is missing or invalid |
| Your account has been logged out. Please, log in again | previously logged out or expired token |
| Your account temporary suspended, please contact account manager | The organization account is suspended |
| Bad credentials | the credentials is not suited on that organization |
| invalid external aggregator | the aggregator name is not valid within that organization |
| Unable to authenticate employee | api-key is not active or valid |
Please note that some of the values for properties may vary in the actual response and should not be considered as fixed values.
### Error Response
The success response of the API represented as the following:
Plain Text
```
{
"success": false,
"error": "error message",
"status_code": 400
}
```
operationId: create
parameters:
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
employee:
type: object
properties:
code:
type: string
example: '65458232'
department_id:
type: number
example: 10467
email:
type: string
example: ibrahemsalsdaem@ahmed.com
personal_email:
type: string
nullable: true
example: ibraheem.personal@gmail.com
employee_contracts_attributes:
type: array
example:
- contract_period: 2 years
contract_type: Fixed term
end_date: 2023/12/12
items:
type: object
properties:
contract_period:
type: string
example: 2 years
contract_type:
type: string
example: Fixed term
end_date:
type: string
example: 2023/12/12
employee_outsourcing_company_attributes:
type: object
properties:
outsourcing_company_id:
type: number
example: 44
employment_type_id:
type: number
example: 104
full_name_ar:
type: string
example: " سالم إبراهيم أحمد"
full_name_en:
type: string
example: Ibraheem Ahemd Salim
gender:
type: string
example: Male
identification_info_attributes:
type: object
properties:
document_number:
type: string
example: '32584167917'
nationality_id:
type: number
example: 4
joining_date:
type: string
example: 2023/12/12
location_id:
type: number
example: 872
marital_status:
type: string
example: Single
required: false
responses:
'200':
description: Success Response By external aggregator
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
employee:
type: object
properties:
address:
type: object
nullable: true
example: 'null'
avatar:
type: string
example: https://abcd-public.s3.me-south-1.amazonaws.com/images/employee.png
code:
type: number
example: 65458232
created_at:
type: string
example: August 30, 2023
business_unit:
type: object
properties:
id:
type: string
example: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en:
type: string
example: business-unit-open-api-1
name_ar:
type: string
example: business-unit-open-api-1-ar
department:
type: object
properties:
id:
type: number
example: 10467
name_ar:
type: string
example: accountant
name_en:
type: string
example: accountant
document_number:
type: string
example: '32584167917'
email:
type: string
example: test@abcd.net
personal_email:
type: string
nullable: true
example: ibraheem.personal@gmail.com
employment_type:
type: object
properties:
id:
type: number
example: 104
name_ar:
type: string
example: موظف أجير
name_en:
type: string
example: Ajeer
full_name_ar:
type: string
example: سالم إبراهيم أحمد
full_name_en:
type: string
example: Ibraheem Ahemd Salim
gender:
type: string
example: Male
id:
type: object
nullable: true
example: 'null'
is_active:
type: boolean
example: true
is_invited:
type: boolean
example: true
job_title:
type: object
nullable: true
example: 'null'
joining_date:
type: string
example: '2023-12-12'
last_active_time:
type: string
example: The employee has never logged in to his account
line_manager:
type: object
nullable: true
example: 'null'
location:
type: object
properties:
address_ar:
type: string
example: البقيع
address_en:
type: string
example: Al Baqeaa
id:
type: number
example: 872
marital_status:
type: string
example: Single
nationality:
type: object
properties:
id:
type: number
example: 4
name_ar:
type: string
example: " أمريكي"
name_en:
type: string
example: American
passport_number:
type: object
nullable: true
example: 'null'
status:
type: string
example: active
telephone:
type: string
example: ''
working_experience_period:
type: string
example: Not joined yet
message:
type: string
example: Employee registered successfully
success:
type: boolean
example: true
"/openapi/v1/employees/basic_info":
get:
tags:
- Employees
summary: Show
description: |-
# **Request**
`GET /openapi/v1/employees/basic_info`
This API endpoint retrieves basic info of specific employee
The request includes the following:
### HEADERS
| name | **Required** | description | **Type** | **Example** | **default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| api-version | Yes | Supported API version s | Integer | 1 | | currently supported is 1 only |
| Slug | Yes | Organization slug name | String | abcd | | |
| Access-Token | Yes | Used to allow an application to access an API it generated from Session API | String | eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRp
ZmllciI6OTAwMDAxNCwiYXBpX2tleV9pZCI6MSwic291cm
NlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhd
CI6MTY5OTYwMjF4NiwiZXhwIjoxNzAyMTk0Njg2fQ.upSy
VVcRrBe2SNUvjnAlDq7NO-N_tenPnGF6zNs1KZU | | |
| source | No | the source type of Open Api | String | open_api | open_api | Supported values:
\- open_api
\- external_aggregator |
| username | Conditional:
if the source type: external_aggregator | the name of the external service | String | workable | | |
#### Query Parameters
| **name** | **Required** | **Description** | **Type** | **Example** | **Default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| rpp | No | controll the limit of the shown result per page | Integer | 50 | 100 | Minimum: 1
Maximum: 100 |
| page | No | choose the required page | Integer | 5 | 1 | |
| id | Yes | Unique id of the employee | String | bab6cd98-7246-4cfc-a576-19bc00391792 | | UUID type |
---
# Response
- Success Response
The success response of the API represented as the following:
Plain Text
```
{
"success": true,
"message": null,
"data": {
"employee": {
"id": "bab6cd98-7246-4cfc-a576-19bc00391792",
"code": 165,
"full_name_en": "Veenu George",
"full_name_ar": "فينو جورج",
"gender": "Male",
"marital_status": "Single",
"telephone": "99999999999",
"email": "test@abcd.net",
"personal_email": "veenu.george@gmail.com",
"date_of_birth": "1982-04-20",
"avatar": "https://abcd-public.s3.me-south-1.amazonaws.com/images/employee.png",
"is_active": true,
"status": "active",
"joining_date": "2017-05-21",
"passport_number": "1111111111",
"line_manager": {
"id": "8b5f7e1a-2cd3-4ad0-b9c4-745734jbhjb",
"name": "Majed Bazibidy"
},
"is_invited": true,
"last_active_time": "23 Jun 2022 12:44 PM",
"working_experience_period": "6 Years - 3 Months - 10 Days",
"created_at": "May 14, 2019",
"address": {
"id": 68799,
"home_address1": "55 West 25th Street",
"home_address2": null,
"home_city": "Minneapolis",
"home_postal_code": null,
"home_country": "Yemen",
"saudi_address1": null,
"saudi_address2": null,
"saudi_city": "mukalla",
"saudi_postal_code": "65432",
"saudi_country": null,
"employee_id": 36826,
"status": "Pending",
"home_po_box": null,
"created_at": "2023-08-29T08:49:11.141Z",
"updated_at": "2023-08-29T09:52:22.285Z",
"building_number": 23456,
"street_name": "first",
"district": "Al-code"
},
"job_title": {
"id": 14330,
"name_en": "Salesman",
"name_ar": "Salesman"
},
"business_unit": {
"id": "c33f90d6-85d8-4f99-baae-d6543bd96ab8",
"name_en": "business-unit-open-api-1",
"name_ar": "business-unit-open-api-1-ar"
},
"department": {
"id": 10171,
"name_en": "Central sales Dep",
"name_ar": "Central sales Dep"
},
"employment_type": {
"id": 78,
"name_en": "Full Time",
"name_ar": "دوام كامل"
},
"location": {
"id": 6589,
"address_en": "CR- Deryah-1",
"address_ar": "CR-Deryah-1"
},
"nationality": {
"id": 161,
"name_en": "Singaporean",
"name_ar": "سنغافوري"
},
"document_number": "1070400252"
}
}
}
```
This contain the following:
| **key** | **Description** | **value** |
| --- | --- | --- |
| success | represent the status of the API response | true |
| message | show additional message | null |
| data | show the required data to fetch, and contain basic info for the employee | hash of data |
| Status_code | the status code of the api request | 200 |
---
Pagination:
- `current_page`: The current page of the results.
- `next_page`: The URL of the next page of results, if available.
- `previous_page`: The URL of the previous page of results, if available.
- `total_pages`: The total number of pages.
- `per_page`: The number of results per page.
- `total_entries`: The total number of entries across all pages.
---
### Error Response
The success response of the API represented as the following:
Plain Text
```
{
"success": false,
"error": "error message",
"status_code": 400
}
```
This response contain the following:
| **name** | **Description** | **Value** |
| --- | --- | --- |
| success | represent the status of the API response | false |
| error | represent the error reason acquired during the request | error_messages |
| status_code | the status code of the api requests | error_status_code |
error_messages
| **message** | **Reason** |
| --- | --- |
| Parameter {field_name} is required | The field name is required |
| "value" is not a valid {type} | the value passed is not in valid type |
| invalid api version | invalid `api-version` header passed or api-version header was not passed at all |
| Organization not found with given subdomain | invalid `Slug` header value |
| Permission denied. Please contact your Administrator | `Slug` Header is missing or your organization doesn't support open api feature |
| This call requires login | `Access-Token` is missing or invalid |
| Your account has been logged out. Please, log in again | previously logged out or expired token |
| Your account temporary suspended, please contact account manager | The organization account is suspended |
| Bad credentials | the credentials is not suited on that organization |
| invalid external aggregator | the aggregator name is not valid within that organization |
| Unable to authenticate employee | api-key is not active or valid |
Please note that some of the values for properties may vary in the actual response and should not be considered as fixed values.
operationId: show
parameters:
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: bab6cd98-7246-4cfc-a576-19bc00391792
required: false
responses:
'200':
description: Success Response By External Aggregator
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
employee:
type: object
properties:
address:
type: object
properties:
building_number:
type: number
example: 23456
created_at:
type: string
example: '2023-08-29T08:49:11.141Z'
district:
type: string
example: Al-code
employee_id:
type: number
example: 36826
home_address1:
type: string
example: 55 West 25th Street
home_address2:
type: object
nullable: true
example: 'null'
home_city:
type: string
example: Minneapolis
home_country:
type: string
example: Yemen
home_po_box:
type: object
nullable: true
example: 'null'
home_postal_code:
type: object
nullable: true
example: 'null'
id:
type: number
example: 68799
saudi_address1:
type: object
nullable: true
example: 'null'
saudi_address2:
type: object
nullable: true
example: 'null'
saudi_city:
type: string
example: mukalla
saudi_country:
type: object
nullable: true
example: 'null'
saudi_postal_code:
type: string
example: '65432'
status:
type: string
example: Pending
street_name:
type: string
example: first
updated_at:
type: string
example: '2023-08-29T09:52:22.285Z'
avatar:
type: string
example: https://abcd-public.s3.me-south-1.amazonaws.com/images/employee.png
code:
type: number
example: 165
created_at:
type: string
example: May 14, 2019
business_unit:
type: object
properties:
id:
type: string
example: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en:
type: string
example: business-unit-open-api-1
name_ar:
type: string
example: business-unit-open-api-1-ar
department:
type: object
properties:
id:
type: number
example: 10171
name_ar:
type: string
example: Central sales Dep
name_en:
type: string
example: Central sales Dep
document_number:
type: string
example: '1070400252'
email:
type: string
example: test@abcd.net
personal_email:
type: string
nullable: true
example: ibraheem.personal@gmail.com
date_of_birth:
type: string
example: '1982-04-20'
employment_type:
type: object
properties:
id:
type: number
example: 78
name_ar:
type: string
example: دوام كامل
name_en:
type: string
example: Full Time
full_name_ar:
type: string
example: فينو جورج
full_name_en:
type: string
example: Veenu George
gender:
type: string
example: Male
id:
type: string
example: bab6cd98-7246-4cfc-a576-19bc00391792
is_active:
type: boolean
example: true
is_invited:
type: boolean
example: true
job_title:
type: object
properties:
id:
type: number
example: 14330
name_ar:
type: string
example: Salesman
name_en:
type: string
example: Salesman
joining_date:
type: string
example: '2017-05-21'
last_active_time:
type: string
example: 23 Jun 2022 12:44 PM
line_manager:
type: object
properties:
id:
type: string
example: 8b5f7e1a-2cd3-4ad0-b9c4-61d93e2ab4cf
name:
type: string
example: Majed Bazibidy
location:
type: object
properties:
address_ar:
type: string
example: CR- Deryah-1
address_en:
type: string
example: CR- Deryah-1
id:
type: number
example: 6589
marital_status:
type: string
example: Single
nationality:
type: object
properties:
id:
type: number
example: 161
name_ar:
type: string
example: سنغافوري
name_en:
type: string
example: Singaporean
passport_number:
type: string
example: '1234567897'
status:
type: string
example: active
telephone:
type: string
example: '1111111111'
working_experience_period:
type: string
example: 6 Years - 3 Months - 10 Days
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
"/openapi/v1/employees/financial_info":
get:
tags:
- Employees
summary: Show
description: |-
# **Request**
`GET /openapi/v1/employees/financial_info`
This API endpoint retrieves financial info of specific employee
The request includes the following:
### HEADERS
| name | **Required** | description | **Type** | **Example** | **default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| api-version | Yes | Supported API version s | Integer | 1 | | currently supported is 1 only |
| Slug | Yes | Organization slug name | String | abcd | | |
| Access-Token | Yes | Used to allow an application to access an API it generated from Session API | String | eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRp
ZmllciI6OTAwMDAxNCwiYXBpX2tleV9pZCI6MSwic291cm
NlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhd
CI6MTY5OTYwMjF4NiwiZXhwIjoxNzAyMTk0Njg2fQ.upSy
VVcRrBe2SNUvjnAlDq7NO-N_tenPnGF6zNs1KZU | | |
| source | No | the source type of Open Api | String | open_api | open_api | Supported values:
\- open_api
\- external_aggregator |
| username | Conditional:
if the source type: external_aggregator | the name of the external service | String | workable | | |
#### Query Parameters
| **name** | **Required** | **Description** | **Type** | **Example** | **Default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| rpp | No | controll the limit of the shown result per page | Integer | 50 | 100 | Minimum: 1
Maximum: 100 |
| page | No | choose the required page | Integer | 5 | 1 | |
| id | Yes | Unique id of the employee | String | bab6cd98-7246-4cfc-a576-19bc00391792 | | UUID type |
---
# Response
- Success Response
The success response of the API represented as the following:
Plain Text
```
{
"success": true,
"message": null,
"data": {
"employee": {
"id": "bab6cd98-7246-4cfc-a576-19bc00391792",
"code": 165,
"full_name_en": "Veenu George",
"full_name_ar": "فينو جورج",
"gender": "Male",
"marital_status": "Single",
"telephone": "99999999999",
"email": "test@abcd.net",
"personal_email": "veenu.george@gmail.com",
"avatar": "https://abcd-public.s3.me-south-1.amazonaws.com/images/employee.png",
"is_active": true,
"status": "active",
"joining_date": "2017-05-21",
"passport_number": "1111111111",
"line_manager": {
"id": "8b5f7e1a-2cd3-4ad0-b9c4-745734jbhjb",
"name": "Majed Bazibidy"
},
"is_invited": true,
"last_active_time": "23 Jun 2022 12:44 PM",
"working_experience_period": "6 Years - 3 Months - 10 Days",
"created_at": "May 14, 2019",
"address": {
"id": 68799,
"home_address1": "55 West 25th Street",
"home_address2": null,
"home_city": "Minneapolis",
"home_postal_code": null,
"home_country": "Yemen",
"saudi_address1": null,
"saudi_address2": null,
"saudi_city": "mukalla",
"saudi_postal_code": "65432",
"saudi_country": null,
"employee_id": 36826,
"status": "Pending",
"home_po_box": null,
"created_at": "2023-08-29T08:49:11.141Z",
"updated_at": "2023-08-29T09:52:22.285Z",
"building_number": 23456,
"street_name": "first",
"district": "Al-code"
},
"job_title": {
"id": 14330,
"name_en": "Salesman",
"name_ar": "Salesman"
},
"business_unit": {
"id": "c33f90d6-85d8-4f99-baae-d6543bd96ab8",
"name_en": "business-unit-open-api-1",
"name_ar": "business-unit-open-api-1-ar"
},
"department": {
"id": 10171,
"name_en": "Central sales Dep",
"name_ar": "Central sales Dep"
},
"employment_type": {
"id": 78,
"name_en": "Full Time",
"name_ar": "دوام كامل"
},
"location": {
"id": 6589,
"address_en": "CR- Deryah-1",
"address_ar": "CR-Deryah-1"
},
"nationality": {
"id": 161,
"name_en": "Singaporean",
"name_ar": "سنغافوري"
},
"document_number": "1070400252",
"basic_salary": '1.0',
"first_salary_pay_date": "October 31, 2019",
"last_salary_pay_date": null
}
}
}
```
This contain the following:
| **key** | **Description** | **value** |
| --- | --- | --- |
| success | represent the status of the API response | true |
| message | show additional message | null |
| data | show the required data to fetch, and contain basic info for the employee | hash of data |
| Status_code | the status code of the api request | 200 |
---
Pagination:
- `current_page`: The current page of the results.
- `next_page`: The URL of the next page of results, if available.
- `previous_page`: The URL of the previous page of results, if available.
- `total_pages`: The total number of pages.
- `per_page`: The number of results per page.
- `total_entries`: The total number of entries across all pages.
---
### Error Response
The success response of the API represented as the following:
Plain Text
```
{
"success": false,
"error": "error message",
"status_code": 400
}
```
This response contain the following:
| **name** | **Description** | **Value** |
| --- | --- | --- |
| success | represent the status of the API response | false |
| error | represent the error reason acquired during the request | error_messages |
| status_code | the status code of the api requests | error_status_code |
error_messages
| **message** | **Reason** |
| --- | --- |
| Parameter {field_name} is required | The field name is required |
| "value" is not a valid {type} | the value passed is not in valid type |
| invalid api version | invalid `api-version` header passed or api-version header was not passed at all |
| Organization not found with given subdomain | invalid `Slug` header value |
| Permission denied. Please contact your Administrator | `Slug` Header is missing or your organization doesn't support open api feature |
| This call requires login | `Access-Token` is missing or invalid |
| Your account has been logged out. Please, log in again | previously logged out or expired token |
| Your account temporary suspended, please contact account manager | The organization account is suspended |
| Bad credentials | the credentials is not suited on that organization |
| invalid external aggregator | the aggregator name is not valid within that organization |
| Unable to authenticate employee | api-key is not active or valid |
Please note that some of the values for properties may vary in the actual response and should not be considered as fixed values.
parameters:
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: bab6cd98-7246-4cfc-a576-19bc00391792
required: false
responses:
'200':
description: Success Response By External Aggregator
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
employee:
type: object
properties:
address:
type: object
properties:
building_number:
type: number
example: 23456
created_at:
type: string
example: '2023-08-29T08:49:11.141Z'
district:
type: string
example: Al-code
employee_id:
type: number
example: 36826
home_address1:
type: string
example: 55 West 25th Street
home_address2:
type: object
nullable: true
example: 'null'
home_city:
type: string
example: Minneapolis
home_country:
type: string
example: Yemen
home_po_box:
type: object
nullable: true
example: 'null'
home_postal_code:
type: object
nullable: true
example: 'null'
id:
type: number
example: 68799
saudi_address1:
type: object
nullable: true
example: 'null'
saudi_address2:
type: object
nullable: true
example: 'null'
saudi_city:
type: string
example: mukalla
saudi_country:
type: object
nullable: true
example: 'null'
saudi_postal_code:
type: string
example: '65432'
status:
type: string
example: Pending
street_name:
type: string
example: first
updated_at:
type: string
example: '2023-08-29T09:52:22.285Z'
avatar:
type: string
example: https://abcd-public.s3.me-south-1.amazonaws.com/images/employee.png
code:
type: number
example: 165
created_at:
type: string
example: May 14, 2019
business_unit:
type: object
properties:
id:
type: string
example: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en:
type: string
example: business-unit-open-api-1
name_ar:
type: string
example: business-unit-open-api-1-ar
department:
type: object
properties:
id:
type: number
example: 10171
name_ar:
type: string
example: Central sales Dep
name_en:
type: string
example: Central sales Dep
document_number:
type: string
example: '1070400252'
email:
type: string
example: test@abcd.net
personal_email:
type: string
nullable: true
example: ibraheem.personal@gmail.com
employment_type:
type: object
properties:
id:
type: number
example: 78
name_ar:
type: string
example: دوام كامل
name_en:
type: string
example: Full Time
full_name_ar:
type: string
example: فينو جورج
full_name_en:
type: string
example: Veenu George
gender:
type: string
example: Male
id:
type: string
example: bab6cd98-7246-4cfc-a576-19bc00391792
is_active:
type: boolean
example: true
is_invited:
type: boolean
example: true
job_title:
type: object
properties:
id:
type: number
example: 14330
name_ar:
type: string
example: Salesman
name_en:
type: string
example: Salesman
joining_date:
type: string
example: '2017-05-21'
last_active_time:
type: string
example: 23 Jun 2022 12:44 PM
line_manager:
type: object
properties:
id:
type: string
example: 8b5f7e1a-2cd3-4ad0-b9c4-61d93e2ab4cf
name:
type: string
example: Majed Bazibidy
location:
type: object
properties:
address_ar:
type: string
example: CR- Deryah-1
address_en:
type: string
example: CR- Deryah-1
id:
type: number
example: 6589
marital_status:
type: string
example: Single
nationality:
type: object
properties:
id:
type: number
example: 161
name_ar:
type: string
example: سنغافوري
name_en:
type: string
example: Singaporean
passport_number:
type: string
example: '1234567897'
status:
type: string
example: active
telephone:
type: string
example: '1111111111'
working_experience_period:
type: string
example: 6 Years - 3 Months - 10 Days
basic_salary:
type: string
example: '1.0'
first_salary_pay_date:
type: string
example: October 31, 2019
last_salary_pay_date:
nullable: true
type: string
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
"/openapi/v1/employees/accounting_info":
get:
tags:
- Employees
summary: Get All Openapi V1 Employees Accounting_infos
parameters:
- name: id
in: query
schema:
type: string
properties: {}
example: 62521f81-817a-4e2f-b360-b4afe47c6ddc
responses:
'200':
description: The request has succeeded
headers: {}
content:
application/json:
schema:
type: object
examples:
when employee exists with tracking dimension mappings:
value:
success: true
message:
data:
employee:
id: 62521f81-817a-4e2f-b360-b4afe47c6ddc
code: '4321'
full_name_en: Gabriel Prohaska
full_name_ar: Deloise Senger
gender: Male
marital_status: Single
telephone: '0987654321'
email: tillie_hyatt@carter.org
personal_email: gabriel.prohaska@gmail.com
date_of_birth: 1990/04/01
avatar: http://localhost:3000/images/missing.png
is_active: true
status: active
joining_date: 2026/03/25
passport_number:
line_manager:
is_invited: true
last_active_time: Never logged in
working_experience_period: 2 Days
created_at: March 26, 2026
delete_date:
terminate_date:
address:
job_title:
business_unit:
department:
id: 3
name_en: corrupti-3
name_ar: corrupti-3-ar
employment_type:
id: 3
name_en: nostrum-3
name_ar: nostrum-3-ar
location:
id: 3
address_en: c9e04b42-d743-4125-98be-4df5226dfc59-ut-Location
address_ar: c9e04b42-d743-4125-98be-4df5226dfc59-ut-Location-ar
is_deleted: false
nationality:
id: 155
name_en: Saudi
name_ar: سعودي
document_number: '1107082147'
subsidiary_id: cd77fdc1-20b5-4614-b77d-46475f655598
tracking_dimension_mappings:
- tracking_dimension_value_id: df220fbd-3cbc-4251-8183-6fea92162885
allocation: 100
created_at: 2026/03/26
updated_at: 2026/03/26
security:
- org_slug: []
- locale: []
- Access-Token: []
"/openapi/v1/employee_monthly_payables":
get:
tags:
- Finance
summary: List Employee Monthly Payables
description: |-
# **Request**
`GET /openapi/v1/employee_monthly_payables`
This API endpoint retrieves employee monthly payables information for a specific employee and pay period. The pay period start must be the beginning of a month (e.g., 2025-09-01).
**Note:** This API is only available for whitelisted organizations.
### HEADERS
| name | **Required** | description | **Type** | **Example** | **Additional Notes** |
|--------------|--------------|---------------------------------------------|----------|-------------|---------------------|
| api-version | Yes | Supported API version | Integer | 1 | Only 1 is supported |
| Slug | Yes | Organization slug name | String | abcd | |
| Access-Token | Yes | JWT for authentication | String | ... | Generated from Session API |
### Query Parameters
| name | **Required** | Description | **Type** | **Example** | **Additional Notes** |
|-----------------|--------------|---------------------------------------------|----------|-------------|---------------------|
| pay_period_start| Yes | Beginning of month date (YYYY-MM-DD) | Date | 2025-09-01 | Must be first day of month |
| employee_id | Yes | Employee ID (UUID) | String | "550e8400-e29b-41d4-a716-446655440000" | UUID format. Required |
---
# Response
- Success Response
```json
{
"success": true,
"message": null,
"data": {
"employee_id": "550e8400-e29b-41d4-a716-446655440000",
"pay_period_start": "2025-09-01",
"pay_period_end": "2025-09-30",
"net_salary": "5,000.00",
"earnings_total": "6,000.00",
"additions_total": "500.00",
"deductions_total": "1,500.00",
"earnings": {
"total_amount": "6,000.00",
"breakdown": {}
},
"additions": {
"total_amount": "500.00",
"breakdown": {}
},
"deductions": {
"total_amount": "1,500.00",
"breakdown": {}
},
"manual_remarks": []
}
}
```
parameters:
- in: query
name: pay_period_start
required: true
schema:
type: string
format: date
description: Beginning of month date (YYYY-MM-DD). Must be the first day of
the month.
example: '2025-09-01'
- in: query
name: employee_id
required: true
schema:
type: string
format: uuid
description: Employee ID (UUID). Required.
example: 550e8400-e29b-41d4-a716-446655440000
responses:
'200':
description: Employee monthly payables data for the specified employee.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
nullable: true
data:
"$ref": "#/components/schemas/EmployeeMonthlyPayable"
'400':
description: Bad Request - Invalid parameters
'401':
description: Unauthorized
'403':
description: Forbidden - Organization not whitelisted
'404':
description: Payrun not found for the specified period or employee not found
'500':
description: Server error
"/openapi/v1/payroll_transactions":
get:
tags:
- Finance
summary: Payrun Transaction
description: |-
# **Request**
`GET /openapi/v1/payroll_transactions`
This API is used to list all the payroll transactions.
These are supported types:-
- Payrun (regular).
- Final settlements.
- Vacations settlements.
- Out off payroll transactions.
The request includes the following:
### HEADERS
| name | **Required** | description | **Type** | **Example** | **default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| api-version | Yes | Supported API version s | Integer | 1 | | currently supported is 1 only |
| Slug | Yes | Organization slug name | String | abcd | | |
| Access-Token | Yes | Used to allow an application to access an API it generated from Session API | String | eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRp
ZmllciI6OTAwMDAxNCwiYXBpX2tleV9pZCI6MSwic291cm
NlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhd
CI6MTY5OTYwMjF4NiwiZXhwIjoxNzAyMTk0Njg2fQ.upSy
VVcRrBe2SNUvjnAlDq7NO-N_tenPnGF6zNs1KZU | | |
| source | No | the source type of Open Api | String | open_api | open_api | Supported values:
\- open_api
\- external_aggregator |
| username | Conditional:
if the source type: external_aggregator | the name of the external service | String | workable | | |
#### Query Parameters
| **name** | **Required** | **Description** | **Type** | **Example** | **Default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| rpp | No | controll the limit of the shown result per page | Integer | 50 | 100 | Minimum: 1
Maximum: 100 |
| page | No | choose the required page | Integer | 5 | 1 | |
| type | Yes | Types of transactions, must be within these types: \[payrun, final_settlements, vacations_settlements, out_off_payroll_transactions\] | String | | payrun (Regular Payroll): All transactions that are given to the employee inside the regular payroll.
final_settlements: All transactions that are given to the employee within the final settlement. The final settlement is the payrun where calculates all the dues whenever there is an employee gets off-boarded. Such as the end-of-service reward, salary till the last working days, and etc...
vacations_settlements: All transactions that are given to the employee within the vacation settlement. The vacation settlement is the payrun where calculates all the dues whenever there is an employee request to get his salary in advance during vacation. Such as working days salary, vacation days salary, overtime, etc...
out_off_payroll_transactions: All transactions that are given to the employee outside the regular payroll. | |
| pay_period | conditinal:
Requeired if type: payrun only | 1st day of a confirmed month | Date | 2022-03-01 | | |
| paygroup_id | conditinal:
Required if type: payrun only | paygroup identifier | string | 56f6e9cc-0d45-4133-b23b-aeaf2b8e6992 | | |
| from | conditinal:
Required if type: final_settlements, vacations_settlements, or out_off_payroll_transactions | Start date for filtering | Date | 2022-03-01 | | |
| to | conditinal:
Required if type: final_settlements, vacations_settlements, or out_off_payroll_transactions | End date for filtering | Date | 2022-03-31 | | |
| transaction_type_ids | No | filter by array of payroll transaction within a settlement | Array | \[dfa893d5-284a-4be8-800c-e2287852177a\] | | If this param not found it'll fetch all transactions within that settlement |
| employee_ids | No | filter by array of employee within a settlement | Array | \[409094ee-0775-4695-ba0b-27cbc944c8ec\] | | If this param not found it'll fetch all employees within that settlement |
---
# Response
- Success Response
The success response of the API represented as the following:
Plain Text
```
{
"success": true,
"message": null,
"data": {
"status": "confirmed",
"pay_period": "2022-03-01 - 2022-03-31",
"employees": [
{
"id": "de9df6e2-6a63-4857-b5f5-a69da7abd7da",
"code": 600,
"full_name_en": "Yunes Test",
"full_name_ar": "يونس محمد",
"is_active": true,
"status": "active",
"payment_type": "Bank",
"payment_type_i18n": "Bank",
"business_unit": {
"name": "North",
"name_i18n": "North"
},
"grade": {
"name": "Grade 1",
"name_i18n": "Grade 1"
},
"country": null,
"gosi_info": {
"name_i18n": "Al-qaten",
"gosi_number": "2021"
},
"transactions": [
{
"paid_at": "2022-04-12T14:57:00.000Z",
"transaction_type": {
"id": "91b36e78-189d-480e-a425-1a90aac60dc4",
"name": "Fees",
"name_i18n": "Fees",
"category": "PayrunElement"
},
"amount": "1000.0",
"is_retro": false,
"status": "paid",
"include_in_payrun": true,
"effective_date": "2022-03-01",
"pay_type": "in_payrun",
"pay_type_i18n": "In-payroll",
"source_type": null
}
]
}
],
"employee_count": 197
}
}
```
This contain the following:
| **key** | **Description** | **value** |
| --- | --- | --- |
| success | represent the status of the API response | true |
| message | show additional message | null |
| data | show the required data to fetch, and cotaining information about the regular payroll settlement transaction | hash of data |
| Status_code | the status code of the api request | 200 |
data description:
- `id`: The unique identifier of a GL Transaction Type.
- `status`: the status of that settlement
- `pay_period`: The name of The GL Transaction Type, unique within each category.
- `employees`: contain list of employees for that settlement.
- `employee_count`: Employee count within that settlement.
Note:
Out of payroll as different structure like below, excluding status and pay_period fields
Plain Text
```
{
"success": true,
"message": null,
"data": [
{
"id": "d50445b7-9c84-4d6f-97be-9a27d343695f",
"code": 10,
"full_name_en": "Employee Ten",
"full_name_ar": "الموظف العاشر",
"is_active": false,
"status": "inactive",
"payment_type": "Bank",
"payment_type_i18n": "Bank",
"business_unit": null,
"grade": {
"name": "Grade 2",
"name_i18n": "Grade 2"
},
"country": null,
"gosi_info": {
"name_i18n": "Bingazy CRr",
"gosi_number": "345345345345345"
},
"transactions": [
{
"paid_at": null,
"transaction_type": {
"id": "b24a6f61-6afe-473c-9d7a-6166e8cec88f",
"name": "Urgent",
"name_i18n": "Urgent",
"category": "LoanType"
},
"amount": "10000.0",
"is_retro": null,
"status": "paid",
"include_in_payrun": false,
"effective_date": "2021-04-01",
"pay_type": "out_of_payrun",
"pay_type_i18n": "Out-payoll",
"source_type": null
}
]
}
]
}
```
---
Pagination:
- `current_page`: The current page of the results.
- `next_page`: The URL of the next page of results, if available.
- `previous_page`: The URL of the previous page of results, if available.
- `total_pages`: The total number of pages.
- `per_page`: The number of results per page.
- `total_entries`: The total number of entries across all pages.
---
### Error Response
The success response of the API represented as the following:
Plain Text
```
{
"success": false,
"error": "error message",
"status_code": 400
}
```
This response contain the following:
| **name** | **Description** | **Value** |
| --- | --- | --- |
| success | represent the status of the API response | false |
| error | represent the error reason acquired during the request | error_messages |
| status_code | the status code of the api requests | error_status_code |
error_messages
| **message** | **Reason** |
| --- | --- |
| Parameter {field_name} is required | The field name is required |
| "value" is not a valid {type} | the value passed is not in valid type |
| invalid api version | invalid `api-version` header passed or api-version header was not passed at all |
| Organization not found with given subdomain | invalid `Slug` header value |
| Permission denied. Please contact your Administrator | `Slug` Header is missing or your organization doesn't support open api feature |
| This call requires login | `Access-Token` is missing or invalid |
| Your account has been logged out. Please, log in again | previously logged out or expired token |
| Your account temporary suspended, please contact account manager | The organization account is suspended |
| Bad credentials | the credentials is not suited on that organization |
| invalid external aggregator | the aggregator name is not valid within that organization |
| Unable to authenticate employee | api-key is not active or valid |
Please note that the provided values for properties may vary in the actual response and should not be considered as fixed values.
operationId: payrunTransaction
parameters:
- name: type
in: query
description: 'Required. valid types are: [payrun, final_settlements, vacations_settlements,
out_off_payroll_transactions]'
schema:
type: string
- name: pay_period
in: query
description: Required if type is 'payrun', 1st day of a confirmed month.
schema:
type: string
- name: paygroup_id
in: query
description: Required if type is 'payrun', paygroup identifier.
schema:
type: string
- name: from
in: query
description: Required if type is 'final_settlements', 'vacations_settlements',
or 'out_off_payroll_transactions'. Start date for filtering.
schema:
type: string
format: date
- name: to
in: query
description: Required if type is 'final_settlements', 'vacations_settlements',
or 'out_off_payroll_transactions'. End date for filtering.
schema:
type: string
format: date
- name: page
in: query
description: Pagination
schema:
type: string
- name: rpp
in: query
description: Pagination (no. of records per page. Default is 100)
schema:
type: string
- name: transaction_type_ids[]
in: query
description: Filter by an array of transaction_type_ids
schema:
type: string
- name: employee_ids[]
in: query
description: Filter by an array of employee_ids
schema:
type: string
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
employee_count:
type: number
example: 197
employees:
type: array
example:
- business_unit:
name: North
name_i18n: North
code: 600
country:
full_name_ar: يونس محمد
full_name_en: Yunes Test
gosi_info:
gosi_number: '2021'
name_i18n: Al-qaten
grade:
name: Grade 1
name_i18n: Grade 1
id: de9df6e2-6a63-4857-b5f5-a69da7abd7da
is_active: true
payment_type: Bank
payment_type_i18n: Bank
status: active
transactions:
- amount: '1000.0'
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type:
status: paid
transaction_type:
category: PayrunElement
id: 91b36e78-189d-480e-a425-1a90aac60dc4
name: Fees
name_i18n: Fees
- amount: '500.0'
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type: pay_period_days
status: paid
transaction_type:
category: EarningType
id: 6e27a549-968a-4d74-886c-600e69e53ea0
name: sara
name_i18n: sara
- amount: "-500.0"
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type:
status: paid
transaction_type:
category: LoanType
id: 6f697714-1891-44f7-9880-17ac3bd54c14
name: Personal
name_i18n: Personal
- amount: '2000.0'
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type: pay_period_days
status: paid
transaction_type:
category: EarningType
id: 51303f42-fb18-41c3-b434-cd50681077e0
name: Car onee
name_i18n: Car onee
- amount: '2000.0'
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type: pay_period_days
status: paid
transaction_type:
category: EarningType
id: 1049c1eb-18d8-4fd6-b483-b873d50cb67d
name: Health Insurance
name_i18n: Health Insurance
- amount: '20000.0'
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type: pay_period_days
status: paid
transaction_type:
category: EarningType
id: 409094ee-0775-4695-ba0b-27cbc944c8ec
name: Salary
name_i18n: Salary
- amount: "-123.0"
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type:
status: paid
transaction_type:
category: LoanType
id: 9fd1ebd9-e9a9-41e6-9233-16dadfae52d2
name: Housing
name_i18n: Housing
- amount: "-500.0"
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type:
status: paid
transaction_type:
category: LoanType
id: 6f697714-1891-44f7-9880-17ac3bd54c14
name: Personal
name_i18n: Personal
- amount: "-500.0"
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type:
status: paid
transaction_type:
category: LoanType
id: 6f697714-1891-44f7-9880-17ac3bd54c14
name: Personal
name_i18n: Personal
items:
type: object
properties:
business_unit:
type: object
properties:
name:
type: string
example: North
name_i18n:
type: string
example: North
code:
type: number
example: 600
country:
type: object
nullable: true
example: 'null'
full_name_ar:
type: string
example: يونس محمد
full_name_en:
type: string
example: Yunes Test
gosi_info:
type: object
properties:
gosi_number:
type: string
example: '2021'
name_i18n:
type: string
example: Al-qaten
grade:
type: object
properties:
name:
type: string
example: Grade 1
name_i18n:
type: string
example: Grade 1
id:
type: string
example: de9df6e2-6a63-4857-b5f5-a69da7abd7da
is_active:
type: boolean
example: true
payment_type:
type: string
example: Bank
payment_type_i18n:
type: string
example: Bank
status:
type: string
example: active
transactions:
type: array
example:
- amount: '1000.0'
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type:
status: paid
transaction_type:
category: PayrunElement
id: 91b36e78-189d-480e-a425-1a90aac60dc4
name: Fees
name_i18n: Fees
- amount: '500.0'
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type: pay_period_days
status: paid
transaction_type:
category: EarningType
id: 6e27a549-968a-4d74-886c-600e69e53ea0
name: sara
name_i18n: sara
- amount: "-500.0"
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type:
status: paid
transaction_type:
category: LoanType
id: 6f697714-1891-44f7-9880-17ac3bd54c14
name: Personal
name_i18n: Personal
- amount: '2000.0'
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type: pay_period_days
status: paid
transaction_type:
category: EarningType
id: 51303f42-fb18-41c3-b434-cd50681077e0
name: Car onee
name_i18n: Car onee
- amount: '2000.0'
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type: pay_period_days
status: paid
transaction_type:
category: EarningType
id: 1049c1eb-18d8-4fd6-b483-b873d50cb67d
name: Health Insurance
name_i18n: Health Insurance
- amount: '20000.0'
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type: pay_period_days
status: paid
transaction_type:
category: EarningType
id: 409094ee-0775-4695-ba0b-27cbc944c8ec
name: Salary
name_i18n: Salary
- amount: "-123.0"
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type:
status: paid
transaction_type:
category: LoanType
id: 9fd1ebd9-e9a9-41e6-9233-16dadfae52d2
name: Housing
name_i18n: Housing
- amount: "-500.0"
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type:
status: paid
transaction_type:
category: LoanType
id: 6f697714-1891-44f7-9880-17ac3bd54c14
name: Personal
name_i18n: Personal
- amount: "-500.0"
effective_date: '2022-03-01'
include_in_payrun: true
is_retro: false
paid_at: '2022-04-12T14:57:00.000Z'
pay_type: in_payrun
pay_type_i18n: In-payroll
source_type:
status: paid
transaction_type:
category: LoanType
id: 6f697714-1891-44f7-9880-17ac3bd54c14
name: Personal
name_i18n: Personal
items:
type: object
properties:
amount:
type: string
example: '1000.0'
effective_date:
type: string
example: '2022-03-01'
include_in_payrun:
type: boolean
example: true
is_retro:
type: boolean
example: false
paid_at:
type: string
example: '2022-04-12T14:57:00.000Z'
pay_type:
type: string
example: in_payrun
pay_type_i18n:
type: string
example: In-payroll
source_type:
type: string
nullable: true
example: 'null'
status:
type: string
example: paid
transaction_type:
type: object
properties:
category:
type: string
example: PayrunElement
id:
type: string
example: 91b36e78-189d-480e-a425-1a90aac60dc4
name:
type: string
example: Fees
name_i18n:
type: string
example: Fees
pay_period:
type: string
example: 2022-03-01 - 2022-03-31
status:
type: string
example: confirmed
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
"/openapi/v1/payroll_transactions/{id}":
delete:
tags:
- Finance
summary: Delete Payroll Transaction
description: |-
# **Request**
`DELETE /openapi/v1/payroll_transactions/:id`
This API endpoint deletes a payroll transaction. Only transactions with status "initiated" can be deleted.
**Note:** This API is only available for whitelisted organizations.
### HEADERS
| name | **Required** | description | **Type** | **Example** | **Additional Notes** |
|--------------|--------------|---------------------------------------------|----------|-------------|---------------------|
| api-version | Yes | Supported API version | Integer | 1 | Only 1 is supported |
| Slug | Yes | Organization slug name | String | abcd | |
| Access-Token | Yes | JWT for authentication | String | ... | Generated from Session API |
### Path Parameters
| name | **Required** | Description | **Type** | **Example** |
|------|--------------|---------------------------------------------|----------|-------------|
| id | Yes | Payroll transaction ID (UUID) | String | "550e8400-e29b-41d4-a716-446655440000" | UUID format |
parameters:
- in: path
name: id
required: true
schema:
type: string
format: uuid
description: Payroll transaction ID (UUID)
example: 550e8400-e29b-41d4-a716-446655440000
responses:
'200':
description: Payroll transaction deleted successfully.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
nullable: true
data:
type: object
properties:
message:
type: string
example: Transaction deleted successfully
'400':
description: Bad Request - Invalid parameters
'401':
description: Unauthorized
'403':
description: Forbidden - Organization not whitelisted or transaction cannot
be deleted
'404':
description: Transaction not found
'422':
description: Unprocessable Entity - Transaction cannot be deleted (not in
initiated status)
'500':
description: Server error
"/openapi/v1/gl_transaction_types":
get:
tags:
- Finance
summary: GL Transaction Types
description: |-
# **Request**
`GET /openapi/v1/gl_transaction_types`
This API endpoint retrieves all the GL transaction Types within the organization.
The request includes the following:
### HEADERS
| name | **Required** | description | **Type** | **Example** | **default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| api-version | Yes | Supported API version s | Integer | 1 | | currently supported is 1 only |
| Slug | Yes | Organization slug name | String | abcd | | |
| Access-Token | Yes | Used to allow an application to access an API it generated from Session API | String | eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRp
ZmllciI6OTAwMDAxNCwiYXBpX2tleV9pZCI6MSwic291cm
NlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhd
CI6MTY5OTYwMjF4NiwiZXhwIjoxNzAyMTk0Njg2fQ.upSy
VVcRrBe2SNUvjnAlDq7NO-N_tenPnGF6zNs1KZU | | |
| source | No | the source type of Open Api | String | open_api | open_api | Supported values:
\- open_api
\- external_aggregator |
| username | Conditional:
if the source type: external_aggregator | the name of the external service | String | workable | | |
#### Query Parameters
| **name** | **Required** | **Description** | **Type** | **Example** | **Default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| rpp | No | control the limit of the shown result per page | Integer | 50 | 100 | Minimum: 1
Maximum: 100 |
| page | No | choose the required page | Integer | 5 | 1 | |
---
# Response
- Success Response
The success response of the API represented as the following:
Plain Text
```
{
"success": true,
"message": null,
"data": {
"gl_transaction_types": [
{
"id": "894a529b-0953-4db8-b10e-02b4b5a4b600",
"gl_transaction_category": "Loan Types",
"gl_transaction_name": "ss",
"gl_transaction_name_ar": "ss",
"status": "inactive"
},
{
"id": "730b31e5-620e-414f-876f-c508a5c101a7",
"gl_transaction_category": "Allowances",
"gl_transaction_name": "er",
"gl_transaction_name_ar": "er",
"status": "active"
}
],
"pagination": {
"current_page": 1,
"next_page": 2,
"previous_page": null,
"total_pages": 2,
"per_page": 100,
"total_entries": 146
}
}
}
```
This contain the following:
| **key** | **Description** | **value** |
| --- | --- | --- |
| success | represent the status of the API response | true |
| message | show additional message | null |
| data | show the required data to fetch, and contain two values type:
\+ gl_transaction_types: contain array of all available gl transaction types
pagination: contain additional field to navigate data through the api | hash of data |
| Status_code | the status code of the api request | 200 |
GL Transaction Types description:
- `id`: The unique identifier of a GL Transaction Type.
- `gl_transaction_category`: The category the transaction type belongs to
- `gl_transaction_name`: The name of The GL Transaction Type, unique within each category.
- `gl_transaction_name_ar`: The arabic name for GL Transaction type.
- `status`: The status of the GL Transaction Type, must be within two possibilities \[active, inactive\].
---
Pagination:
- `current_page`: The current page of the results.
- `next_page`: The URL of the next page of results, if available.
- `previous_page`: The URL of the previous page of results, if available.
- `total_pages`: The total number of pages.
- `per_page`: The number of results per page.
- `total_entries`: The total number of entries across all pages.
---
### Error Response
The success response of the API represented as the following:
Plain Text
```
{
"success": false,
"error": "error message",
"status_code": 400
}
```
This response contain the following:
| **name** | **Description** | **Value** |
| --- | --- | --- |
| success | represent the status of the API response | false |
| error | represent the error reason acquired during the request | error_messages |
| status_code | the status code of the api requests | error_status_code |
error_messages
| **message** | **Reason** |
| --- | --- |
| Parameter {field_name} is required | The field name is required |
| "value" is not a valid {type} | the value passed is not in valid type |
| invalid api version | invalid `api-version` header passed or api-version header was not passed at all |
| Organization not found with given subdomain | invalid `Slug` header value |
| Permission denied. Please contact your Administrator | `Slug` Header is missing or your organization doesn't support open api feature |
| This call requires login | `Access-Token` is missing or invalid |
| Your account has been logged out. Please, log in again | previously logged out or expired token |
| Your account temporary suspended, please contact account manager | The organization account is suspended |
| Bad credentials | the credentials is not suited on that organization |
| invalid external aggregator | the aggregator name is not valid within that organization |
| Unable to authenticate employee | api-key is not active or valid |
Please note that the values for properties like `id`, `gl_transaction_category`, `gl_transaction_name`, `gl_transaction_name_ar`, and `status` may vary in the actual response and should not be considered as fixed values.
operationId: glTransactionTypes
parameters:
- name: page
in: query
description: Pagination
schema:
type: string
- name: rpp
in: query
description: Pagination (no. of records per page. Default is 100)
schema:
type: string
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
gl_transaction_types:
type: array
example:
- gl_transaction_category: Loan Types
gl_transaction_name: ss
gl_transaction_name_ar: ss
id: 894a529b-0953-4db8-b10e-02b4b5a4b600
status: inactive
- gl_transaction_category: Allowances
gl_transaction_name: er
gl_transaction_name_ar: " er"
id: 730b31e5-620e-414f-876f-c508a5c101a7
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: hhhnan
gl_transaction_name_ar: ههههنااان
id: 940b00fa-c930-4e96-bdb7-e47675665ab0
status: active
- gl_transaction_category: Allowances
gl_transaction_name: s1
gl_transaction_name_ar: s1
id: 2c5c1822-99bb-436d-b059-fcca344cd192
status: active
- gl_transaction_category: Allowances
gl_transaction_name: en asdf
gl_transaction_name_ar: asdf ar
id: 63d18415-a45e-4198-8c5c-7d787ced29d1
status: active
- gl_transaction_category: Allowances
gl_transaction_name: Basic Salary
gl_transaction_name_ar: الراتب الاساسي
id: 409094ee-0775-4695-ba0b-27cbc944c8ec
status: active
- gl_transaction_category: Allowances
gl_transaction_name: Housing
gl_transaction_name_ar: بدل سكن
id: 18867082-5a76-492a-9378-1a4eba23f2ca
status: active
- gl_transaction_category: Allowances
gl_transaction_name: Transportation
gl_transaction_name_ar: بدل مواصلات
id: 77d13c3a-6859-41d9-94be-fb968d8cd1ee
status: active
- gl_transaction_category: Allowances
gl_transaction_name: Mobile
gl_transaction_name_ar: بدل اتصالات
id: 9bf7604f-aee1-40bb-b1fe-7104b01dacae
status: active
- gl_transaction_category: Allowances
gl_transaction_name: Food
gl_transaction_name_ar: بدل إعاشة
id: c8104ac0-42a8-4b43-9863-1fc2d1790551
status: active
- gl_transaction_category: Allowances
gl_transaction_name: Bonus
gl_transaction_name_ar: علاوة
id: 8eaa67dd-7076-4af6-9bb7-b83066b7e33c
status: active
- gl_transaction_category: Allowances
gl_transaction_name: Health Insurance
gl_transaction_name_ar: تأمين صحي
id: 1049c1eb-18d8-4fd6-b483-b873d50cb67d
status: active
- gl_transaction_category: Allowances
gl_transaction_name: Others
gl_transaction_name_ar: أخرى
id: 35ba84a6-c6f4-4383-b1c4-7fe3978ddae9
status: active
- gl_transaction_category: Allowances
gl_transaction_name: 'outsourcing benifit '
gl_transaction_name_ar: outsourcing benifit
id: fc205e5f-d8b6-4f58-aa8c-02a04e34e5aa
status: active
- gl_transaction_category: Allowances
gl_transaction_name: hi
gl_transaction_name_ar: hi
id: f1eabe3c-7507-4b70-940e-3fbebf0d8b09
status: active
- gl_transaction_category: Allowances
gl_transaction_name: hi2
gl_transaction_name_ar: hi2
id: cbd919a6-8a12-4d18-9a6d-96eeb88bf952
status: active
- gl_transaction_category: Allowances
gl_transaction_name: hi3
gl_transaction_name_ar: hi3
id: '00663955-9a6d-460e-be40-968561970263'
status: active
- gl_transaction_category: Allowances
gl_transaction_name: TE/ST
gl_transaction_name_ar: تست
id: 9659d92c-b50d-4b9b-9f6c-fdd012a978e8
status: active
- gl_transaction_category: Allowances
gl_transaction_name: علاوة إشراف
gl_transaction_name_ar: علاوةإشراف
id: fe2c2c0a-ca14-4822-907b-0364532d0fa2
status: active
- gl_transaction_category: Allowances
gl_transaction_name: بدل طبيعة عمل
gl_transaction_name_ar: بدل طبيعة عمل
id: ce2b2ff1-1048-4260-97a8-647c7a5a1eb9
status: active
- gl_transaction_category: Allowances
gl_transaction_name: T/A
gl_transaction_name_ar: T/A
id: ee759e47-f1aa-43b7-bee6-e5711896475e
status: active
- gl_transaction_category: Allowances
gl_transaction_name: " maged/fgfg"
gl_transaction_name_ar: " "
id: 135ce5fd-db97-4f60-ac51-17aafe5afd69
status: active
- gl_transaction_category: Allowances
gl_transaction_name: Replacement of lost
gl_transaction_name_ar: Replacement of lost
id: 93ddfe64-4049-4ad6-836c-16cae2e9e32c
status: active
- gl_transaction_category: Allowances
gl_transaction_name: salem
gl_transaction_name_ar: سالم
id: ef28cc29-b230-4c84-be32-5fac6f2d4b58
status: active
- gl_transaction_category: Allowances
gl_transaction_name: Car onee
gl_transaction_name_ar: مؤسسة جزر المعرفه لتقنية المعلومات
id: 51303f42-fb18-41c3-b434-cd50681077e0
status: active
- gl_transaction_category: Allowances
gl_transaction_name: sara
gl_transaction_name_ar: sara
id: 6e27a549-968a-4d74-886c-600e69e53ea0
status: active
- gl_transaction_category: Allowances
gl_transaction_name: ss
gl_transaction_name_ar: ss
id: fd3ba313-a4d1-4f16-b553-e93117a85d71
status: active
- gl_transaction_category: Absenteeism transactions
gl_transaction_name: Late Arrival
gl_transaction_name_ar: تاخير
id: 63feb366-d97a-4bdd-8c5f-cfbe8686c4ef
status: active
- gl_transaction_category: Absenteeism transactions
gl_transaction_name: Early Departure
gl_transaction_name_ar: خروج مبكر
id: fff8bbb0-826c-413b-9a85-c021eec8e9b1
status: active
- gl_transaction_category: Absenteeism transactions
gl_transaction_name: Absence
gl_transaction_name_ar: غياب
id: 758a8c72-0f04-48ec-8420-1741e24254eb
status: active
- gl_transaction_category: Absenteeism transactions
gl_transaction_name: Missing Punch
gl_transaction_name_ar: نسيان بصمه
id: 8a0965bf-f9f2-4bcf-9f2e-4cf1ade1c959
status: active
- gl_transaction_category: Absenteeism transactions
gl_transaction_name: Unpaid Leave
gl_transaction_name_ar: اجازة غير مدفوعة
id: ea0c3e9c-a0f5-4bea-9c1d-cfe7c604ad5e
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: Overtime
gl_transaction_name_ar: وقت اضافي
id: 9667cd04-e3aa-4db5-a20d-51e00861d1ef
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: Urgent Loan
gl_transaction_name_ar: طلب سلفة
id: 31c7c446-1c21-4e89-bac0-ed1c7693e346
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: Expense Claim
gl_transaction_name_ar: مطالبة مالية
id: d12efdcf-35f1-45ff-809d-f40bb3f1dd15
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: TEST
gl_transaction_name_ar: تست
id: bac1a1ac-f0a6-4525-bb70-b41a438efe5e
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: abcd
gl_transaction_name_ar: أ ب ج
id: 48ce735f-fc07-4591-815f-2b789b57fdca
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: ahmed aljohi
gl_transaction_name_ar: '455'
id: 5010f07d-e08e-4037-8c1b-ffe941a52446
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: ahmed
gl_transaction_name_ar: ahmde
id: d21ebfaa-7f8f-42a0-91bf-858e65263cc5
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: just like that
gl_transaction_name_ar: بارادم
id: 1bcbebe4-da8b-4433-8d33-8830950abf02
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: Test 40
gl_transaction_name_ar: مؤسسة جزر المعرفه لتقنية المعلومات
id: be618726-499e-436a-89c0-8baaf2bde1df
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: from me
gl_transaction_name_ar: 'من عندي '
id: 116c3328-f2ed-4a29-a1c9-e7a966cd197c
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: test sync
gl_transaction_name_ar: test sync ar
id: 8e962440-5a01-45d7-a262-42dc0905c4bf
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: Course Material 232323
gl_transaction_name_ar: rtyrty12
id: 4d646c09-16ac-4fff-8cb2-d65726a85d35
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: Default202020
gl_transaction_name_ar: Default202020
id: 6e4573a2-ecc5-4e81-a4c3-587aa434e1cf
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: fgsfg
gl_transaction_name_ar: dfsdf
id: d9d7ecbe-0b4e-4b20-a3da-4fd76baa1a2a
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: HASSAN
gl_transaction_name_ar: hassan
id: a388849c-392f-4ba8-8700-c393096ecc61
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: helllo dd
gl_transaction_name_ar: " dd"
id: ee6cc9ab-84da-4a36-a69d-bf3733de7271
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: helllo ddv
gl_transaction_name_ar: vvv
id: 7946486b-55b2-44da-9995-d0a3b084102e
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: Just test
gl_transaction_name_ar: اختبار فقط
id: 0a6e94db-1ca6-4f4e-854c-cb327af3ec87
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: 'Course Material '
gl_transaction_name_ar: '12'
id: 9eeb3e3e-def2-4407-b4cc-37a0f013d1be
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: test 41
gl_transaction_name_ar: تست
id: a51dc7df-5a0f-41bd-a2d1-53b31f1de47b
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: test3
gl_transaction_name_ar: test3
id: f66d0841-4e9f-4cd2-93a1-9e6082bf9040
status: active
- gl_transaction_category: Accruals
gl_transaction_name: Vacation Accrual
gl_transaction_name_ar: مخصص الإجازة
id: 9469d4e9-e5d9-4d31-b5a1-e9a6fa01eb4a
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: AbuJaber
gl_transaction_name_ar: ابوجابر
id: 9cd321d3-e65d-485d-8ae5-e2b8908d2444
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: Hassan Bahliwah
gl_transaction_name_ar: حسان
id: 4eb914aa-8f03-4fcf-b659-a18c32797c55
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: test 33
gl_transaction_name_ar: test 33 ar
id: b0523673-aea1-4cda-9281-468dfa4ad048
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: Default23
gl_transaction_name_ar: Default 199
id: 1bc726f5-468e-47d4-9c0b-7a342c84260f
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: Business Trip
gl_transaction_name_ar: رحلة عمل
id: e775833d-b428-46a7-bda4-04e4ecdd3b15
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: '123'
gl_transaction_name_ar: '123'
id: '023458f6-9e65-4863-8e3e-80a019e20cd7'
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: ss
gl_transaction_name_ar: ss
id: 18f8701c-e382-44cc-8f9c-e478f2be3059
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: Fees
gl_transaction_name_ar: رسوم
id: 91b36e78-189d-480e-a425-1a90aac60dc4
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: pully
gl_transaction_name_ar: بطرة
id: 58a5663d-7992-49ba-ba32-7ef205dfc009
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: as
gl_transaction_name_ar: as
id: 3e7e20ca-1249-42d4-8cab-5fec47dae5c5
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: '333'
gl_transaction_name_ar: '333'
id: e0a1acf1-ef1e-482e-a318-058acaefd132
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: Pallavi Singh
gl_transaction_name_ar: ps
id: 29d90f46-668b-4665-a2e4-b373b21e3870
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: abcd
gl_transaction_name_ar: جيسر
id: 841b3b98-0426-4290-be67-3d428d73a919
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: Ded
gl_transaction_name_ar: خصم
id: c8b53a97-0688-410d-85f1-ff407a842ad2
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: Ad26102020
gl_transaction_name_ar: Ad26102020q
id: ceefe4c1-39eb-4841-b58a-245f0a9d10c6
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: Default2020
gl_transaction_name_ar: Default2020
id: 804a461a-41a8-4fdb-bbc9-92e67b2437c5
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: Car
gl_transaction_name_ar: مؤسسة جزر المعرفه لتقنية المعلومات
id: 9f2e6f88-623c-4afd-9b1f-46673295092b
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: Abubker
gl_transaction_name_ar: ابوبكر
id: f49b208b-c5b3-47f8-9443-42a5faa58d52
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: hello ddd
gl_transaction_name_ar: ddd
id: 4cff012b-8b71-4ac7-bc78-9eb861910bc9
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: HASSAN7
gl_transaction_name_ar: hh77
id: b8865889-ccc9-4da6-b43a-40cf316afcc5
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: New---deductions
gl_transaction_name_ar: خصومات جديدة---
id: 18c004d7-f1e5-4efe-8913-773b3e3f036d
status: active
- gl_transaction_category: Loan Types
gl_transaction_name: Housing
gl_transaction_name_ar: سكني
id: 9fd1ebd9-e9a9-41e6-9233-16dadfae52d2
status: active
- gl_transaction_category: Loan Types
gl_transaction_name: Personal
gl_transaction_name_ar: شخصي
id: 6f697714-1891-44f7-9880-17ac3bd54c14
status: active
- gl_transaction_category: Loan Types
gl_transaction_name: Urgent
gl_transaction_name_ar: عاجل
id: b24a6f61-6afe-473c-9d7a-6166e8cec88f
status: active
- gl_transaction_category: Loan Types
gl_transaction_name: New-Loan
gl_transaction_name_ar: قرض جديد
id: 15daeb1d-edec-4c56-b0b2-7ea2ce21dcf1
status: active
- gl_transaction_category: Loan Types
gl_transaction_name: mr
gl_transaction_name_ar: rw
id: 3442df25-0de5-44f7-b3c2-40e70fc87f93
status: active
- gl_transaction_category: Loan Types
gl_transaction_name: سيبيس
gl_transaction_name_ar: سيبس
id: bd7ef409-0f5e-44a3-80cc-93cfbb88c389
status: active
- gl_transaction_category: Accruals
gl_transaction_name: Vacation Accrued Expense
gl_transaction_name_ar: مصروف مخصص الإجازة
id: a274beb4-da11-4620-aa23-d6d999529708
status: active
- gl_transaction_category: Accruals
gl_transaction_name: EOS Accrual
gl_transaction_name_ar: مخصص نهاية الخدمة
id: c9905ee8-4c4d-4cdb-9b38-31a3e8ba9017
status: active
- gl_transaction_category: Accruals
gl_transaction_name: Payroll Salary Payable
gl_transaction_name_ar: صافي الراتب المستحق
id: eadc7273-389b-418a-82e2-2d1f4f977417
status: active
- gl_transaction_category: Accruals
gl_transaction_name: GOSI Payable
gl_transaction_name_ar: إجمالي مستحقات التأمينات الإجتماعية
id: 3e71344b-5b1e-4d62-bc8e-78e871db16cf
status: active
- gl_transaction_category: Accruals
gl_transaction_name: GOSI Company Contribution Expense
gl_transaction_name_ar: التأمينات الإجتماعية (نسبة تحمل
الشركة)
id: 5976fdf0-af21-45e7-9619-c84d77ad40f5
status: active
- gl_transaction_category: Other PayTypes
gl_transaction_name: name en
gl_transaction_name_ar: name ar
id: 25532a1b-65e1-4862-aade-24b258c07eb8
status: active
- gl_transaction_category: Loan Types
gl_transaction_name: ddd
gl_transaction_name_ar: sss
id: 3deca0a6-9a70-4f95-8bf1-2be2625b94a7
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: rohan sdf
gl_transaction_name_ar: '24'
id: 7b417b21-b51a-4e44-8208-33528032f2dd
status: active
- gl_transaction_category: Loan Types
gl_transaction_name: New-Loan-Type
gl_transaction_name_ar: قرض جديد
id: a80c2f7c-3be9-4942-9424-7124fd67127b
status: inactive
- gl_transaction_category: Allowances
gl_transaction_name: aaaa
gl_transaction_name_ar: a
id: ccd16c8a-b108-4d95-b019-23b170dc42dc
status: active
- gl_transaction_category: Allowances
gl_transaction_name: aaa
gl_transaction_name_ar: a
id: 340aab26-8ffc-4871-aba0-34dd6afe2045
status: active
- gl_transaction_category: Allowances
gl_transaction_name: aw
gl_transaction_name_ar: a
id: 8b7e4282-3d0d-40ba-8200-6126c5727935
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: s
gl_transaction_name_ar: s
id: 8cff131d-c7d9-4ad1-ad8a-10d6d4038197
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: q
gl_transaction_name_ar: q
id: a78e42b6-7700-433a-a816-3ba6c97a91c3
status: active
- gl_transaction_category: Other Deductions
gl_transaction_name: '1'
gl_transaction_name_ar: '1'
id: e1a07dc7-ceaa-4472-b362-527e59225003
status: active
- gl_transaction_category: Accruals
gl_transaction_name: EOS Accrued Expense
gl_transaction_name_ar: مصروف مخصص نهاية الخدمة
id: 9be9db30-b706-4b27-a85d-6e99b5efdd5f
status: active
- gl_transaction_category: Accruals
gl_transaction_name: GOSI Employee Contribution
gl_transaction_name_ar: التأمينات الإجتماعية (نسبة تحمل
الموظف)
id: 241ada1f-18b0-4b1b-a208-9689c542bb71
status: active
- gl_transaction_category: Loan Types
gl_transaction_name: Loan out
gl_transaction_name_ar: Loan out
id: c866cd65-3da2-4646-adf8-3d263ceabbe0
status: active
- gl_transaction_category: Allowances
gl_transaction_name: ooooooo
gl_transaction_name_ar: oooooo
id: 1382e4e4-1ca2-4cdd-a4b8-be08786efb97
status: inactive
items:
type: object
properties:
gl_transaction_category:
type: string
example: Loan Types
gl_transaction_name:
type: string
example: ss
gl_transaction_name_ar:
type: string
example: ss
id:
type: string
example: 894a529b-0953-4db8-b10e-02b4b5a4b600
status:
type: string
example: inactive
pagination:
type: object
properties:
current_page:
type: number
example: 1
next_page:
type: number
example: 2
per_page:
type: number
example: 100
previous_page:
type: object
nullable: true
example: 'null'
total_entries:
type: number
example: 146
total_pages:
type: number
example: 2
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
"/openapi/v1/paygroups":
get:
tags:
- Finance
summary: List all paygroups for the organization
description: |-
# **Request**
`GET /openapi/v1/paygroups`
This API endpoint retrieves all the paygroups within the organization.
The request includes the following:
### HEADERS
| name | **Required** | description | **Type** | **Example** | **default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| api-version | Yes | Supported API version s | Integer | 1 | | currently supported is 1 only |
| Slug | Yes | Organization slug name | String | abcd | | |
| Access-Token | Yes | Used to allow an application to access an API it generated from Session API | String | eyJhbGciOiJIUzI1NiJ9.eyJvcmdhbml6YXRpb25faWRlbnRp
ZmllciI6OTAwMDAxNCwiYXBpX2tleV9pZCI6MSwic291cm
NlIjoib3Blbl9hcGkiLCJzb3VyY2VfaWQiOm51bGwsImlhd
CI6MTY5OTYwMjF4NiwiZXhwIjoxNzAyMTk0Njg2fQ.upSy
VVcRrBe2SNUvjnAlDq7NO-N_tenPnGF6zNs1KZU | | |
| source | No | the source type of Open Api | String | open_api | open_api | Supported values:
\- open_api
\- external_aggregator |
| username | Conditional:
if the source type: external_aggregator | the name of the external service | String | workable | | |
#### Query Parameters
| **name** | **Required** | **Description** | **Type** | **Example** | **Default** | **Additional Notes** |
| --- | --- | --- | --- | --- | --- | --- |
| rpp | No | Control the limit of the shown result per page | Integer | 50 | 100 | Minimum: 1
Maximum: 100 |
| page | No | Choose the required page | Integer | 5 | 1 | |
---
# Response
- Success Response
The success response of the API represented as the following:
Plain Text
```
{
"success": true,
"message": null,
"data": {
"paygroups": [
{
"id": "56f6e9cc-0d45-4133-b23b-aeaf2b8e6992",
"name": "default"
},
{
"id": "69360df7-1b9f-4144-9e1c-8b05f1bfc1eb",
"name": "Pallavi"
},
{
"id": "b02aadff-bfd4-4a78-979e-3115fdc05126",
"name": "ammar"
},
{
"id": "2fb72457-4d35-4ca8-b67c-e3e67dc529d3",
"name": "Abubker"
},
{
"id": "86298de6-9112-4445-b6cf-88b1a288d2c7",
"name": "Mohammed"
},
{
"id": "f6224234-2c81-4326-ad22-e46d94da8ac0",
"name": "Salah"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"previous_page": null,
"total_pages": 1,
"per_page": 100,
"total_entries": 6
}
}
}
```
This contains the following:
| **key** | **Description** | **value** |
| --- | --- | --- |
| success | Represent the status of the API response | true |
| message | Show additional message | null |
| data | Show the required data to fetch, and contain two values type:
+ paygroups: contain array of all available paygroups
pagination: contain additional field to navigate data through the API | hash of data |
| Status_code | The status code of the API request | 200 |
---
Pagination:
- `current_page`: The current page of the results.
- `next_page`: The URL of the next page of results, if available.
- `previous_page`: The URL of the previous page of results, if available.
- `total_pages`: The total number of pages.
- `per_page`: The number of results per page.
- `total_entries`: The total number of entries across all pages.
operationId: listPaygroups
parameters:
- name: page
in: query
description: Pagination
schema:
type: string
- name: rpp
in: query
description: Pagination (no. of records per page. Default is 100)
schema:
type: string
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
paygroups:
type: array
example:
- id: 56f6e9cc-0d45-4133-b23b-aeaf2b8e6992
name: default
- id: 69360df7-1b9f-4144-9e1c-8b05f1bfc1eb
name: Pallavi
- id: b02aadff-bfd4-4a78-979e-3115fdc05126
name: ammar
- id: 2fb72457-4d35-4ca8-b67c-e3e67dc529d3
name: Abubker
- id: 86298de6-9112-4445-b6cf-88b1a288d2c7
name: Mohammed
- id: f6224234-2c81-4326-ad22-e46d94da8ac0
name: Salah
pagination:
type: object
properties:
current_page:
type: number
example: 1
next_page:
type: object
nullable: true
example: 'null'
previous_page:
type: object
nullable: true
example: 'null'
total_pages:
type: number
example: 1
per_page:
type: number
example: 100
total_entries:
type: number
example: 6
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
"/openapi/v1/accounting/journals":
post:
tags:
- Finance
summary: Create Journal Export Request
description: |
Creates an asynchronous journal **export job**. Poll the returned `id` with
`GET /openapi/v1/accounting/journals/{id}` until `status` is terminal.
### Where is the request payload?
In Swagger UI, scroll to **Request body** (not **Parameters**). Content type is
**`multipart/form-data`** — each field below is a form field (not JSON).
Required headers are listed under **Parameters** (`api-version`, `Access-Token`, and `slug` header or query).
### Request body examples
| Example | Purpose |
| --- | --- |
| **request_full_reference_regular** | **Full reference** for the most common case (`journal_type=regular`). Copy this for integration. |
| **request_full_reference_out_of_payroll** | **Full reference** when `journal_type=out_of_payroll` (includes `pay_period_to`, optional `transaction_ids`). |
| **journal_type_*** | Same fields as the references, one row per `journal_type` value. |
| **journal_type_vacation_settlement** / **journal_type_end_of_service** | Valid enum values but **rejected** by Open API (expect HTTP 400). |
| **invalidParams** | Legacy invalid-date case (400). |
operationId: createJournalExportRequest
parameters:
- name: slug
in: header
description: Organization slug. Required unless `slug` is sent as a query
parameter or in the form body.
schema:
type: string
example: global_testing_organization
- name: slug
in: query
required: false
description: Organization slug (alternative to header).
schema:
type: string
example: global_testing_organization
- name: api-version
in: header
description: Supported API version, currently 1 only
required: true
schema:
type: string
enum:
- '1'
- name: Access-Token
in: header
required: true
schema:
type: string
requestBody:
required: true
description: |
**Multipart form fields** for the export job. Open the **Schema** tab for field types and enums,
or the **Examples** dropdown for ready-to-send payloads.
content:
multipart/form-data:
schema:
"$ref": "#/components/schemas/JournalExportCreateRequest"
examples:
request_full_reference_regular:
summary: "[Full reference] regular payroll export (default integration
payload)"
description: |
Use this example for Hyundai integration — all required fields for `journal_type=regular`.
`slug` may be omitted here if you pass it as query/header (see Parameters).
value:
journal_type: regular
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
request_full_reference_out_of_payroll:
summary: "[Full reference] out_of_payroll export"
description: Requires `pay_period_to`; `transaction_ids` optional
(payroll transaction GUIDs).
value:
journal_type: out_of_payroll
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
pay_period_to: 2025/01/31
transaction_ids:
- 027ddd37-9340-4d70-99f5-dd199f5e0d78
- 1afe404c-f84a-4283-8131-4e6f7b0db4aa
journal_type_regular:
summary: journal_type=regular (same as full reference)
description: Alias of **request_full_reference_regular** — kept for
discoverability by type name.
value:
journal_type: regular
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
slug: global_testing_organization
journal_type_ajeer:
summary: journal_type=ajeer
value:
journal_type: ajeer
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
slug: global_testing_organization
journal_type_gosi:
summary: journal_type=gosi
value:
journal_type: gosi
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
slug: global_testing_organization
journal_type_accrual:
summary: journal_type=accrual
value:
journal_type: accrual
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
slug: global_testing_organization
journal_type_vacation_accrual:
summary: journal_type=vacation_accrual
value:
journal_type: vacation_accrual
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
slug: global_testing_organization
journal_type_eos_accrual:
summary: journal_type=eos_accrual
value:
journal_type: eos_accrual
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
slug: global_testing_organization
journal_type_ticket:
summary: journal_type=ticket
value:
journal_type: ticket
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
slug: global_testing_organization
journal_type_expense:
summary: journal_type=expense
value:
journal_type: expense
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
slug: global_testing_organization
journal_type_out_of_payroll:
summary: journal_type=out_of_payroll (requires pay_period_to)
value:
journal_type: out_of_payroll
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
pay_period_to: 2025/01/31
transaction_ids:
- 027ddd37-9340-4d70-99f5-dd199f5e0d78
slug: global_testing_organization
journal_type_vacation_settlement:
summary: journal_type=vacation_settlement (rejected by Open API)
value:
journal_type: vacation_settlement
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
slug: global_testing_organization
journal_type_end_of_service:
summary: journal_type=end_of_service (rejected by Open API)
value:
journal_type: end_of_service
paygroup_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
pay_period_from: 2025/01/01
slug: global_testing_organization
invalidParams:
summary: Invalid date (matches legacy request-spec example)
value:
journal_type: invalid
paygroup_id: bad
pay_period_from: ''
slug: global_testing_organization
responses:
'400':
description: The server cannot understand the request due to a client error,
such as malformed syntax or invalid parameters
headers: {}
content:
application/json:
schema:
"$ref": "#/components/schemas/OpenApiErrorResponse"
examples:
POST#create:
value:
success: false
error: "'' is not a valid Date"
data:
POST#unsupported_journal_type:
summary: Open API rejects vacation_settlement and end_of_service
value:
success: false
error: 'Journal type: vacation_settlement is not supported'
data:
'201':
description: The request has been fulfilled, and a new resource has been
created as a result. The newly created resource is returned in the response
body
headers: {}
content:
application/json:
schema:
"$ref": "#/components/schemas/JournalExportRequestResponse"
examples:
POST#create:
value:
success: true
message:
data:
journal_export_request:
source: open_api
status: pending
created_at: 2025/08/20
updated_at: 2025/08/20
POST#regular:
summary: Typical regular payroll export accepted
value:
success: true
message:
data:
journal_export_request:
source: open_api
status: pending
created_at: 2025/08/20
updated_at: 2025/08/20
id: 2281f094-7684-43d6-9f24-de3b0a0c84e3
total_journals: 0
journals:
POST#out_of_payroll:
summary: Out-of-payroll export accepted (pending)
value:
success: true
message:
data:
journal_export_request:
source: open_api
status: pending
created_at: 2025/08/20
updated_at: 2025/08/20
id: 7b2c9e11-4a3d-4f1e-9c0b-1d2e3f4a5b6c
total_journals: 0
journals:
security:
- org_slug: []
- locale: []
- Access-Token: []
"/openapi/v1/accounting/journals/{id}":
get:
tags:
- Finance
summary: Get Journal Export Request
description: |
Poll a journal export request by `id` until `status` is terminal for journal data (`completed` or `failed`).
`completed_with_errors` exists on the export record but **Open API GET returns 404** (see **404** example `GET#completed_with_errors`).
### How to read the **200** response examples
| Example | Purpose |
| --- | --- |
| **GET#show** | **Full reference** — complete shape (export metadata, `journals[]`, `journal_lines[]`, pagination). **Use this for integration.** |
| **GET#show_pending**, **GET#show_processing**, **GET#show_out_of_payroll_completed**, **GET#cost_center_items_shapes** | Scenario-specific **full or partial** payloads. |
| **GET#response_label_*** | **Minimal only** — trimmed to show a sample `journals[].journal_type` **display label** (e.g. Monthly Payroll, Gosi). Empty `journal_lines` are intentional; copy field structure from **GET#show**. |
operationId: getJournalExportRequest
parameters:
- name: id
in: path
schema:
type: string
properties: {}
example: 2281f094-7684-43d6-9f24-de3b0a0c84e3
required: true
- name: slug
in: query
schema:
type: string
properties: {}
example: global_testing_organization
- name: page
in: query
schema:
type: integer
properties: {}
example: 1
required: false
- name: rpp
in: query
schema:
type: integer
properties: {}
example: 20
required: false
- name: api-version
in: header
description: Supported API version, currently 1 only
required: true
schema:
type: string
enum:
- '1'
- name: Access-Token
in: header
required: true
schema:
type: string
responses:
'404':
description: The requested resource could not be found on the server
headers: {}
content:
application/json:
schema:
"$ref": "#/components/schemas/OpenApiErrorResponse"
examples:
GET#show:
value:
success: false
error: Journal export request is archived.
data:
GET#not_found:
summary: Unknown export id
value:
success: false
error: Not Found
data:
GET#completed_with_errors:
summary: Export status completed_with_errors (no journal payload
on Open API GET)
description: |
`completed_with_errors` is a valid export status in Jisr, but this Open API `show` action
does not return `200` with journals for it (controller falls through to not found).
value:
success: false
error: Not Found
data:
'200':
description: |
The request has succeeded. Prefer example **GET#show** for the complete response shape;
**GET#response_label_*** examples are label-only samples (see operation description).
headers: {}
content:
application/json:
schema:
"$ref": "#/components/schemas/JournalExportRequestResponse"
examples:
GET#show:
summary: "[Full reference] Completed export — use for integration"
description: |
Canonical payload with `journal_export_request`, nested `journals`, `journal_lines`, and pagination.
Examples named `GET#response_label_*` are intentionally minimal and only demonstrate possible
`journals[].journal_type` display strings; they omit most fields on purpose.
value:
success: true
message:
data:
journal_export_request:
source: open_api
status: completed
created_at: 2025/08/20
updated_at: 2025/08/07
id: 891c818e-f86d-4757-9ed5-b53827cb4d1b
journal_preparation_errors:
journals:
- journal_type: Monthly Payroll
pay_period_start: 2025/01/01
pay_period_end: 2025/01/31
subsidiary: Subsidiary A
total_credit: -100.0
total_debit: 100.0
journal_lines:
- account_id: '1000'
account_name: Cash
transaction_name: Basic Salary
cost_center_items: []
employee_name: John
employee_id:
credit_amount: 0.0
debit_amount: 100.0
narrative: note
pagination:
page: 1
rpp: 20
total_pages: 1
total_records: 1
next_page:
previous_page:
GET#show_pending:
summary: "[Status] Pending — poll again later"
description: Full export body is not ready; `journals` may be absent
until `completed`.
value:
success: true
message: Journal export request is pending. Please try again later.
data:
journal_export_request:
source: open_api
status: pending
created_at: 2025/08/20
updated_at: 2025/08/20
id: 2281f094-7684-43d6-9f24-de3b0a0c84e3
journal_preparation_errors:
GET#show_processing:
summary: "[Status] Processing — poll again later"
description: Same as pending; export job is still running.
value:
success: true
message: Journal export request is processing. Please try again
later.
data:
journal_export_request:
source: open_api
status: processing
created_at: 2025/08/20
updated_at: 2025/08/20
id: 2281f094-7684-43d6-9f24-de3b0a0c84e3
total_journals: 0
journals:
GET#show_out_of_payroll_completed:
summary: "[Full reference] Completed out_of_payroll export"
description: Full journal + lines example for `out_of_payroll` (not
a label-only sample).
value:
success: true
message:
data:
journal_export_request:
source: open_api
status: completed
created_at: 2025/08/20
updated_at: 2025/08/07
id: 891c818e-f86d-4757-9ed5-b53827cb4d1b
total_journals: 1
journal_preparation_errors:
journals:
- journal_type: Out of payroll
pay_period_start: 2025/01/01
pay_period_end: 2025/01/31
subsidiary: Subsidiary A
separation_value: Pay group A
total_credit: -50.0
total_debit: 50.0
journal_lines:
- account_id: '2000'
account_name: Expense
transaction_name: Out of payrun adjustment
cost_center_items: []
employee_name: Jane
employee_id: EMP002
credit_amount: 0.0
debit_amount: 50.0
narrative: OOP line
pagination:
page: 1
rpp: 20
total_pages: 1
total_records: 1
next_page:
previous_page:
GET#response_label_monthly_payroll:
summary: "[Label only · minimal] journals[].journal_type = Monthly
Payroll"
description: |
Illustrates the display label for a `regular` export only. Not a complete API response —
see **GET#show** for journal lines, amounts, and pagination.
value:
success: true
message:
data:
journal_export_request:
source: open_api
status: completed
id: 11111111-1111-1111-1111-111111111101
total_journals: 1
journals:
- journal_type: Monthly Payroll
journal_lines: []
pagination:
page: 1
rpp: 20
total_pages: 1
total_records: 0
next_page:
previous_page:
GET#response_label_gosi:
summary: "[Label only · minimal] journals[].journal_type = Gosi"
description: Label sample only. See **GET#show** for the full response
structure.
value:
success: true
message:
data:
journal_export_request:
status: completed
total_journals: 1
journals:
- journal_type: Gosi
journal_lines: []
pagination:
page: 1
rpp: 20
total_pages: 1
total_records: 0
next_page:
previous_page:
GET#response_label_accrual:
summary: "[Label only · minimal] journals[].journal_type = Accrual"
description: Label sample only. See **GET#show** for the full response
structure.
value:
success: true
message:
data:
journal_export_request:
status: completed
total_journals: 1
journals:
- journal_type: Accrual
journal_lines: []
pagination:
page: 1
rpp: 20
total_pages: 1
total_records: 0
next_page:
previous_page:
GET#response_label_ajeer:
summary: "[Label only · minimal] journals[].journal_type = Ajeer"
description: Label sample only. See **GET#show** for the full response
structure.
value:
success: true
message:
data:
journal_export_request:
status: completed
total_journals: 1
journals:
- journal_type: Ajeer
journal_lines: []
pagination:
page: 1
rpp: 20
total_pages: 1
total_records: 0
next_page:
previous_page:
GET#response_label_ticket:
summary: "[Label only · minimal] journals[].journal_type = Ticket"
description: Label sample only. See **GET#show** for the full response
structure.
value:
success: true
message:
data:
journal_export_request:
status: completed
total_journals: 1
journals:
- journal_type: Ticket
journal_lines: []
pagination:
page: 1
rpp: 20
total_pages: 1
total_records: 0
next_page:
previous_page:
GET#response_label_expense:
summary: "[Label only · minimal] journals[].journal_type = Expense"
description: Label sample only. See **GET#show** for the full response
structure.
value:
success: true
message:
data:
journal_export_request:
status: completed
total_journals: 1
journals:
- journal_type: Expense
journal_lines: []
pagination:
page: 1
rpp: 20
total_pages: 1
total_records: 0
next_page:
previous_page:
GET#response_label_out_of_payroll:
summary: "[Label only · minimal] journals[].journal_type = Out of
payroll"
description: Label sample only. For a full out_of_payroll payload
see **GET#show_out_of_payroll_completed**.
value:
success: true
message:
data:
journal_export_request:
status: completed
total_journals: 1
journals:
- journal_type: Out of payroll
journal_lines: []
pagination:
page: 1
rpp: 20
total_pages: 1
total_records: 0
next_page:
previous_page:
GET#cost_center_items_shapes:
summary: "[Field reference] cost_center_items string vs object shapes"
description: Shows both allowed `cost_center_items` item shapes
on one journal line. Use **GET#show** for overall structure.
value:
success: true
message:
data:
journal_export_request:
status: completed
total_journals: 1
journals:
- journal_type: Monthly Payroll
journal_lines:
- account_id: '1000'
account_name: Cash
transaction_name: Basic Salary
cost_center_items:
- Riyadh Office
- name: Cost center A
code: CC-A
credit_amount: 0.0
debit_amount: 100.0
pagination:
page: 1
rpp: 20
total_pages: 1
total_records: 1
next_page:
previous_page:
'400':
description: The server cannot understand the request due to a client error,
such as malformed syntax or invalid parameters
headers: {}
content:
application/json:
schema:
"$ref": "#/components/schemas/JournalExportRequestFailedResponse"
examples:
GET#show:
value:
success: false
error: 'Journal export request failed with error: oops'
data:
journal_export_request:
source: open_api
status: failed
created_at: 2025/08/20
updated_at: 2025/06/15
id: 8c22f671-5025-4b3f-a035-06012f79093b
journal_preparation_errors: oops
journals:
security:
- org_slug: []
- locale: []
- Access-Token: []
"/openapi/v1/accounting/tracking_dimensions/{id}":
get:
tags:
- Tracking_dimensions
summary: Get Openapi V1 Accounting Tracking Dimensions
parameters:
- name: id
in: path
schema:
type: string
properties: {}
example: f5d3d473-a502-42b5-a204-0896c99331e9
required: true
responses:
'200':
description: The request has succeeded
headers: {}
content:
application/json:
schema:
type: object
examples:
GET#show:
value:
success: true
message:
data:
tracking_dimension:
id: f5d3d473-a502-42b5-a204-0896c99331e9
name: tracking-1
name_ar: tracking-1-ar
external_data:
name: Jeneva Spinka
internal_id: '5227380897'
jisr_org_structure: Location
created_at: 2026/03/26
updated_at: 2026/03/26
subsidiary_id: 1b1b4ec1-b70c-42bf-be61-c5d0ca2f0dc9
tracking_dimension_values:
- id: 5fc2bbcd-07cd-465f-ae9f-07b921a6a1b7
tracking_dimension_id: f5d3d473-a502-42b5-a204-0896c99331e9
external_data:
name: Lashaun Hoppe
internal_id: '2395703344'
name: ex-2
name_ar: ex-2-ar
code:
jisr_org_structure: Location
jisr_org_structure_id: 76
created_at: 2026/03/26
updated_at: 2026/03/26
- id: 241dcf13-d8ce-498c-9a23-e7f67852cbd1
tracking_dimension_id: f5d3d473-a502-42b5-a204-0896c99331e9
external_data:
name: Guillermo Bradtke
internal_id: '8980614846'
name: itaque-1
name_ar: itaque-1-ar
code:
jisr_org_structure: Location
jisr_org_structure_id: 75
created_at: 2026/03/26
updated_at: 2026/03/26
security:
- org_slug: []
- locale: []
- Access-Token: []
"/openapi/v1/accounting/tracking_dimensions":
get:
tags:
- Tracking_dimensions
summary: Get All Openapi V1 Accounting Tracking Dimensions
parameters:
- name: subsidiary_id
in: query
schema:
type: string
properties: {}
example: d3079071-4279-4805-8769-bcbad5b05e5d
- name: slug
in: query
schema:
type: string
properties: {}
example: global_testing_organization_with_an_employee
responses:
'200':
description: The request has succeeded
headers: {}
content:
application/json:
schema:
type: object
examples:
GET#index:
value:
success: true
message:
data:
tracking_dimensions:
- id: 6a42115f-cd58-459f-80a0-d79268efce43
name: tracking-3
name_ar: tracking-3-ar
external_data:
name: Mariano Terry
internal_id: '8583055014'
jisr_org_structure: Location
created_at: 2026/03/26
updated_at: 2026/03/26
subsidiary_id: e14b9826-fb3a-422f-8163-4fca8d723d9b
- id: '0582f8b1-f6f5-4d14-8c17-138b55e9a480'
name: tracking-4
name_ar: tracking-4-ar
external_data:
name: Al Gleichner
internal_id: '6811538317'
jisr_org_structure: Area
created_at: 2026/03/26
updated_at: 2026/03/26
subsidiary_id: e8cf31f4-c61c-48bd-a68a-4b00479f434d
when subsidiary_id is provided:
value:
success: true
message:
data:
tracking_dimensions:
- id: 44cca337-d46e-41d8-a7dc-e9a773164087
name: tracking-5
name_ar: tracking-5-ar
external_data:
name: Ian Ullrich
internal_id: '2950998193'
jisr_org_structure: Location
created_at: 2026/03/26
updated_at: 2026/03/26
subsidiary_id: d3079071-4279-4805-8769-bcbad5b05e5d
security:
- org_slug: []
- locale: []
- Access-Token: []
"/openapi/v1/lookups/departments":
get:
tags:
- Lookups
summary: Departments
description: |-
# **Request**
`GET /openapi/v1/lookups/departments`
This API used to get all departments on organization
The request includes the following:
### HEADERS
| **Name** | **Description** |
| --- | --- |
| slug | Organization slug |
| api-version | Supported version (1) |
| Access-Token | Used to allow an application to access an API it generated from Session API |
| source | open_api or external_aggregator |
| username | This field needed if source is external_aggregator |
#### Query Parameters
| **Name** | **Description** |
| --- | --- |
| page | Current page to be shown |
| rpp | **Record Per Page** represent the number of records per page |
---
# Response
- Success Response
```
{
"success": true,
"message": null,
"data": {
"departments": [
{
"id": 65961,
"name_en": "Testing MQ",
"name_ar": "testing MQ"
},
{
"id": 65962,
"name_en": "Testing MQ 1",
"name_ar": "Testing MQ 2"
},
{
"id": 65956,
"name_en": "test1aaa",
"name_ar": "test1aaa"
},
{
"id": 65957,
"name_en": "HRsubsub",
"name_ar": "HRsubsub"
},
{
"id": 46910,
"name_en": "Higher ManagementHigher Management",
"name_ar": "الإدارة العليا"
},
{
"id": 49566,
"name_en": "main department Parent parent parent",
"name_ar": "القسم الرئيسي"
},
{
"id": 48515,
"name_en": "Sample Parent",
"name_ar": "نموذج البارنت ديبارتمنت"
},
{
"id": 80256,
"name_en": "ssa",
"name_ar": "شسسش"
},
{
"id": 80258,
"name_en": "assasa",
"name_ar": "شسسشس"
},
{
"id": 80257,
"name_en": "سشش",
"name_ar": "شش"
},
{
"id": 66456,
"name_en": "fdsdaf",
"name_ar": "sadfasdf"
},
{
"id": 80383,
"name_en": "test٢٢٢١",
"name_ar": "تيست"
},
{
"id": 72284,
"name_en": "Test_Department",
"name_ar": "تيست_قسم"
},
{
"id": 77116,
"name_en": "Maice Zekry",
"name_ar": "ميس ذكري"
},
{
"id": 77214,
"name_en": "Admin & Facility",
"name_ar": "المنشات"
},
{
"id": 77436,
"name_en": "fgh",
"name_ar": "vnb"
},
{
"id": 10195,
"name_en": "Markting Dep",
"name_ar": "Markting Dep"
},
{
"id": 10185,
"name_en": "Central Area3",
"name_ar": "Central Area3"
},
{
"id": 10184,
"name_en": "Lab Dep",
"name_ar": "Lab Dep"
},
{
"id": 10435,
"name_en": "Accouting & Finance",
"name_ar": "الحسابات والمالية"
}
],
"pagination": {
"current_page": 1,
"next_page": 2,
"previous_page": null,
"total_pages": 5,
"per_page": 20,
"total_entries": 89
}
}
}
```
operationId: departments
parameters:
- name: page
in: query
schema:
type: string
- name: rpp
in: query
schema:
type: string
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: Success Response By external aggregator
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
departments:
type: array
description: "`code` is the customer-defined department code,
unique within the organization and null when unset. `parent`
is the direct parent department, null for a root department.
`manager` is the department manager keyed on the employee
id used throughout this API, null when unset, and is returned
on the parent too. `valid_from`, `valid_to` and `status`
are informational and returned only for organizations where
they are enabled."
example:
- id: 65961
name_ar: testing MQ
name_en: Testing MQ
code: DEPT-001
manager:
parent:
- id: 65962
name_ar: Testing MQ 2
name_en: Testing MQ 1
code: DEPT-002
manager:
id: 9f1c2e7a-4b8d-4f1e-9c3a-7d5b2e6f8a10
name: Sara Ahmed
parent:
id: 65961
name_ar: testing MQ
name_en: Testing MQ
code: DEPT-001
manager:
- id: 65956
name_ar: test1aaa
name_en: test1aaa
code:
parent:
- id: 65957
name_ar: HRsubsub
name_en: HRsubsub
code: DEPT-004
parent:
id: 65956
name_ar: test1aaa
name_en: test1aaa
code:
valid_from: '2026-01-01'
valid_to: '2026-12-31'
status: active
- id: 46910
name_ar: الإدارة العليا
name_en: Higher ManagementHigher Management
code:
parent:
- id: 49566
name_ar: القسم الرئيسي
name_en: main department Parent parent parent
- id: 48515
name_ar: نموذج البارنت ديبارتمنت
name_en: Sample Parent
- id: 80256
name_ar: شسسش
name_en: ssa
- id: 80258
name_ar: شسسشس
name_en: assasa
- id: 80257
name_ar: شش
name_en: سشش
- id: 66456
name_ar: sadfasdf
name_en: fdsdaf
- id: 80383
name_ar: تيست
name_en: test٢٢٢١
- id: 72284
name_ar: تيست_قسم
name_en: Test_Department
- id: 77116
name_ar: ميس ذكري
name_en: Maice Zekry
- id: 77214
name_ar: المنشات
name_en: Admin & Facility
- id: 77436
name_ar: vnb
name_en: fgh
- id: 10195
name_ar: Markting Dep
name_en: Markting Dep
- id: 10185
name_ar: Central Area3
name_en: Central Area3
- id: 10184
name_ar: Lab Dep
name_en: Lab Dep
- id: 10435
name_ar: الحسابات والمالية
name_en: Accouting & Finance
items:
type: object
properties:
id:
type: number
example: 65961
name_ar:
type: string
example: testing MQ
name_en:
type: string
example: Testing MQ
pagination:
type: object
properties:
current_page:
type: number
example: 1
next_page:
type: number
example: 2
per_page:
type: number
example: 20
previous_page:
type: object
nullable: true
example: 'null'
total_entries:
type: number
example: 89
total_pages:
type: number
example: 5
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
"/openapi/v1/lookups/employment_types":
get:
tags:
- Lookups
summary: Employment Types
description: |-
# **Request**
`GET /openapi/v1/lookups/employment_types`
This API used to get all employment types on organization
The request includes the following:
### HEADERS
| **Name** | **Description** |
| --- | --- |
| slug | Organization slug |
| api-version | Supported version (1) |
| Access-Token | Used to allow an application to access an API it generated from Session API |
| source | open_api or external_aggregator |
| username | This field needed if source is external_aggregator |
#### Query Parameters
| **Name** | **Description** |
| --- | --- |
| page | Current page to be shown |
| rpp | **Record Per Page** represent the number of records per page |
---
# Response
- Success Response
```
{
"success": true,
"message": null,
"data": {
"employment_types": [
{
"id": 104,
"name_en": "Ajeer",
"name_ar": "موظف أجير"
},
{
"id": 7808,
"name_en": "Contractor",
"name_ar": "مقاول"
},
{
"id": 505,
"name_en": "Domestic Labor",
"name_ar": "العمالة المنزلية"
},
{
"id": 619,
"name_en": "FREE LANCER",
"name_ar": "مستقل"
},
{
"id": 78,
"name_en": "Full Time",
"name_ar": "دوام كامل"
},
{
"id": 10700,
"name_en": "Outsourced",
"name_ar": "أجير"
},
{
"id": 79,
"name_en": "Part Time",
"name_ar": "دوام جزئي"
},
{
"id": 141,
"name_en": "Remote",
"name_ar": "موظف عن بعد"
},
{
"id": 7842,
"name_en": "Software Engineer",
"name_ar": "مهندس برمجيات"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"previous_page": null,
"total_pages": 1,
"per_page": 20,
"total_entries": 9
}
}
}
```
operationId: employmentTypes
parameters:
- name: page
in: query
schema:
type: string
- name: rpp
in: query
schema:
type: string
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: Success Response By external aggregator
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
employment_types:
type: array
example:
- id: 104
name_ar: موظف أجير
name_en: Ajeer
- id: 7808
name_ar: مقاول
name_en: Contractor
- id: 505
name_ar: العمالة المنزلية
name_en: Domestic Labor
- id: 619
name_ar: مستقل
name_en: FREE LANCER
- id: 78
name_ar: دوام كامل
name_en: Full Time
- id: 10700
name_ar: أجير
name_en: Outsourced
- id: 79
name_ar: دوام جزئي
name_en: Part Time
- id: 141
name_ar: موظف عن بعد
name_en: Remote
- id: 7842
name_ar: مهندس برمجيات
name_en: Software Engineer
items:
type: object
properties:
id:
type: number
example: 104
name_ar:
type: string
example: موظف أجير
name_en:
type: string
example: Ajeer
pagination:
type: object
properties:
current_page:
type: number
example: 1
next_page:
type: object
nullable: true
example: 'null'
per_page:
type: number
example: 20
previous_page:
type: object
nullable: true
example: 'null'
total_entries:
type: number
example: 9
total_pages:
type: number
example: 1
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
"/openapi/v1/lookups/business_units":
get:
tags:
- Lookups
summary: Business Units
description: |-
# **Request**
`GET /openapi/v1/lookups/business_units`
This API used to get all business units on organization
The request includes the following:
### HEADERS
| **Name** | **Description** |
| --- | --- |
| slug | Organization slug |
| api-version | Supported version (1) |
| Access-Token | Used to allow an application to access an API it generated from Session API |
| source | open_api or external_aggregator |
| username | This field needed if source is external_aggregator |
#### Query Parameters
| **Name** | **Description** |
| --- | --- |
| page | Current page to be shown |
| rpp | **Record Per Page** represent the number of records per page |
---
# Response
- Success Response
```
{
"success": true,
"message": null,
"data": {
"business_units": [
{
"id": "c33f90d6-85d8-4f99-baae-d6543bd96ab8",
"name_en": "business-unit-open-api-1",
"name_ar": "business-unit-open-api-1-ar"
},
{
"id": "59872d49-d600-4235-a0b5-69dad9ff7d61",
"name_en": "business-unit-open-api-2",
"name_ar": "business-unit-open-api-2-ar"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"previous_page": null,
"total_pages": 1,
"per_page": 100,
"total_entries": 2
}
}
}
```
operationId: business_units
parameters:
- name: page
in: query
schema:
type: string
- name: rpp
in: query
schema:
type: string
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: The request has succeeded
headers: {}
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
nullable: true
data:
type: object
properties:
business_units:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
name_en:
type: string
name_ar:
type: string
nullable: true
pagination:
type: object
properties:
current_page:
type: integer
next_page:
type: integer
nullable: true
previous_page:
type: integer
nullable: true
total_pages:
type: integer
per_page:
type: integer
total_entries:
type: integer
examples:
when list business unit:
value:
success: true
message:
data:
business_units:
- id: c33f90d6-85d8-4f99-baae-d6543bd96ab8
name_en: business-unit-open-api-1
name_ar: business-unit-open-api-1-ar
- id: 59872d49-d600-4235-a0b5-69dad9ff7d61
name_en: business-unit-open-api-2
name_ar: business-unit-open-api-2-ar
pagination:
current_page: 1
next_page:
previous_page:
total_pages: 1
per_page: 100
total_entries: 2
"/openapi/v1/lookups/locations":
get:
tags:
- Lookups
summary: Locations
description: |-
# **Request**
`GET /openapi/v1/lookups/locations`
This API used to get all locations on organization
The request includes the following:
### HEADERS
| **Name** | **Description** |
| --- | --- |
| slug | Organization slug |
| api-version | Supported version (1) |
| Access-Token | Used to allow an application to access an API it generated from Session API |
| source | open_api or external_aggregator |
| username | This field needed if source is external_aggregator |
#### Query Parameters
| **Name** | **Description** |
| --- | --- |
| page | Current page to be shown |
| rpp | **Record Per Page** represent the number of records per page |
---
# Response
- Success Response
```
{
"success": true,
"message": null,
"data": {
"locations": [
{
"id": 6598,
"address_en": "CR- Kharj",
"address_ar": "CR- Kharj"
},
{
"id": 736,
"address_en": "ALEEM",
"address_ar": "أليم"
},
{
"id": 1190,
"address_en": "test",
"address_ar": "فحص"
},
{
"id": 6564,
"address_en": "CR- Head office",
"address_ar": "عربي "
},
{
"id": 6562,
"address_en": "CR-Design Lab Dep",
"address_ar": "الحياه "
},
{
"id": 8844,
"address_en": "Lahour",
"address_ar": "لاهور"
},
{
"id": 29403,
"address_en": "kullu",
"address_ar": "kullu"
},
{
"id": 21299,
"address_en": "fgfg",
"address_ar": "gfg"
},
{
"id": 6735,
"address_en": "Malaz",
"address_ar": "اا"
},
{
"id": 6722,
"address_en": "Head Office",
"address_ar": "المكتب الرئيسي"
},
{
"id": 830,
"address_en": "Jeddah",
"address_ar": "جدة"
},
{
"id": 20610,
"address_en": "aqaqaqaqaqaq",
"address_ar": "كاكاكاكاكاكاكاك"
},
{
"id": 20819,
"address_en": "ff",
"address_ar": "ff"
},
{
"id": 1338,
"address_en": "Al yasimin",
"address_ar": "الياسمين"
},
{
"id": 22654,
"address_en": "Makkah2",
"address_ar": "Makkah3"
},
{
"id": 20818,
"address_en": "rgdssd",
"address_ar": "تيست"
},
{
"id": 6603,
"address_en": "CR- Riyadh Park",
"address_ar": "CR- Riyadh Park"
},
{
"id": 6604,
"address_en": "WR- Hamra",
"address_ar": "WR- Hamra"
},
{
"id": 6563,
"address_en": "CR- Hamra",
"address_ar": "CR- Hamra"
},
{
"id": 6565,
"address_en": "Design team",
"address_ar": "Design team"
}
],
"pagination": {
"current_page": 1,
"next_page": 2,
"previous_page": null,
"total_pages": 5,
"per_page": 20,
"total_entries": 97
}
}
}
```
operationId: locations
parameters:
- name: page
in: query
schema:
type: string
- name: rpp
in: query
schema:
type: string
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: Success Response By external aggregator
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
locations:
type: array
example:
- address_ar: CR- Kharj
address_en: CR- Kharj
id: 6598
- address_ar: أليم
address_en: ALEEM
id: 736
- address_ar: فحص
address_en: test
id: 1190
- address_ar: 'عربي '
address_en: CR- Head office
id: 6564
- address_ar: 'الحياه '
address_en: CR-Design Lab Dep
id: 6562
- address_ar: لاهور
address_en: Lahour
id: 8844
- address_ar: kullu
address_en: kullu
id: 29403
- address_ar: gfg
address_en: fgfg
id: 21299
- address_ar: اا
address_en: Malaz
id: 6735
- address_ar: المكتب الرئيسي
address_en: Head Office
id: 6722
- address_ar: جدة
address_en: Jeddah
id: 830
- address_ar: كاكاكاكاكاكاكاك
address_en: aqaqaqaqaqaq
id: 20610
- address_ar: ff
address_en: ff
id: 20819
- address_ar: الياسمين
address_en: Al yasimin
id: 1338
- address_ar: Makkah3
address_en: Makkah2
id: 22654
- address_ar: تيست
address_en: rgdssd
id: 20818
- address_ar: CR- Riyadh Park
address_en: CR- Riyadh Park
id: 6603
- address_ar: WR- Hamra
address_en: WR- Hamra
id: 6604
- address_ar: CR- Hamra
address_en: CR- Hamra
id: 6563
- address_ar: Design team
address_en: Design team
id: 6565
items:
type: object
properties:
address_ar:
type: string
example: CR- Kharj
address_en:
type: string
example: CR- Kharj
id:
type: number
example: 6598
pagination:
type: object
properties:
current_page:
type: number
example: 1
next_page:
type: number
example: 2
per_page:
type: number
example: 20
previous_page:
type: object
nullable: true
example: 'null'
total_entries:
type: number
example: 97
total_pages:
type: number
example: 5
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
"/openapi/v1/lookups/nationalities":
get:
tags:
- Lookups
summary: Nationalities
description: |-
# **Request**
`GET /openapi/v1/lookups/nationalities`
This API used to get all Nationalities supported on system
The request includes the following:
### HEADERS
| **Name** | **Description** |
| --- | --- |
| slug | Organization slug |
| api-version | Supported version (1) |
| Access-Token | Used to allow an application to access an API it generated from Session API |
| source | open_api or external_aggregator |
| username | This field needed if source is external_aggregator |
#### Query Parameters
| **Name** | **Description** |
| --- | --- |
| page | Current page to be shown |
| rpp | **Record Per Page** represent the number of records per page |
---
# Response
- Success Response
```
{
"success": true,
"message": null,
"data": {
"nationalities": [
{
"id": 424,
"name_en": "Kosovar",
"name_ar": "كوسوفي"
},
{
"id": 55,
"name_en": "Egyptian",
"name_ar": "مصرى"
},
{
"id": 1,
"name_en": "Afghan",
"name_ar": "الأفغاني"
},
{
"id": 2,
"name_en": "Albanian",
"name_ar": " الألبانية"
},
{
"id": 3,
"name_en": "Algerian",
"name_ar": " جزائري"
},
{
"id": 4,
"name_en": "American",
"name_ar": " أمريكي"
},
{
"id": 5,
"name_en": "Andorran",
"name_ar": " أندورا"
},
{
"id": 6,
"name_en": "Angolan",
"name_ar": " الأنغولي"
},
{
"id": 7,
"name_en": "Antiguans",
"name_ar": " انتيغوا"
},
{
"id": 8,
"name_en": "Argentinean",
"name_ar": " الأرجنتيني"
},
{
"id": 9,
"name_en": "Armenian",
"name_ar": " لأرميني"
},
{
"id": 10,
"name_en": "Australian",
"name_ar": "الأسترالي"
},
{
"id": 11,
"name_en": "Austrian",
"name_ar": "النمساوي"
},
{
"id": 12,
"name_en": "Azerbaijani",
"name_ar": "أذربيجان"
},
{
"id": 13,
"name_en": "Bahamian",
"name_ar": "باهامى"
},
{
"id": 14,
"name_en": "Bahraini",
"name_ar": "البحريني"
},
{
"id": 15,
"name_en": "Bangladeshi",
"name_ar": "بنجلاديش"
},
{
"id": 16,
"name_en": "Barbadian",
"name_ar": "باربادوسي"
},
{
"id": 17,
"name_en": "Barbudans",
"name_ar": "بربودا"
},
{
"id": 18,
"name_en": "Batswana",
"name_ar": "بوتسوانا"
}
],
"pagination": {
"current_page": 1,
"next_page": 2,
"previous_page": null,
"total_pages": 12,
"per_page": 20,
"total_entries": 226
}
}
}
```
operationId: nationalities
parameters:
- name: page
in: query
schema:
type: string
- name: rpp
in: query
schema:
type: string
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: Success Response By external aggregator
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
nationalities:
type: array
example:
- id: 424
name_ar: كوسوفي
name_en: Kosovar
- id: 55
name_ar: مصرى
name_en: Egyptian
- id: 1
name_ar: الأفغاني
name_en: Afghan
- id: 2
name_ar: " الألبانية"
name_en: Albanian
- id: 3
name_ar: " جزائري"
name_en: Algerian
- id: 4
name_ar: " أمريكي"
name_en: American
- id: 5
name_ar: " أندورا"
name_en: Andorran
- id: 6
name_ar: " الأنغولي"
name_en: Angolan
- id: 7
name_ar: " انتيغوا"
name_en: Antiguans
- id: 8
name_ar: " الأرجنتيني"
name_en: Argentinean
- id: 9
name_ar: " لأرميني"
name_en: Armenian
- id: 10
name_ar: الأسترالي
name_en: Australian
- id: 11
name_ar: النمساوي
name_en: Austrian
- id: 12
name_ar: أذربيجان
name_en: Azerbaijani
- id: 13
name_ar: باهامى
name_en: Bahamian
- id: 14
name_ar: البحريني
name_en: Bahraini
- id: 15
name_ar: بنجلاديش
name_en: Bangladeshi
- id: 16
name_ar: باربادوسي
name_en: Barbadian
- id: 17
name_ar: بربودا
name_en: Barbudans
- id: 18
name_ar: بوتسوانا
name_en: Batswana
items:
type: object
properties:
id:
type: number
example: 424
name_ar:
type: string
example: كوسوفي
name_en:
type: string
example: Kosovar
pagination:
type: object
properties:
current_page:
type: number
example: 1
next_page:
type: number
example: 2
per_page:
type: number
example: 20
previous_page:
type: object
nullable: true
example: 'null'
total_entries:
type: number
example: 226
total_pages:
type: number
example: 12
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
"/openapi/v1/lookups/outsourcing_companies":
get:
tags:
- Lookups
summary: Outsourcing Companies
description: |-
# **Request**
`GET /openapi/v1/lookups/outsourcing_companies`
This API used to get all Outsourcing Companies that on registered organization
The request includes the following:
### HEADERS
| **Name** | **Description** |
| --- | --- |
| slug | Organization slug |
| api-version | Supported version (1) |
| Access-Token | Used to allow an application to access an API it generated from Session API |
| source | open_api or external_aggregator |
| username | This field needed if source is external_aggregator |
#### Query Parameters
| **Name** | **Description** |
| --- | --- |
| page | Current page to be shown |
| rpp | **Record Per Page** represent the number of records per page |
---
# Response
- Success Response
```
{
"success": true,
"message": null,
"data": {
"outsourcing_companies": [
{
"id": 1,
"name_en": "Outsourcing Provider 1",
"name_ar": "Outsourcing Provider 1"
},
{
"id": 245,
"name_en": "TEST",
"name_ar": "فحص"
},
{
"id": 44,
"name_en": "baradem",
"name_ar": "baradem"
},
{
"id": 45,
"name_en": "baradem1",
"name_ar": "baradem1"
},
{
"id": 181,
"name_en": "Default 19",
"name_ar": "Default 19"
},
{
"id": 191,
"name_en": "Nas",
"name_ar": "ناس"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"previous_page": null,
"total_pages": 1,
"per_page": 20,
"total_entries": 6
}
}
}
```
operationId: outsourcingCompanies
parameters:
- name: page
in: query
schema:
type: string
- name: rpp
in: query
schema:
type: string
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: Success Response By external aggregator
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
outsourcing_companies:
type: array
example:
- id: 1
name_ar: Outsourcing Provider 1
name_en: Outsourcing Provider 1
- id: 245
name_ar: فحص
name_en: TEST
- id: 44
name_ar: baradem
name_en: baradem
- id: 45
name_ar: baradem1
name_en: baradem1
- id: 181
name_ar: Default 19
name_en: Default 19
- id: 191
name_ar: ناس
name_en: Nas
items:
type: object
properties:
id:
type: number
example: 1
name_ar:
type: string
example: Outsourcing Provider 1
name_en:
type: string
example: Outsourcing Provider 1
pagination:
type: object
properties:
current_page:
type: number
example: 1
next_page:
type: object
nullable: true
example: 'null'
per_page:
type: number
example: 20
previous_page:
type: object
nullable: true
example: 'null'
total_entries:
type: number
example: 6
total_pages:
type: number
example: 1
message:
type: object
nullable: true
example: 'null'
success:
type: boolean
example: true
"/openapi/v1/webhooks":
get:
tags:
- Webhooks
summary: Webhooks
description: Get all webhooks
operationId: webhooks
parameters:
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: object
nullable: true
example: 'null'
data:
type: object
properties:
subscriptions:
type: array
items:
type: object
properties:
id:
type: number
example: 12
name:
type: string
example: gbhnjmk
auth_data:
type: object
nullable: true
example: 'null'
auth_position:
type: string
example: header
auth_type:
type: string
example: none
request_format:
type: string
example: json
custom_header:
type: object
nullable: true
example: 'null'
description:
type: string
example: vhbjn
endpoint:
type: string
example: https://typedwebhook.tools/webhook/cd26b02c-7fe3-470d-84d2-1a73dbe95837
http_method:
type: string
example: post
status:
type: string
example: inactive
agreegator:
type: object
nullable: true
example: 'null'
organization:
type: object
properties:
id:
type: number
example: 2
identifier:
type: number
example: 9000002
name:
type: string
example: Bingazy Company
name_i18n:
type: string
example: Bingazy Company
created_at:
type: string
example: '2019-05-14T11:22:23.509Z'
actions:
type: array
items:
type: object
properties:
id:
type: number
example: 20
name_en:
type: string
example: confirm_regular_payrun
name_ar:
type: string
example: confirm_reglar_payrun
status:
type: string
example: active
description:
type: string
example: Confirm Regular Payroll
created_at:
type: string
example: '2024-01-01T11:46:08.553Z'
created_at:
type: string
example: '2024-05-05T06:28:02.329Z'
updated_at:
type: string
example: '2024-11-14T05:49:24.165Z'
post:
tags:
- Webhooks
summary: Webhooks
description: Create a new webhook
operationId: createWebhook
parameters:
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the webhook subscription.
example: Subscription to Example Webhook
description:
type: string
description: A brief description of the subscription.
example: This subscription receives updates on example events.
endpoint:
type: string
description: The URL where the webhook should send events.
example: https://example.com/webhook
status:
type: string
description: The status of the subscription, e.g., active or inactive.
example: active
custom_header:
type: object
additionalProperties:
type: string
description: Custom headers to include in the webhook request.
example:
X-Custom-Header: Value
authentication:
type: object
properties:
type:
type: string
description: Authentication type for the webhook (e.g., 'Bearer',
'Basic').
example: Bearer
add_position:
type: string
description: Position of the authentication in the header (e.g.,
'header' or 'query').
example: header
data:
type: object
additionalProperties:
type: string
description: Additional data required for authentication.
example:
token: your-auth-token
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Webhook created successfully
data:
type: object
properties:
id:
type: number
example: 10
name:
type: string
example: ghj
auth_data:
type: object
nullable: true
example: 'null'
auth_position:
type: string
example: header
auth_type:
type: string
example: none
request_format:
type: string
example: json
custom_header:
type: object
nullable: true
example: 'null'
description:
type: string
example: nm
endpoint:
type: string
example: https://typedwebhook.tools/webhook/73f83f6c-3295-489d-8400-8af77fb98d21
http_method:
type: string
example: post
status:
type: string
example: active
actions:
type: array
items:
type: object
properties:
id:
type: number
example: 1
name_en:
type: string
example: create_employee
name_ar:
type: string
example: create_employee
status:
type: string
example: active
description:
type: string
example: Create Employee
created_at:
type: string
example: 2023-08-03 11:03:11 UTC
created_at:
type: string
example: 2023-12-25 08:26:41 UTC
updated_at:
type: string
example: 2024-05-21 06:04:29 UTC
"/openapi/v1/webhooks/{id}":
put:
tags:
- Webhooks
summary: Webhooks
description: Update a webhook
operationId: updateWebhook
parameters:
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
- name: id
in: path
description: The ID of the webhook subscription to update.
required: true
schema:
type: integer
example: 10
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the webhook subscription.
example: Subscription to Example Webhook
description:
type: string
description: A brief description of the subscription.
example: This subscription receives updates on example events.
endpoint:
type: string
description: The URL where the webhook should send events.
example: https://example.com/webhook
status:
type: string
description: The status of the subscription, e.g., active or inactive.
example: active
custom_header:
type: object
additionalProperties:
type: string
description: Custom headers to include in the webhook request.
example:
X-Custom-Header: Value
authentication:
type: object
properties:
type:
type: string
description: Authentication type for the webhook
example: Bearer
add_position:
type: string
description: Position of the authentication in the header (e.g.,
'header' or 'query').
example: header
data:
type: object
additionalProperties:
type: string
description: Additional data required for authentication.
example:
token: your-auth-token
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Webhook updated successfully
data:
type: object
properties:
id:
type: number
example: 10
name:
type: string
example: ghj
auth_data:
type: object
nullable: true
example: 'null'
auth_position:
type: string
example: header
auth_type:
type: string
example: none
request_format:
type: string
example: json
custom_header:
type: object
nullable: true
example: 'null'
description:
type: string
example: nm
endpoint:
type: string
example: https://typedwebhook.tools/webhook/73f83f6c-3295-489d-8400-8af77fb98d21
http_method:
type: string
example: post
status:
type: string
example: active
actions:
type: array
items:
type: object
properties:
id:
type: number
example: 1
name_en:
type: string
example: create_employee
name_ar:
type: string
example: create_employee
status:
type: string
example: active
description:
type: string
example: Create Employee
created_at:
type: string
example: 2023-08-03 11:03:11 UTC
created_at:
type: string
example: 2023-12-25 08:26:41 UTC
updated_at:
type: string
example: 2024-05-21 06:04:29 UTC
delete:
tags:
- Webhooks
summary: Webhooks
description: Delete a webhook
operationId: deleteWebhook
parameters:
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
- name: id
in: path
description: The ID of the webhook subscription to delete.
required: true
schema:
type: integer
example: 10
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Webhook deleted successfully
data:
type: object
properties:
id:
type: number
example: 10
name:
type: string
example: ghj
auth_data:
type: object
nullable: true
example: 'null'
auth_position:
type: string
example: header
auth_type:
type: string
example: none
request_format:
type: string
example: json
custom_header:
type: object
nullable: true
example: 'null'
description:
type: string
example: nm
endpoint:
type: string
example: https://typedwebhook.tools/webhook/73f83f6c-3295-489d-8400-8af77fb98d21
http_method:
type: string
example: post
status:
type: string
example: active
actions:
type: array
items:
type: object
properties:
id:
type: number
example: 1
name_en:
type: string
example: create_employee
name_ar:
type: string
example: create_employee
status:
type: string
example: active
description:
type: string
example: Create Employee
created_at:
type: string
example: 2023-08-03 11:03:11 UTC
created_at:
type: string
example: 2023-12-25 08:26:41 UTC
updated_at:
type: string
example: 2023-12-25 08:26:41 UTC
"/openapi/v1/webhooks/{id}/test":
post:
tags:
- Webhooks
summary: Webhooks
description: Test a webhook
operationId: testWebhook
parameters:
- name: slug
in: header
schema:
type: string
- name: api-version
in: header
schema:
type: string
- name: Access-Token
in: header
schema:
type: string
- name: id
in: path
description: The ID of the webhook subscription to test.
required: true
schema:
type: integer
example: 10
responses:
'200':
description: Success Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
message:
type: string
example: Webhook test successful
data:
type: object
nullable: true
tags:
- name: Authentication
- name: Accruals
- name: Attendance
- name: Attendance Log
- name: Employees
- name: Employee Leave
- name: Finance
- name: Lookups
- name: Webhooks