Skip to main content
Companies represent business entities in the system. Each company can have multiple employees and documents associated with it. Companies are also linked to orders for document generation and their corresponding transactions. All company operations require authentication.

​
Data Structure

{
  "id": 1,
  "site_id": 1,
  "user_id": 1,
  "name": "Acme Inc",
  "email": "[email protected]",
  "phone": "+1234567890",
  "ein": "12-3456789",
  "masked_ein": "XX-XXX6789",
  "address": {
    "address1": "123 Main St",
    "address2": "Suite 100",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  },
  "employees_count": 5,
  "documents_count": 10,
  "orders_count": 3,
  "total_spent": 299.97,
  "created_at": "2024-01-28T12:00:00Z",
  "updated_at": "2024-01-28T12:00:00Z"
}

​
List Companies

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

​
Available Filters

  • filter[name] - Filter by company name
  • filter[email] - Filter by company email
  • filter[total_spent_min] - Filter by minimum total spent amount
  • filter[total_spent_max] - Filter by maximum total spent amount
  • sort - Sort by field (e.g., name, -created_at, -total_spent)
  • include - Include related resources (e.g., employees, documents, orders)
  • per_page - Number of items per page (default: 15)

​
Create Company

Create a new company record. 
curl -X POST https://api.paystub.dev/companies \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json" \
-d '{
"name": "New Company Inc",
"email": "[email protected]",
"address1": "456 Business Ave",
"city": "Chicago",
"state": "IL",
"zip": "60601",
"country": "US"
}'

​
Update Company

Update an existing company’s information. 
curl -X PUT https://api.paystub.dev/companies/1 \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Company Name",
"email": "[email protected]"
}'

​
Delete Company

Delete a company and all associated records. 
curl -X DELETE https://api.paystub.dev/companies/1 \
-H "Authorization: Bearer your_token_here"

​
Relationships

  • Site: Each company belongs to a site
  • User: Each company belongs to a user who created it
  • Employees: A company can have multiple employees
  • Documents: A company can have multiple documents
  • Orders: A company can have multiple orders
  • Transactions: All transactions are associated with orders

​
Error Handling

  • 401 Unauthenticated - Invalid or missing token
  • 403 Unauthorized - Insufficient permissions
  • 404 Not Found - Company does not exist
  • 422 Validation Error - Invalid input data

​
Best Practices

  1. Always validate EIN format (XX-XXXXXXX)
  2. Use proper country codes (ISO 2-letter)
  3. Include complete address information
  4. Handle sensitive data (EIN) securely
  5. Monitor company spending limits
  6. Track order and transaction histo