Workwell Technologies Punch Reports API

openapi: 3.0.3
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. All endpoints use HTTPS and are authenticated via an API key passed in the x-api-key request header. API keys are account-scoped — they grant access to all data within your uAttend account. Request bodies are JSON objects; even when no parameters are needed, pass an empty JSON object. This OpenAPI was generated by API Evangelist from the provider's published API documentation (https://uattend.zendesk.com/hc/en-us/articles/48783008798875-uAttend-API); the provider does not publish a machine-readable spec.
  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:
    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.
    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.
  responses:
    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'
    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'
    BadRequest:
      description: Bad Request — malformed JSON in the request body, or a required field is missing.
      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'
  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.