Skip to main content
Employees are individuals associated with companies in the system. Each employee can have multiple documents (paystubs, W2s, etc.) linked to their profile. All employee operations require authentication.

​
Data Structure

{
  "id": 1,
  "site_id": 1,
  "user_id": 1,
  "company_id": 1,
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "email": "[email protected]",
  "phone": "+1234567890",
  "ssn": "123-45-6789",
  "masked_ssn": "XXX-XX-6789",
  "address": {
    "address1": "123 Main St",
    "address2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  },
  "additional_info": {},
  "earnings": {},
  "deductions": {},
  "documents_count": 5,
  "created_at": "2024-01-28T12:00:00Z",
  "updated_at": "2024-01-28T12:00:00Z",
  "relationships": {
    "site": {
      "data": { "id": 1, "type": "sites" }
    },
    "user": {
      "data": { "id": 1, "type": "users" }
    },
    "company": {
      "data": { "id": 1, "type": "companies" }
    },
    "documents": {
      "data": [
        { "id": 1, "type": "documents" },
        { "id": 2, "type": "documents" }
      ]
    }
  }
}

​
List Employees

Retrieve a paginated list of employees. 
curl https://api.paystub.dev/employees \
-H "Authorization: Bearer your_token_here"

​
Query Parameters

The API supports the following query parameters using Spatie Query Builder:

​
Filtering

  • Simple Filters:
GET /employees?filter[company_id]=1
GET /employees?filter[first_name]=John
GET /employees?filter[last_name]=Doe
GET /employees?filter[email][email protected]
  • Exact Filters:
GET /employees?filter[first_name:exact]=John
  • Partial Matching:
GET /employees?filter[first_name:contains]=Jo
  • Multiple Values:
GET /employees?filter[company_id]=1,2,3

​
Including Relationships

You can include related models in the response: 
GET /employees?include=company
GET /employees?include=company,documents
GET /employees?include=company.site
Available relationships:
  • site - The site this employee belongs to
  • user - The user who created this employee
  • company - The company this employee works for
  • documents - All documents associated with this employee

​
Sorting

Sort results by one or multiple fields: 
GET /employees?sort=first_name
GET /employees?sort=-created_at
GET /employees?sort=company_id,-last_name
Available sort fields:
  • first_name
  • last_name
  • email
  • created_at
  • updated_at
  • company_id

​
Selecting Fields

Select specific fields to return: 
GET /employees?fields[employees]=first_name,last_name,email
GET /employees?fields[employees]=first_name,last_name&fields[company]=name

​
Pagination

Control the number of results per page: 
GET /employees?per_page=25

​
Create Employee

Create a new employee record. 
curl -X POST https://api.paystub.dev/employees \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json" \
-d '{
"company_id": 1,
"first_name": "Jane",
"last_name": "Smith",
"email": "[email protected]",
"ssn": "987-65-4321",
"address1": "789 Work St",
"city": "Los Angeles",
"state": "CA",
"zip": "90001",
"country": "US"
}'

​
Validation Rules

FieldRules
company_idRequired, exists in companies table
first_nameRequired, string, max:255
last_nameRequired, string, max:255
emailRequired, email, max:255
ssnRequired, format: XXX-XX-XXXX
address1Required, string, max:255
cityRequired, string, max:255
stateRequired for US addresses
zipRequired, string, max:20
countryRequired, ISO 2-letter code

​
Update Employee

Update an existing employee’s information. 
curl -X PUT https://api.paystub.dev/employees/1 \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"phone": "+1987654321"
}'

​
Delete Employee

Delete an employee and their associated records. 
curl -X DELETE https://api.paystub.dev/employees/1 \
-H "Authorization: Bearer your_token_here"

​
Relationships

​
BelongsTo Relationships

  • site - The site this employee belongs to
  • user - The user who created this employee
  • company - The company this employee works for

​
HasMany Relationships

  • documents - All documents associated with this employee

​
Security Considerations

  1. SSN Protection
  • SSN is always masked in responses (XXX-XX-1234 format)
  • Full SSN is only visible during creation
  • SSN is encrypted at rest in the database
  • SSN is transmitted securely via HTTPS
  1. Access Control
  • Users can only access employees within their site
  • Company-level permissions restrict access to employees
  • Audit logs track all employee data access

​
Error Handling

​
HTTP Status Codes

  • 401 Unauthenticated
{
  "success": false,
  "message": "Unauthenticated."
}
  • 403 Unauthorized
{
  "success": false,
  "message": "You are not authorized to access this employee."
}
  • 404 Not Found
{
  "success": false,
  "message": "Employee not found."
}
  • 422 Validation Error
{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "ssn": ["Invalid SSN format."]
  }
}

​
Best Practices

  1. Data Validation
  • Always validate SSN format (XXX-XX-XXXX)
  • Verify email format and uniqueness
  • Validate phone numbers for proper format
  • Ensure address fields follow standards
  1. Security
  • Use HTTPS for all API calls
  • Implement rate limiting
  • Monitor failed access attempts
  • Regular security audits
  1. Performance
  • Use sparse fieldsets for large datasets
  • Include only needed relationships
  • Implement proper indexing
  • Cache frequently accessed data
  1. Compliance
  • Follow data privacy regulations
  • Implement data retention policies
  • Maintain audit trails
  • Regular compliance reviews