Customer APIs are built to provide flexibility to our users to get information or post data from/to the database. It allows external entities (like customers, partners, or connector products) to call a Synerion Agile API to get or post data.

The API can be used for the following major use cases:

1. Get employee’s basic and extended profile information, such as, employee’s personal details, job costing, work rule, absences, schedule, and benefit package. Other extended information includes hire date, probation date, home & corporate address details, public, corporate & private information.
2. Get information on employee’s work time and labor costing data.
3. Retrieve information on punches such as original punch type, time & date, jobs & departments, and any modified punches with details on punch time, date & punch type.
4. Customer API can also be used to submit the employee time and attendance and costing punches.

Collection of API’s

• API authentication
• Daily time transactions and costing time transactions
• Employee profiles and employee profiles extended
• Get punches
• Grosvenor – punch and employees

API documentation link: https://api-swagger.synerionagile.com/

Base/Parent url: https://api.synerionagile.com/

API Authentication

Synerion API uses Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources.

An API service user is created to use for authentication purposes. This user is authorized to have visibility to all departments and employees.

Endpoint:

Description:

This API is used to authenticate the API service user and generates the JWT token. This generated token is valid for 60 minutes. Once expired, the user must re-authenticate by making another call to the authentication endpoint to obtain a fresh token. This ensures secure access to the APIs and prevents unauthorized access through expired tokens.

Request Parameters:

Parameter name	Type, mandatory/optional, header/Query Params	Description
AppRegion	string, required, header	Use ‘CAE’ for Canada Use ‘USE2’ for United States
Content-Type	String, required, header	Use application/json

Request Body:

NOTE: Credentials and API key, required for accessing the APIs, will be provided by Synerion

Response:

Response Codes:

Postman Example(s)

Authentication

1. POST https://api.synerionagile.com/v1/Authentication/Login

2. Add a Request Header

AppRegion –> CAE or USE2

3. Add a Request Body

4. [Optionally] store the bearer token for subsequent calls

Add this script in the Scripts tab to store token in the “bearer_token” environment variable. You may need to create this environment variable first.

Get Employees basic

Note: The authentication token and AppRegion header MUST be included with ALL API calls.

Tip: It’s best to generate a new auth token before making an API call to avoid expiration issues.

Employee Profiles

Employee Profiles endpoints are used to extract the employee profile information. Employee profile has two below endpoints:

Note: These endpoints respect the department and employee visibility. The API service user has full visibility to all departments that existed at the time of the service user registration. For any newly created departments, you may need to contact the support team to adjust the service user’s department visibility.

Basic info

Endpoint:

Description:

This endpoint gets a list of employee profile information. This list is paginated. This API returns the basic information of an employee (as mentioned in below response)

Required Permissions:

Base permission: FeatureEmployee Export

Additional Field Level Permissions And System Settings:

Permissions	Description
Base_permission & FeatureEmployee Profile General	It returns employee’s info including Name, employee code, payroll code, department name & number, and hire date
Base_permission & FeatureJob Costing function & system setting: Limit by NumberOfCargoValue	It returns all jobs and job values
Base_permission & JoinEmployeeBadge-View	It returns the current badge
Base_permission & FeatureEmployee Profile Work Rule	It returns the default absence, holiday schedule, current work rule, current period selection, and benefit package
Base_permission & FeatureEmployee Profile Rates	It returns the current rate, rate start date, job title and job description
Base_permission & FeatureEmployee Profile HR Profile	It returns the active status, part-time, export to payroll, and effective start date

Request Parameters:

Parameter name	Type, mandatory/optional, header/Query Params	Description
AppRegion	string, required, header	Use ‘CAE’ for Canada Use ‘USE2’ for United States
Authorization	string, required, header	The authorization token, returned by /v1/authentication/login, required to send this bearer token to the request
EmployeeCodes	String, optional, query params	Filter the punches by employee code(s)
DepartmentNumbers	String, optional, query params	Filter the punches by department number(s)
Page	String, optional, query params	The current page to get the paginated list
PerPage	String, optional, query params	The number of records to display per page

Response:

Response Codes:

Employee Profiles Extended

Endpoint:

Description:

This endpoint provides a list of employee profiles with extended information, for example, end of probation, hire date, termination date, review dates, gender, marital status, number of dependencies and authorizations, and personal and corporate information.

Request Parameters:

Parameter name	Type, mandatory/optional, header/Query Params	Description
AppRegion	string, required, header	Use ‘CAE’ for Canada Use ‘USE2’ for United States
Authorization	string, required, header	The authorization token, returned by /v1/authentication/login, required to send this bearer token to the request
EmployeeCodes	String, optional, query params	Filter the punches by employee code(s)
DepartmentNumbers	String, optional, query params	Filter the punches by department number(s)
Page	String, optional, query params	The current page to get the paginated list
PerPage	String, optional, query params	The number of records to display per page

Response:

Response Codes:

Daily Transaction APIs

Daily transaction APIs are useful endpoints to retrieve the employee’s job information such as schedule info, punch-in & out, jobs, durations, rates, costing transactions, absence and memos. The API will also exclude blank days (e.g., weekends).

Daily transaction has below 2 endpoints:

• /v1/Daily/TimeTransactions
• /v1/Daily/CostingTimeTransactions

Daily Time Transaction

Endpoint:

Description:

This endpoint provides a daily breakdown of employee’s shift information along with hours breakdown by time category.

Grouping:
The transactions are grouped by

1. Shiftmatch date
2. Time category

Request Parameters:

Parameter name	Type, mandatory/optional, header/Query Params	Description
AppRegion	string, required, header	Use ‘CAE’ for Canada Use ‘USE2’ for United States
Authorization	string, required, header	The authorization token, returned by /v1/authentication/login, required to send this bearer token to the request
StartDate	String(date-time), optional, query params	The current date will be used if omitted. (date format example: 2024-03-01)
EndDate	String(date-time), optional, query params	The current date will be used if omitted. (date format example: 2024-03-01)
EmployeeCodes	String, optional, query params	Filter the punches by employee code(s)
TcgFr	String, optional, query params	The time category group in French to search on
TcgEn	String, optional, query params	The time category group in English to search on
TcgSp	String, optional, query params	The time category group in Spanish to search on
DepartmentNumbers	String, optional, query params	Filter the punches by department number(s)
Page	String, optional, query params	The current page to get the paginated list
PerPage	String, optional, query params	The number of records to display per page

Response:

Response Codes:

Daily Costing Time Transactions

Endpoint:

Description:

With this endpoint, the user will get the information about time transaction allocation which are broken down based on their worked departments and job costing.

Grouping:
The transactions are grouped by

1. Shiftmatch date
2. Time category
3. Worked department and jobs

Request Parameters:

Parameter name	Type, mandatory/optional, header/Query Params	Description
AppRegion	string, required, header	Use ‘CAE’ for Canada Use ‘USE2’ for United States
Authorization	string, required, header	The authorization token, returned by /v1/authentication/login, required to send this bearer token to the request
StartDate	String(date-time), optional, query params	The current date will be used if omitted. (date format example: 2024-03-01)
EndDate	String(date-time), optional, query params	The current date will be used if omitted. (date format example: 2024-03-01)
EmployeeCodes	String, optional, query params	Filter the punches by employee code(s)
TcgFr	String, optional, query params	The time category group in French to search on
TcgEn	String, optional, query params	The time category group in English to search on
TcgSp	String, optional, query params	The time category group in Spanish to search on
DepartmentNumbers	String, optional, query params	Filter the punches by department number(s)
Page	String, optional, query params	The current page to get the paginated list
PerPage	String, optional, query params	The number of records to display per page

Response:

Response Codes:

2.4 Punch

Punch

Endpoint:

Description:

This endpoint will provide the list of punches with original and modified values. Original punches contain the punches that originated from the terminal. Modified punches include missing and updated punches.

Request Parameters:

Parameter name	Type, mandatory/optional, header/Query Params	Description
AppRegion	string, required, header	Use ‘CAE’ for Canada Use ‘USE2’ for United States
Authorization	string, required, header	The authorization token, returned by /v1/authentication/login, required to send this bearer token to the request.
PunchTypes	String, optional, query params	A list of punch type and can have one or more values (In, Out, Break Begin, Break End, Department, Job)
StartDate	String(date-time), optional, query params	The current date will be used if omitted. (date format example: 2024-03-01)
EndDate	String(date-time), optional, query params	The current date will be used if omitted. (date format example: 2024-03-01)
EmployeeCodes	String, optional, query params	Filter the punches by employee code(s)
DepartmentNumbers	String, optional, query params	Filter the punches by department number(s)
Page	String, optional, query params	The current page to get the paginated list
PerPage	String, optional, query params	The number of records to display per page

Response:

Response Codes:

Grosvenor

Grosvenor endpoints help our customers to post punch requests to the system and use it to get a list of employees. Grosvenor has two below endpoints:

Grosvenor Punch

Endpoint:

Description:

This endpoint helps the users to submit the employee’s punches by providing information such as employee id, unique key, badge, punching info (punch type and punch time), and job values in the payload. These are used for clock integration. The API will perform some basic checks to ensure the required fields have been submitted and will return a corresponding response.

Required fields: For attendance punches (IN, OUT, BB, BE) Badge, Punch time, Punch type, Terminal and Unique key are required fields. Additionally, for department punches, punch type must be “DEPT” and department number must be provided in chvalue1. For job punches, punch type must be “JOB” and job values must be provided in chvalue1 to chvalue6.

Request Parameters:

Parameter name	Type, mandatory/optional, header/Query Params	Description
AppRegion	string, required, header	Use ‘CAE’ for Canada Use ‘USE2’ for United States
Authorization	string, required, header	The authorization token, returned by /v1/authentication/login, required to send this bearer token to the request.
Content-Type	String, required, header	Use application/json

Note:

Punch time format: “yyyy-MM-ddTHH:mm:00zzz” (Note: seconds should always be 00)

Punch type abbreviations:

“IN” for In punches

“OUT” for Out punches

“BB” for Break Begin punches

“BE” for Break End punches

“DEPT” for Department Punch punches

“JOB” for Job Punch punches

Request Body:

Response Codes:

Grosvenor Employee API

Endpoint:

Description:

This endpoint returns all the active employees for the purposes of integrating with the terminals (physical and virtual clocks).

Request Parameters:

Parameter name	Type, mandatory/optional, header/Query Params	Description
AppRegion	string, required, header	Use ‘CAE’ for Canada Use ‘USE2’ for United States
Authorization	string, required, header	The authorization token, returned by /v1/authentication/login, required to send this bearer token to the request.

Response:

Response Codes:

———****———