Punches
Web services for Y-Time applications
Base URL: /domains/erp/hr/punches
Version: v1
Summary
| Path | Operation | Description |
|---|---|---|
| /{byu_id} | POST | |
| PUT | ||
| /{byu_id},{employee_record} | GET | |
| /{byu_id},{employee_record},{punch_date},{sequence_number} | DELETE |
Paths
POST /{byu_id}
Creates a punch record in TL_RPTD_TIME
application/json application/xml
Punch Information
| byu_id | The nine-digit computer-generated ID assigned to each employee | path | string , must match ^[0-9]{9}$ | #/parameters/byu_id |
Uses default content-types: application/json application/xml
- 200 OK
-
The timesheet for the employee
Example for application/json{
"byu_id": "999999999",
"international": false,
"jobs": [
{
"clock_in": false,
"employee_record": "0",
"full_part_time": "P",
"job_code_description": "Project Assistant",
"message": "This account code is currently inactive. Please contact your supervisor to update the account code",
"operating_unit": "R5422011",
"period_subtotal": "00:00",
"physical_facilities": false,
"valid_account": false,
"weekly_subtotal": "00:00"
},
{
"clock_in": false,
"employee_record": "1",
"full_part_time": "P",
"job_code_description": "Research Assistant",
"operating_unit": "11233010",
"period_subtotal": "51:41",
"physical_facilities": false,
"valid_account": true,
"weekly_subtotal": "51:41"
}
],
"period_total": "51:41",
"weekly_total": "51:41"
} - 400 Bad Request #/responses/400
-
Invalid Request - unable to interpret request
Example for application/json{
"clock_in": true,
"employee_record": 0,
"punch_date": "2018-05-21",
"punch_time": "08:00:00",
"reason": "Error - You cannot create a punch at a time where another punch already exists. Please modify your punch time and try again"
} - 401 Unauthorized #/responses/401
-
Authentication required to access data
- 403 Forbidden #/responses/403
-
Access denied to protected data
- 500 Internal Server Error #/responses/500
-
Internal Server Error - Error occurred that wasn't the user's fault
- 504 Gateway Timeout #/responses/504
-
Gateway Timeout
- default #/responses/default
-
Unexpected error
PUT /{byu_id}
Correct an exception
application/json application/xml
Punch Information
| byu_id | The nine-digit computer-generated ID assigned to each employee | path | string , must match ^[0-9]{9}$ | #/parameters/byu_id |
Uses default content-types: application/json application/xml
- 200 OK
-
Exception was corrected successfully.
Example for application/json{
"response": {
"status": "Success"
}
} - 400 Bad Request #/responses/400
-
Invalid Request - unable to interpret request
Example for application/json{
"clock_in": true,
"employee_record": 0,
"punch_date": "2018-05-21",
"punch_time": "08:00:00",
"reason": "Error - You cannot create a punch at a time where another punch already exists. Please modify your punch time and try again"
} - 401 Unauthorized #/responses/401
-
Authentication required to access data
- 403 Forbidden #/responses/403
-
Access denied to protected data
- 500 Internal Server Error #/responses/500
-
Internal Server Error - Error occurred that wasn't the user's fault
- 504 Gateway Timeout #/responses/504
-
Gateway Timeout
- default #/responses/default
-
Unexpected error
GET /{byu_id},{employee_record}
Get punches for a job from TL_RPTD_TIME
application/json
| byu_id | The nine-digit computer-generated ID assigned to each employee | path | string , must match ^[0-9]{9}$ | #/parameters/byu_id |
| employee_record | Employee Record Number | path | integer (up to 3 chars) | #/parameters/employee_record |
Uses default content-types: application/json application/xml
- 200 OK
-
Service request is OK and the list of punches is in the response.
Example for application/json[
{
"date": "2018-05-21",
"has_exception": true,
"other_hours": "--:--",
"punched_hours": "--:--",
"punches": [
{
"clock_in": true,
"deletable_pair": 1,
"hours_worked": "6",
"punch_time": "08:00:00",
"sequence_number": 1
},
{
"clock_in": true,
"deletable_pair": 1,
"hours_worked": "5.91667",
"punch_time": "08:05:00",
"sequence_number": 4
},
{
"clock_in": false,
"deletable_pair": 0,
"hours_worked": "0",
"punch_time": "14:00:00",
"sequence_number": 3
}
]
},
{
"date": "2018-05-22",
"has_exception": true,
"other_hours": "--:--",
"punched_hours": "--:--",
"punches": [
{
"clock_in": true,
"punch_time": ""
},
{
"clock_in": false,
"deletable_pair": 0,
"hours_worked": "0",
"punch_time": "12:00:00",
"sequence_number": 2
}
]
},
{
"date": "2018-05-23",
"has_exception": true,
"other_hours": "--:--",
"punched_hours": "--:--",
"punches": [
{
"clock_in": true,
"deletable_pair": 0,
"hours_worked": "0.0001",
"punch_time": "08:00:00",
"sequence_number": 1
},
{
"clock_in": false,
"punch_time": ""
}
]
},
{
"date": "2018-05-24",
"has_exception": true,
"other_hours": "--:--",
"punched_hours": "--:--",
"punches": [
{
"clock_in": true,
"deletable_pair": 0,
"hours_worked": "0.0001",
"punch_time": "08:00:00",
"sequence_number": 1
},
{
"clock_in": true,
"deletable_pair": 0,
"hours_worked": "0.0001",
"punch_time": "12:00:00",
"sequence_number": 2
},
{
"clock_in": false,
"punch_time": ""
}
]
},
{
"date": "2018-05-25",
"has_exception": false,
"other_hours": "01:00",
"punched_hours": "03:30",
"punches": [
{
"clock_in": true,
"deletable_pair": 0,
"hours_worked": "3.5",
"punch_time": "08:00:00",
"sequence_number": 1
},
{
"clock_in": false,
"deletable_pair": 0,
"hours_worked": "0",
"punch_time": "11:30:00",
"sequence_number": 2
}
]
}
] - 400 Bad Request #/responses/400
-
Invalid Request - unable to interpret request
Example for application/json{
"clock_in": true,
"employee_record": 0,
"punch_date": "2018-05-21",
"punch_time": "08:00:00",
"reason": "Error - You cannot create a punch at a time where another punch already exists. Please modify your punch time and try again"
} - 401 Unauthorized #/responses/401
-
Authentication required to access data
- 403 Forbidden #/responses/403
-
Access denied to protected data
- 500 Internal Server Error #/responses/500
-
Internal Server Error - Error occurred that wasn't the user's fault
- 504 Gateway Timeout #/responses/504
-
Gateway Timeout
- default #/responses/default
-
Unexpected error
DELETE /{byu_id},{employee_record},{punch_date},{sequence_number}
Deletes the specified punch
application/json
| byu_id | The nine-digit computer-generated ID assigned to each employee | path | string , must match ^[0-9]{9}$ | #/parameters/byu_id |
| employee_record | Employee Record Number | path | integer (up to 3 chars) | #/parameters/employee_record |
| punch_date | Date of Punch in format YYYY-MM-DD | path | string (date) | #/parameters/punch_date |
| sequence_number | Sequence Number | path | integer (up to 15 chars) | #/parameters/sequence_number |
Uses default content-types: application/json application/xml
- 200 OK
-
Service request is OK and the punch was deleted.
- 400 Bad Request #/responses/400
-
Invalid Request - unable to interpret request
Example for application/json{
"clock_in": true,
"employee_record": 0,
"punch_date": "2018-05-21",
"punch_time": "08:00:00",
"reason": "Error - You cannot create a punch at a time where another punch already exists. Please modify your punch time and try again"
} - 401 Unauthorized #/responses/401
-
Authentication required to access data
- 403 Forbidden #/responses/403
-
Access denied to protected data
- 500 Internal Server Error #/responses/500
-
Internal Server Error - Error occurred that wasn't the user's fault
- 504 Gateway Timeout #/responses/504
-
Gateway Timeout
- default #/responses/default
-
Unexpected error
Parameter definitions
Response definitions
- 400
-
Invalid Request - unable to interpret request
Example for application/json{
"clock_in": true,
"employee_record": 0,
"punch_date": "2018-05-21",
"punch_time": "08:00:00",
"reason": "Error - You cannot create a punch at a time where another punch already exists. Please modify your punch time and try again"
} - 401
-
Authentication required to access data
- 403
-
Access denied to protected data
- 500
-
Internal Server Error - Error occurred that wasn't the user's fault
- 504
-
Gateway Timeout
- default
-
Unexpected error
Schema definitions
The nine-digit computer-generated ID assigned to each employee
- date: date
-
- has_exception: has_exception
-
- punches: punches
-
- punched_hours: punched_hours
-
- other_hours: other_hours
-
One of the punches in each set of punches with matching numbers can be deleted.
The number that corresponds to a particular job for an employee when they work multiple jobs concurrently on campus.
- timesheet: object
-
- status: status
-
Indicates that the employee has exception(s) on the indicated date (true) or not (false)
internet_address: string , must match ^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$
IP Address
- weekly_subtotal: weekly_subtotal
-
- period_subtotal: period_subtotal
-
- employee_record: employee_record
-
- job_code_description: job_code_description
-
- valid_account: valid_account
-
- clock_in: clock_in
-
- physical_facilities: physical_facilities
-
- full_part_time: full_part_time
-
- message: message
-
- operating_unit: operating_unit
-
The device name of the time clock submitting the punch.
longitude: string , must match ^-?((([1]?[0-7][0-9]|[1-9]?[0-9])\.{1}\d{1,7}$)|[1]?[1-8][0]\.{1}0{1,7})$
Longitude
A user-friendly message indicating why the employee is not able to clock in/out of a particular job.
An eight digit alphanumeric field that defines a financial reporting entity.
Aggregate of other time recorded for the day (sick, vacation, on-call, etc.). If the employee has any uncorrected exceptions it will display --:--
Aggregate of time worked for the period. If the employee has any uncorrected exceptions it will display --:--
Aggregate of time worked across all jobs for the period. If the employee has any uncorrected exceptions it will display --:--
Indicates if the job is in the physical facilities department (true) or not (false).
- punch_date: date
-
- punch_time: punch_time
-
- internet_address: internet_address
-
- latitude: latitude
-
- longitude: longitude
-
- time_collection_source: time_collection_source
-
- employee_record: employee_record
-
- clock_in: clock_in
-
- location_description: location_description
-
- punch_zone: punch_zone
-
- punch: post_punch
-
- timesheet: object
-
- weekly_total: weekly_total
-
- period_total: period_total
-
- byu_id: byu_id
-
- international: international
-
- jobs: jobs
-
- sequence_number: sequence_number
-
- punch_time: punch_time
-
- deletable_pair: deletable_pair
-
- hours_worked: hours_worked
-
- clock_in: clock_in
-
Time of Punch in format HH:MM:SS
punch_zone: string , must match ^(([+]((([0][0-9]|[1][0-3])[:][0-5][0-9])|(14[:]00)))|([-]((([0][0-9]|[1][01])[:][0-5][0-9])|(12[:]00))))$
The time zone offset where the device is physically located when making a punch.
Aggregate of time worked for the day based on In and Out punches. If the employee has any uncorrected exceptions it will display --:--
- punch_date: date
-
- punch_time: punch_time
-
- internet_address: internet_address
-
- time_collection_source: time_collection_source
-
- employee_record: employee_record
-
- clock_in: clock_in
-
- location_description: location_description
-
- punch_zone: punch_zone
-
- punch: put_punch
-
- reason: reason
-
- punch_date: date
-
- punch_time: punch_time
-
- clock_in: clock_in
-
- employee_record: employee_record
-
Indicates if the account associated with the job is active (true) or not (false). If false, a corresponding message property will be available to display to end users.
Aggregate of time worked for the week. If the employee has any uncorrected exceptions it will display --:--
