POS Employees

Access employee information from your POS system, including roles, schedules, and access permissions.

Overview

The POS Employee API provides access to employee data stored in your POS system. Employee records contain essential information about staff members including their roles, contact information, and system access details.

Employee data is crucial for:

  • Tracking who performed actions (opened/closed tickets, applied discounts, etc.)
  • Managing permissions and access control
  • Reporting on employee performance
  • Integrating with scheduling and time tracking systems

API Endpoints

Retrieve Employees

Returns employee records for a specific location.

Method: GET

Endpoint: /pos/v2/{locationId}/employees

Authentication: Bearer token required

Retrieve all employees associated with a location. This endpoint provides comprehensive employee information including their roles and permissions.

Path Parameters

NameTypeDescription
locationId *integerThe unique identifier for the location

Query Parameters

NameTypeDescription
pageintegerPage number for pagination (default: 1)
pageSizeintegerNumber of results per page (default: 50, max: 100)
activebooleanFilter by active/inactive status
updatedAfterdatetimeFilter employees updated after this timestamp

Request

GET
/pos/v2/{locationId}/employees
curl -X GET https://conecto-api.shift4payments.com/pos/v2/12345/employees \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "results": [
    {
      "posRef": "EMP-12345",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "jane.smith@example.com",
      "phone": "+1234567890",
      "employeeNumber": "E-001",
      "jobTitle": "Server",
      "jobRef": "JOB-SERVER",
      "isActive": true,
      "hireDate": "2024-01-15",
      "locationId": 12345,
      "permissions": {
        "canVoidItems": true,
        "canApplyDiscounts": true,
        "canAccessReports": false,
        "canManageEmployees": false
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    {
      "posRef": "EMP-12346",
      "firstName": "John",
      "lastName": "Manager",
      "email": "john.manager@example.com",
      "phone": "+1234567891",
      "employeeNumber": "M-001",
      "jobTitle": "Manager",
      "jobRef": "JOB-MANAGER",
      "isActive": true,
      "hireDate": "2023-06-01",
      "locationId": 12345,
      "permissions": {
        "canVoidItems": true,
        "canApplyDiscounts": true,
        "canAccessReports": true,
        "canManageEmployees": true
      },
      "createdAt": "2023-06-01T09:00:00Z",
      "updatedAt": "2024-01-20T14:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 25
  }
}

Models

Employee

The main employee record containing personal information, job details, and permissions.

  • Name
    posRef
    Type
    string
    Description

    Unique POS system reference ID for the employee

  • Name
    firstName
    Type
    string
    Description

    Employee's first name

  • Name
    lastName
    Type
    string
    Description

    Employee's last name

  • Name
    email
    Type
    string
    Description

    Employee's email address

  • Name
    phone
    Type
    string
    Description

    Employee's phone number

  • Name
    employeeNumber
    Type
    string
    Description

    Employee number or ID used in the POS system

  • Name
    jobTitle
    Type
    string
    Description

    Employee's job title or role name

  • Name
    jobRef
    Type
    string
    Description

    Reference to the employee's job/role in the POS system

  • Name
    isActive
    Type
    boolean
    Description

    Whether the employee is currently active

  • Name
    hireDate
    Type
    date
    Description

    Date the employee was hired

  • Name
    terminationDate
    Type
    date
    Description

    Date the employee was terminated, if applicable

  • Name
    locationId
    Type
    integer
    Description

    Location ID where the employee works

  • Name
    pin
    Type
    string
    Description

    Employee PIN for POS system access (may be encrypted/hashed)

  • Name
    badgeNumber
    Type
    string
    Description

    Employee badge or ID card number

  • Name
    permissions
    Type
    object
    Description

    Object containing employee permissions and access levels

  • Name
    hourlyWage
    Type
    number
    Description

    Employee's hourly wage (if applicable)

  • Name
    salary
    Type
    number
    Description

    Employee's annual salary (if applicable)

  • Name
    createdAt
    Type
    datetime
    Description

    When the employee record was created

  • Name
    updatedAt
    Type
    datetime
    Description

    When the employee record was last updated

EmployeePermissions

Defines what actions an employee can perform in the POS system.

  • Name
    canVoidItems
    Type
    boolean
    Description

    Whether the employee can void items from tickets

  • Name
    canApplyDiscounts
    Type
    boolean
    Description

    Whether the employee can apply discounts

  • Name
    canAccessReports
    Type
    boolean
    Description

    Whether the employee can access reports

  • Name
    canManageEmployees
    Type
    boolean
    Description

    Whether the employee can manage other employees

  • Name
    canOpenCashDrawer
    Type
    boolean
    Description

    Whether the employee can manually open the cash drawer

  • Name
    canProcessRefunds
    Type
    boolean
    Description

    Whether the employee can process refunds

  • Name
    canModifyPrices
    Type
    boolean
    Description

    Whether the employee can modify item prices

  • Name
    canClockInOut
    Type
    boolean
    Description

    Whether the employee can clock in and out

Use Cases

Employee Tracking

Track which employees performed specific actions in your POS system:

  • Ticket Operations - See who opened, modified, or closed tickets
  • Discounts & Voids - Audit who applied discounts or voided items
  • Cash Drawer - Track cash drawer operations by employee
  • Time Cards - Link time card entries to employee records

Integration with Third-Party Systems

Employee data can be integrated with external systems:

  • Payroll Systems - Sync employee information for payroll processing
  • Scheduling Software - Import employee data for shift scheduling
  • HR Platforms - Maintain employee records across systems
  • Access Control - Manage physical access based on employee status

Reporting & Analytics

Employee data enables various reporting capabilities:

  • Sales Performance - Analyze sales by employee
  • Labor Costs - Calculate labor costs and efficiency
  • Compliance - Ensure proper access controls and audit trails
  • Productivity - Track employee activity and performance metrics

Best Practices

  • Name
    Data Privacy
    Description

    Handle employee data in compliance with employment laws and privacy regulations. Limit access to sensitive information like wages and personal contact details.

  • Name
    Synchronization
    Description

    Keep employee records synchronized between your system and the POS. Update employee status (active/inactive) promptly when employees are hired or terminated.

  • Name
    Permission Management
    Description

    Respect POS permission structures in your application. Don't attempt operations that an employee doesn't have permission to perform.

  • Name
    Inactive Employees
    Description

    Filter for active employees in most contexts, but retain inactive employee data for historical reporting and audit trails.

  • Name
    Error Handling
    Description

    Handle cases where employee references in tickets or other records may point to employees who no longer exist or are inactive.

Was this page helpful?