Workwell Technologies Timecards API

openapi: 3.2.0
info:
  title: WorkWell Technologies API (uAttend) Timecards API
  description: The WorkWell Technologies API allows you to programmatically retrieve employee, timecard, and punch data from your uAttend account.
  version: 1.0.0
  contact:
    name: WorkWell Technologies Support
    url: https://uattend.zendesk.com/hc/en-us
  x-apievangelist:
    generated: '2026-07-21'
    method: generated
    source: https://uattend.zendesk.com/hc/en-us/articles/48783008798875-uAttend-API
servers:
- url: https://api.workwelltech.com
security:
- ApiKeyAuth: []
tags:
- name: Timecards
  description: Per-user, per-pay-period timecards
paths:
  /timecards:
    post:
      operationId: getTimecard
      summary: Retrieve timecard data for a user and pay period
      description: Returns the timecard for a specified user. If no date is provided, the current pay period is returned. If a date is supplied, the timecard covering that date is returned. All time durations are strings in HH:mm format; dates are yyyy-mm-dd; punch times are 12-hour strings.
      tags:
      - Timecards
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTimecardRequest'
            examples:
              currentPayPeriod:
                summary: Current pay period
                value:
                  UserId: 12345
              specificPayPeriod:
                summary: Specific pay period (date within it)
                value:
                  UserId: 12345
                  Date: '2024-01-15'
      responses:
        '200':
          description: The timecard covering the requested pay period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTimeCardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    TooManyRequests:
      description: Too Many Requests — rate limit exceeded. Slow down request frequency and implement retry logic with exponential backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request — malformed JSON in the request body, or a required field is missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized — the x-api-key header is missing or the key value is incorrect.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not Found — the endpoint URL is incorrect. Verify the path matches exactly /user, /timecards, or /reports/punch.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error — an unexpected server-side error occurred. If this persists, contact WorkWell Technologies support with your request details and timestamp.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden — an AWS identity-based policy is blocking the request (IP/network restriction), the key lacks permission for the resource, or the endpoint URL is incorrect (Missing Authentication Token).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ExpenseCode:
      type: object
      description: An expense code available on the account.
      properties:
        Code:
          type: string
          description: Expense code.
    JobPunches:
      type: object
      properties:
        UserId:
          type: integer
          description: User identifier.
        PunchId:
          type: integer
          description: Punch identifier.
        JobId:
          type: integer
          description: Job identifier.
        JobNumber:
          type: string
          description: Job number.
        JobName:
          type: string
          description: Job name.
        JobDetailId:
          type: integer
          description: Job detail identifier.
        JobDetailName:
          type: string
          description: Job detail name.
        JobInDate:
          type: string
          description: Job in punch date.
        JobInTime:
          type: string
          description: Job in punch time.
        JobOutDate:
          type: string
          description: Job out punch date.
        JobOutTime:
          type: string
          description: Job out punch time.
        DepartmentId:
          type: integer
          description: Department identifier.
        JobDescription:
          type: string
          description: Job description.
        JobNote:
          type: string
          description: Job note.
        SubJobDetails:
          type: array
          description: Nested sub-job punch records.
          items:
            $ref: '#/components/schemas/JobPunches'
    Accrual:
      type: object
      properties:
        Code:
          type: string
          description: Benefit category code (e.g., "VAC", "SIC").
        Accrued:
          type: string
          description: Total accrued balance (HH:mm, e.g., "80:00").
        Used:
          type: string
          description: Hours used (HH:mm, e.g., "20:00").
        Available:
          type: string
          description: Remaining available balance (HH:mm, e.g., "60:00").
    Timecard:
      type: object
      description: 'Pay period totals. All time durations are strings in HH:mm format (40 hours = "40:00"). Pay codes: REG = Regular, OT1 = Overtime 1, OT2 = Overtime 2, VAC = Vacation, SIC = Sick, HOL = Holiday, OTH = Other.'
      properties:
        StartDate:
          type: string
          format: date
          description: Pay period start date.
        EndDate:
          type: string
          format: date
          description: Pay period end date.
        FirstName:
          type: string
          description: First name.
        LastName:
          type: string
          description: Last name.
        PayrollNumber:
          type: string
          description: Payroll number.
        WeekCount:
          type: integer
          description: Number of weeks in the pay period (1-6).
        Week1:
          type: string
          description: Total hours worked in week 1 (HH:mm). Unused weeks return "0:00".
        Week2:
          type: string
          description: Total hours worked in week 2 (HH:mm).
        Week3:
          type: string
          description: Total hours worked in week 3 (HH:mm).
        Week4:
          type: string
          description: Total hours worked in week 4 (HH:mm).
        Week5:
          type: string
          description: Total hours worked in week 5 (HH:mm).
        Week6:
          type: string
          description: Total hours worked in week 6 (HH:mm).
        RegularTime:
          type: string
          description: Total regular hours (HH:mm).
        Overtime1Time:
          type: string
          description: Total overtime 1 hours (HH:mm).
        Overtime2Time:
          type: string
          description: Total overtime 2 hours (HH:mm).
        VacationTime:
          type: string
          description: Total vacation hours (HH:mm).
        HolidayTime:
          type: string
          description: Total holiday hours (HH:mm).
        SickTime:
          type: string
          description: Total sick hours (HH:mm).
        OtherTime:
          type: string
          description: Total other hours (HH:mm).
        SumOfTotalHours:
          type: string
          description: Grand total of all pay code hours (HH:mm).
        RegularGrossPay:
          type: string
          description: Gross pay for regular time.
        Overtime1GrossPay:
          type: string
          description: Gross pay for overtime 1.
        Overtime2GrossPay:
          type: string
          description: Gross pay for overtime 2.
        VacationGrossPay:
          type: string
          description: Gross pay for vacation.
        HolidayGrossPay:
          type: string
          description: Gross pay for holiday.
        SickGrossPay:
          type: string
          description: Gross pay for sick time.
        OtherGrossPay:
          type: string
          description: Gross pay for other time.
        TotalGrossPay:
          type: string
          description: Total gross pay across all pay codes.
        EmployeeReferenceID:
          type: string
          description: Employee reference ID.
        ClientReferenceID:
          type: string
          description: Client reference ID.
        Workdays:
          type: array
          description: List of individual workday records.
          items:
            $ref: '#/components/schemas/Workday'
        Tips:
          type: array
          description: List of tip records.
          items:
            $ref: '#/components/schemas/Tip'
        Accruals:
          type: array
          description: List of benefit accrual balances.
          items:
            $ref: '#/components/schemas/Accrual'
    PunchPair:
      type: object
      description: One entry per in/out punch pair. The last punch pair of a day has IsLast = 1.
      properties:
        PunchId:
          type: string
          description: Unique punch identifier.
        Paycode:
          type: string
          description: Pay code (1=Regular, 6=Break, 7=Lunch).
        DepartmentName:
          type: string
          description: Department name for regular punches; "Break" or "Lunch" for paycodes 6/7.
        InDate:
          type: string
          description: In punch date (yyyy-mm-dd).
        OutDate:
          type: string
          description: Out punch date (yyyy-mm-dd).
        InTime:
          type: string
          description: In punch time (hh:mm AM/PM).
        OutTime:
          type: string
          description: Out punch time (hh:mm AM/PM).
        RegularHours:
          type: string
          description: Regular hours for this punch pair (HH:mm).
        Overtime1Hours:
          type: string
          description: Overtime 1 hours for this punch pair (HH:mm).
        Overtime2Hours:
          type: string
          description: Overtime 2 hours for this punch pair (HH:mm).
        VacationHours:
          type: string
          description: Vacation hours for this punch pair (HH:mm).
        HolidayHours:
          type: string
          description: Holiday hours for this punch pair (HH:mm).
        SickHours:
          type: string
          description: Sick hours for this punch pair (HH:mm).
        OtherHours:
          type: string
          description: Other hours for this punch pair (HH:mm).
        TotalHours:
          type: string
          description: Total hours for this punch pair (HH:mm).
        RegularGrossPay:
          type: number
          description: Gross pay — regular time.
        TotalGrossPay:
          type: number
          description: Total gross pay for this punch pair.
        Description:
          type: string
          description: Optional description.
        Note:
          type: string
          description: Optional note.
        IsLast:
          type: integer
          description: 1 if this is the last punch pair for the day.
    HomeDepartment:
      type: object
      description: Home department details.
      properties:
        DepartmentId:
          type: integer
          description: Department identifier.
        DepartmentName:
          type: string
          description: Department name.
    Department:
      type: object
      description: A department accessible to the user.
      properties:
        DepartmentId:
          type: integer
          description: Department identifier.
        DepartmentCode:
          type: string
          description: Department code.
        DepartmentName:
          type: string
          description: Department name.
    Error:
      type: object
      description: 'AWS API Gateway style error envelope, e.g. {"message": "Unauthorized"}.'
      properties:
        message:
          type: string
          description: Human-readable error message.
    TimecardPunchData:
      type: object
      description: Extended data grouped by date, available in the ExtendedPunchData list.
      properties:
        Date:
          type: string
          description: Date the records belong to (yyyy-mm-dd).
        PunchHistory:
          type: array
          description: Punch edit history for the day.
          items:
            type: object
        Tips:
          type: array
          description: Tip entries for the day.
          items:
            type: object
        JobPunches:
          type: array
          description: Job-specific punch records for the day.
          items:
            $ref: '#/components/schemas/JobPunches'
        Expenses:
          type: array
          description: Expense entries for the day.
          items:
            type: object
    JobSimple:
      type: object
      description: Job information.
      properties:
        JobID:
          type: integer
          description: Job identifier.
        JobNumber:
          type: string
          description: Job number.
        JobName:
          type: string
          description: Job name.
        JobDetails:
          type: array
          description: Job details.
          items:
            type: object
    Workday:
      type: object
      description: One entry per day that has punch activity.
      properties:
        Day1:
          type: string
          description: Day abbreviation (e.g., "Mon").
        Day2:
          type: string
          description: Short date (e.g., "11/30/19").
        Day3:
          type: string
          description: ISO date (e.g., "2019-11-30").
        RegularTime:
          type: string
          description: Daily regular hours (HH:mm).
        Overtime1Time:
          type: string
          description: Daily overtime 1 hours (HH:mm).
        Overtime2Time:
          type: string
          description: Daily overtime 2 hours (HH:mm).
        VacationTime:
          type: string
          description: Daily vacation hours (HH:mm).
        HolidayTime:
          type: string
          description: Daily holiday hours (HH:mm).
        SickTime:
          type: string
          description: Daily sick hours (HH:mm).
        OtherTime:
          type: string
          description: Daily other hours (HH:mm).
        PunchPairs:
          type: array
          description: List of individual in/out punch pairs for this day.
          items:
            $ref: '#/components/schemas/PunchPair'
    GetTimecardRequest:
      type: object
      required:
      - UserId
      properties:
        UserId:
          type: integer
          description: The ID of the user whose timecard to retrieve.
        Date:
          type: string
          format: date
          description: A date within the desired pay period (yyyy-mm-dd). Defaults to the current pay period if omitted.
    GetTimeCardResponse:
      type: object
      description: Top-level wrapper for a timecard response.
      properties:
        PayrollNumber:
          type: string
          description: Payroll number of the user.
        ApprovalVerbiage:
          type: string
          description: Approval status of the timecard.
        IsLock:
          type: integer
          description: 1 if the timecard is locked.
        FirstName:
          type: string
          description: First name.
        LastName:
          type: string
          description: Last name.
        StartDate:
          type: string
          format: date
          description: Pay period start date (yyyy-mm-dd).
        EndDate:
          type: string
          format: date
          description: Pay period end date (yyyy-mm-dd).
        CurrentPayPeriodStart:
          type: string
          description: Start of the current pay period.
        CurrentPayPeriodEnd:
          type: string
          description: End of the current pay period.
        Timecard:
          $ref: '#/components/schemas/Timecard'
        ExtendedPunchData:
          type: array
          description: Extended punch data grouped by date.
          items:
            $ref: '#/components/schemas/TimecardPunchData'
        Jobs:
          type: array
          description: Job information (JobID, JobNumber, JobName, JobDetails).
          items:
            $ref: '#/components/schemas/JobSimple'
        Departments:
          type: array
          description: Departments accessible to the user.
          items:
            $ref: '#/components/schemas/Department'
        ExpenseCodes:
          type: array
          description: Expense codes available.
          items:
            $ref: '#/components/schemas/ExpenseCode'
        HomeDepartment:
          $ref: '#/components/schemas/HomeDepartment'
    Tip:
      type: object
      properties:
        TipId:
          type: integer
          description: Unique tip identifier.
        TipCode:
          type: string
          description: Tip code.
        TotalMinutes:
          type: string
          description: Total minutes for the tip entry.
        TipDepartmentName:
          type: string
          description: Department associated with the tip.
        TotalTipMinute:
          type: string
          description: Total tip minutes.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Account-scoped API key provided by WorkWell Technologies support. Keys grant access to all data within your uAttend account and are active immediately upon issuance. To request a key, contact support with the system you are integrating, how you plan to use the data, and how often you plan to make requests. The API Gateway may additionally enforce IP-based access policies at the infrastructure level.