Punches

Web services for Y-Time applications

More information: https://it.byu.edu
Contact Info: api@byu.edu

Base URL: /domains/erp/hr/punches

Version: v1

Default response content-types: application/json, application/xml
Schemes: https

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

byu_id byu_id

The nine-digit computer-generated ID assigned to each employee

path string , must match ^[0-9]{9}$
employee_record employee_record

Employee Record Number

path integer (up to 3 chars)
punch_date punch_date

Date of Punch in format YYYY-MM-DD

path string (date)
sequence_number sequence_number

Sequence Number

path integer (up to 15 chars)

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

byu_id: string , must match ^[0-9]{9}$

The nine-digit computer-generated ID assigned to each employee

clock_in: boolean

True for an in punch, False for an out punch.

date: string (date)

Date of Punch in format YYYY-MM-DD

dates: object

date: date
has_exception: has_exception
punches: punches
punched_hours: punched_hours
other_hours: other_hours

deletable_pair: integer

One of the punches in each set of punches with matching numbers can be deleted.

employee_record: integer (up to 3 chars)

The number that corresponds to a particular job for an employee when they work multiple jobs concurrently on campus.

error: object

timesheet: object
status: status

full_part_time: string , x ∈ { P , F }

Specifies if the employee is part-time (P) or full-time (F).

has_exception: boolean

Indicates that the employee has exception(s) on the indicated date (true) or not (false)

hours_worked: number (double)

The number of hours worked.

international: boolean

Indicates that the employee is a non-resident alien (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

job_code_description: string (up to 30 chars)

Department specified description of a specific job.

jobs: object

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

latitude: string , must match ^-?(\d\.\d{1,7}|[1-8]\d\.\d{1,7}|90\.0{1,7})$

Latitude

location_description: string (up to 30 chars)

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

message: string (up to 100 chars)

A user-friendly message indicating why the employee is not able to clock in/out of a particular job.

operating_unit: string (up to 8 chars)

An eight digit alphanumeric field that defines a financial reporting entity.

other_hours: string

Aggregate of other time recorded for the day (sick, vacation, on-call, etc.). If the employee has any uncorrected exceptions it will display --:--

period_subtotal: string

Aggregate of time worked for the period. If the employee has any uncorrected exceptions it will display --:--

period_total: string

Aggregate of time worked across all jobs for the period. If the employee has any uncorrected exceptions it will display --:--

physical_facilities: boolean

Indicates if the job is in the physical facilities department (true) or not (false).

post_punch: object

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

post_request: object

punch: post_punch

post_timesheet: object

timesheet: object
weekly_total: weekly_total
period_total: period_total
byu_id: byu_id
international: international
jobs: jobs

punch: object

sequence_number: sequence_number
punch_time: punch_time
deletable_pair: deletable_pair
hours_worked: hours_worked
clock_in: clock_in

punch_time: string , must match ^(?:2[0-3]|[01][0-9]):[0-5][0-9]:[0-5][0-9]$

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.

punched_hours: string

Aggregate of time worked for the day based on In and Out punches. If the employee has any uncorrected exceptions it will display --:--

punches: object[]

put_punch: object

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

put_request: object

punch: put_punch

put_response: object

timesheet: object
status: string

reason: string

sequence_number: integer (up to 15 chars)

status: object

reason: reason
punch_date: date
punch_time: punch_time
clock_in: clock_in
employee_record: employee_record

time_collection_source: string , x ∈ { MBL , WEB , CPI }

Punch Source

timesheet: object[]

valid_account: boolean

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.

weekly_subtotal: string

Aggregate of time worked for the week. If the employee has any uncorrected exceptions it will display --:--

weekly_total: string

Aggregate of time worked across all jobs for the week. If the employee has any uncorrected exceptions it will display --:--

Service Path: 
/domains/erp/hr/punches
Domain or University API: 
/domains/erp/hr/punches

Community

 

Don't see your question listed here? Ask!