# Payroll Management

## **Get List of Paystubs**

<mark style="color:green;">`GET`</mark> `/api/paystubs`

### **Description:**

Returns a list of paystubs for the authenticated company.

### **Headers:**

<table><thead><tr><th width="335">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/json</code></td></tr><tr><td>Authorization</td><td><code>Bearer &#x3C;token></code></td></tr></tbody></table>

### Query Parameters:

<table><thead><tr><th>Name</th><th width="253">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>company_id</code></td><td>integer (optional)</td><td>ID of the company. Defaults to the authenticated company ID.</td></tr><tr><td><code>user_id</code></td><td>integer (optional)</td><td>Filter paystubs by a specific user (employee) ID.</td></tr><tr><td><code>transaction_id</code></td><td>string (optional)</td><td>Filter paystubs by a specific transaction ID.</td></tr><tr><td><code>status</code></td><td>string (optional)</td><td>Filter paystubs by their status (<code>paid</code>, <code>unpaid</code>, etc.).</td></tr><tr><td><code>page</code> </td><td>integer (optional)</td><td>Page number for pagination.</td></tr><tr><td><code>per_page</code></td><td>integer (optional)</td><td>Number of items per page (default is 10).</td></tr></tbody></table>

### **Response:**

{% tabs %}
{% tab title="200" %}

```json
{
    "message": "Paystubs retrieved successfully",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 1,
                "user_id": 1,
                "company_id": 1,
                "pay_period_start": "2023-01-01",
                "pay_period_end": "2023-01-15",
                "taxable_income": 5000.00,
                "reimbursements": 1000.00,
                "other_allowances": 500.00,
                "gross_pay": 6500.00,
                "net_pay": 4500.00,
                "tax_withheld": 500.00,
                "pension_contribution": 200.00,
                "nhf_contribution": 100.00,
                "nhis_contribution": 50.00,
                "other_deductions": 150.00,
                "status": "paid",
                "transaction_id": "COMPANYCODE-ABC123",
                "created_at": "2023-01-16T10:00:00Z",
                "updated_at": "2023-01-16T10:00:00Z",
                "user": {
                    "id": 1,
                    "first_name": "John",
                    "last_name": "Doe",
                    "email": "john.doe@example.com"
                    // ... other user fields
                },
                "contribution": {
                    "id": 1,
                    "employee_id": 1,
                    "company_id": 1,
                    "pay_period_start": "2023-01-01",
                    "pay_period_end": "2023-01-15",
                    "employee_pension_contribution": 200.00,
                    "employer_pension_contribution": 300.00,
                    "nhf_contribution": 100.00,
                    "pit_contribution": 500.00,
                    // ... other contribution fields
                    "custom_contribution_records": [
                        {
                            "id": 1,
                            "contribution_id": 1,
                            "user_id": 1,
                            "name": "Health Insurance",
                            "employee_contribution": 50.00,
                            "employer_contribution": 100.00,
                            "created_at": "2023-01-16T10:00:00Z",
                            "updated_at": "2023-01-16T10:00:00Z"
                        }
                        // ... other custom contributions
                    ]
                }
            }
            // ... other paystubs
        ],
        "first_page_url": "http://example.com/api/paystubs?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "http://example.com/api/paystubs?page=1",
        "next_page_url": null,
        "path": "http://example.com/api/paystubs",
        "per_page": 20,
        "prev_page_url": null,
        "to": 1,
        "total": 1
    }
}

```

{% endtab %}

{% tab title="400" %}

```json
{
    "error": "Validation error message here..."
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "error": "Unauthorized"
}
```

{% endtab %}

{% tab title="403" %}

```json
{
    "error": "You do not have permission to access this company's paystubs."
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "error": "Paystub or company not found."
}
```

{% endtab %}
{% endtabs %}

## Create a New Paystub

<mark style="color:green;">`POST`</mark> `/api/paystubs`

### **Description:**

Creates a new paystub for the authenticated company.

**Headers:**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

### **Body:**

<table><thead><tr><th>Name</th><th width="253">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td>ID of the user</td></tr><tr><td><pre><code>pay_period_start
</code></pre></td><td>string</td><td>The start date of the pay period</td></tr><tr><td><pre><code>pay_period_end
</code></pre></td><td>string</td><td>The end date of the pay period</td></tr><tr><td><pre><code>taxable_income
</code></pre></td><td>number</td><td>The taxable amount for the period</td></tr><tr><td><pre><code>reimbursements
</code></pre></td><td>number</td><td>Reimbursement for the period</td></tr><tr><td><pre><code>other_allowances
</code></pre></td><td>number</td><td>Other non taxable pay for the period</td></tr><tr><td><code>company_id</code></td><td>integer (optional)</td><td>ID of the company. Defaults to the authenticated company ID.</td></tr></tbody></table>

### **Request example:**

```json
{
    "paystubs": [
        {
            "id": 1,
            "pay_period_start": "2023-01-01",
            "pay_period_end": "2023-01-15",
            "taxable_income": 5000.00,
            "reimbursements": 1000.00,
            "other_allowances": 500.00
        }
    ]
}
```

### **Response example:**

{% tabs %}
{% tab title="201" %}

```json
{
    "message": "Paystub processing completed",
    "created_paystubs": [
        {
            "paystub": {
                "id": 1,
                "user_id": 1,
                "company_id": 1,
                "pay_period_start": "2023-01-01",
                "pay_period_end": "2023-01-15",
                "taxable_income": 5000.00,
                "reimbursements": 1000.00,
                "other_allowances": 500.00,
                "gross_pay": 6500.00,
                "net_pay": 4500.00,
                "tax_withheld": 500.00,
                "pension_contribution": 200.00,
                "nhf_contribution": 100.00,
                "nhis_contribution": 50.00,
                "other_deductions": 150.00,
                "status": "unpaid",
                "transaction_id": "COMPANYCODE-ABC123",
                "created_at": "2023-01-16T10:00:00Z",
                "updated_at": "2023-01-16T10:00:00Z"
            },
            "custom_contributions": [
                {
                    "id": 1,
                    "contribution_id": 1,
                    "user_id": 1,
                    "name": "Health Insurance",
                    "employee_contribution": 50.00,
                    "employer_contribution": 100.00,
                    "created_at": "2023-01-16T10:00:00Z",
                    "updated_at": "2023-01-16T10:00:00Z"
                }
                // ... other custom contributions
            ]
        },
        {
            "paystub": {
                "id": 2,
                "user_id": 2,
                "company_id": 1,
                "pay_period_start": "2023-01-01",
                "pay_period_end": "2023-01-15",
                "taxable_income": 6000.00,
                "reimbursements": 0.00,
                "other_allowances": 0.00,
                "gross_pay": 6000.00,
                "net_pay": 4800.00,
                "tax_withheld": 600.00,
                "pension_contribution": 240.00,
                "nhf_contribution": 120.00,
                "nhis_contribution": 60.00,
                "other_deductions": 180.00,
                "status": "unpaid",
                "transaction_id": "COMPANYCODE-DEF456",
                "created_at": "2023-01-16T10:00:00Z",
                "updated_at": "2023-01-16T10:00:00Z"
            },
            "custom_contributions": [
                {
                    "id": 2,
                    "contribution_id": 2,
                    "user_id": 2,
                    "name": "Retirement Fund",
                    "employee_contribution": 60.00,
                    "employer_contribution": 120.00,
                    "created_at": "2023-01-16T10:00:00Z",
                    "updated_at": "2023-01-16T10:00:00Z"
                }
                // ... other custom contributions
            ]
        }
    ],
    "failed_paystubs": [
        // ... any paystubs that failed to be created, along with error messages
    ]
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "error": "Unauthorized"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "error": "Bad Request"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gangmates.com/api-documentation/api-reference/payroll-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.