Workwell Technologies Punch Reports API

openapi: 3.2.0
info:
  title: WorkWell Technologies API (uAttend) Punch Reports 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: Punch Reports
  description: Raw punch records across a date range
paths:
  /reports/punch:
    post:
      operationId: getPunchReport
      summary: Retrieve raw punch records across a date range
      description: Returns raw punch records for one or more users over a specified date range. Supports pagination for large result sets. If no user IDs are supplied, punches for all account users are returned. EndDate cannot be more than 3 months after StartDate — for larger ranges, make multiple requests with sequential date windows.
      tags:
      - Punch Reports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PunchReportRequest'
            examples:
              allUsersNoPaging:
                summary: All users, no paging
                value:
                  StartDate: '2024-01-01'
                  EndDate: '2024-01-31'
                  UsePaging: false
              specificUsersWithPaging:
                summary: Specific users, with paging
                value:
                  StartDate: '2024-01-01'
                  EndDate: '2024-03-31'
                  UserIds:
                  - 12345
                  - 67890
                  UsePaging: true
                  PageSize: 100
                  PageNumber: 0
      responses:
        '200':
          description: Punch records matching the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PunchReportResponse'
        '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:
  schemas:
    PunchReportResponse:
      type: object
      properties:
        Response:
          $ref: '#/components/schemas/ResponseObject'
        UsePaging:
          type: boolean
          description: Whether results were paginated.
        PageSize:
          type: integer
          description: Records per page.
        PageNumber:
          type: integer
          description: Current page (0-indexed).
        Total:
          type: integer
          description: Total matching records (when paging is off).
        UserIds:
          type: array
          description: User IDs included in results. Empty = all users.
          items:
            type: integer
            format: int64
        PunchReportLineItems:
          type: array
          description: The punch records.
          items:
            $ref: '#/components/schemas/PunchReportLineItem'
    ResponseObject:
      type: object
      description: Success flag and error detail.
      properties:
        Success:
          type: boolean
          description: true if the request completed without errors.
        Keys:
          type: object
          description: Error message keys paired to the field they relate to.
          additionalProperties:
            type: array
            items:
              type: string
        Messages:
          type: object
          description: Human-readable error messages paired to the field.
          additionalProperties:
            type: array
            items:
              type: string
    Error:
      type: object
      description: 'AWS API Gateway style error envelope, e.g. {"message": "Unauthorized"}.'
      properties:
        message:
          type: string
          description: Human-readable error message.
    PunchReportLineItem:
      type: object
      description: One record per in/out punch pair.
      properties:
        Id:
          type: integer
          format: int64
          description: Unique punch record identifier.
        UserId:
          type: integer
          description: User the punch belongs to.
        DepartmentId:
          type: integer
          description: Department the punch is attributed to.
        PaycodeId:
          type: integer
          description: 1=Regular, 2=Vacation, 3=Sick, 4=Holiday, 5=Other.
        PunchDay:
          type: integer
          description: Unix integer representing the workday date.
        PunchDate:
          type: string
          format: date
          description: Workday date.
        DayAbbrev:
          type: string
          description: 'Day of week abbreviation: Mon, Tue, Wed, Thu, Fri, Sat, Sun.'
        DepartmentCode:
          type: string
          description: Department code.
        DepartmentName:
          type: string
          description: Department name.
        FirstName:
          type: string
          description: User's first name.
        LastName:
          type: string
          description: User's last name.
        PayrollNumber:
          type: string
          description: Payroll number if present.
        InDate:
          type: string
          format: date
          description: Date of the in punch.
        InTime:
          type: string
          description: Time of the in punch.
        OutDate:
          type: string
          format: date
          description: Date of the out punch.
        OutTime:
          type: string
          description: Time of the out punch.
        Tot:
          type: string
          description: Total punch pair duration in HH:mm format (e.g., "4:15").
        InPunchLocation:
          type: string
          description: 'Where the in punch was made: IP address (web), timeclock ID, or geolocation (smartphone).'
        OutPunchLocation:
          type: string
          description: 'Where the out punch was made: IP address (web), timeclock ID, or geolocation (smartphone).'
        InPunchMethod:
          type: string
          description: 'Method of in punch: Time Clock, Manual Edit, Smartphone App, Website.'
        OutPunchMethod:
          type: string
          description: 'Method of out punch: Time Clock, Manual Edit, Smartphone App, Website.'
    PunchReportRequest:
      type: object
      required:
      - StartDate
      - EndDate
      - UsePaging
      properties:
        StartDate:
          type: string
          format: date
          description: Start of the date range (yyyy-mm-dd).
        EndDate:
          type: string
          format: date
          description: 'End of the date range (yyyy-mm-dd). Maximum range: 3 months from StartDate.'
        UserIds:
          type: array
          description: Filter to specific user IDs. Returns all users if omitted or empty.
          items:
            type: integer
        UsePaging:
          type: boolean
          description: Set to true to paginate results. Set to false to return all results at once.
        PageSize:
          type: integer
          description: Number of records per page. Required when UsePaging is true.
        PageNumber:
          type: integer
          description: 0-indexed page number to retrieve. Required when UsePaging is true.
  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'
    Unauthorized:
      description: Unauthorized — the x-api-key header is missing or the key value is incorrect.
      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'
    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'
    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'
    BadRequest:
      description: Bad Request — malformed JSON in the request body, or a required field is missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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.