# Payroll Settings

## 1. Get All Contribution Settings

<mark style="color:green;">**GET**</mark>  `/api/contribution-settings`

### **Description:**&#x20;

Retrieves all contribution settings for the authenticated company.

### **Response:**

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

```json
{
  "message": "Contribution settings retrieved successfully",
  "data": [
    {
      "id": 1,
      "company_id": 123,
      "setting_1": "value",
      "setting_2": "value"
    }
  ]
}
```

{% endtab %}

{% tab title="500" %}
&#x20;**Internal Server Error**

```json
{
  "error": "An unexpected error occurred while retrieving contribution settings."
}
```

{% endtab %}
{% endtabs %}

***

## 2. Get Contribution Settings for a Specific Company

<mark style="color:green;">**GET**</mark> `/api/contribution-settings/{company_id}`

### **Description:**&#x20;

Retrieves contribution settings for a specific company by ID.

### **Path Parameters:**

| Parameter    | Type   | Description       |
| ------------ | ------ | ----------------- |
| `company_id` | String | ID of the company |

### **Response:**

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

```json
{
  "message": "Contribution settings retrieved successfully",
  "data": {
    "id": 1,
    "company_id": 123,
    "setting_1": "value",
    "setting_2": "value"
  }
}
```

{% endtab %}

{% tab title="400 " %}
**Bad Request**

```json
{
  "error": "Company ID is required."
}
```

{% endtab %}

{% tab title="404 " %}
**Not Found**

```json
{
  "error": "Contribution settings not found."
}
```

{% endtab %}
{% endtabs %}

***

## 3. Update Contribution Settings for a Company

<mark style="color:purple;">**PATCH**</mark>  `/api/contribution-settings/{company_id}`

### **Description:**&#x20;

Updates the contribution settings for a specific company by ID.

### **Path Parameters:**

| Parameter    | Type   | Description       |
| ------------ | ------ | ----------------- |
| `company_id` | String | ID of the company |

### **Body Parameters:**

| Parameter   | Type   | Description                            |
| ----------- | ------ | -------------------------------------- |
| `setting_1` | String | The setting value to update (optional) |
| `setting_2` | String | The setting value to update (optional) |

### **Response:**

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

```json
{
  "message": "Contribution settings updated successfully",
  "data": {
    "id": 1,
    "company_id": 123,
    "setting_1": "updated value",
    "setting_2": "updated value"
  }
}
```

{% endtab %}

{% tab title="400" %}
**Bad Request**

```json
{
  "error": "No data provided for update."
}
```

{% endtab %}

{% tab title="404 " %}
**Not Found**

```json
{
  "error": "Contribution settings not found."
}
```

{% endtab %}
{% endtabs %}

***

## 4. Get Contributions for a Company

<mark style="color:green;">**GET**</mark>  `/api/contributions/{company_id}`

### **Description:**&#x20;

Retrieves all contributions for a specific company, including custom contribution records.

### **Path Parameters:**

| Parameter    | Type   | Description       |
| ------------ | ------ | ----------------- |
| `company_id` | String | ID of the company |

### **Response:**

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

```json
{
  "message": "Contributions retrieved successfully",
  "data": [
    {
      "employee_id": 1,
      "contribution_details": "details",
      "custom_contribution_records": [
        {
          "name": "Custom Contribution",
          "employee_contribution": 100,
          "employer_contribution": 200
        }
      ]
    }
  ]
}
```

{% endtab %}

{% tab title="404" %}
**Not Found**

```json
{
  "error": "Company not found."
}
```

{% endtab %}
{% endtabs %}

***

## 5. Get Contributions for a User

<mark style="color:green;">**GET**</mark> `/api/contributions/user/{user_id}`

### **Description:**&#x20;

Retrieves all contributions for a specific user, including custom contribution records.

### **Path Parameters:**

| Parameter | Type   | Description    |
| --------- | ------ | -------------- |
| `user_id` | String | ID of the user |

### **Response:**

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

```json
{
  "message": "User contributions retrieved successfully",
  "data": [
    {
      "employee_id": 1,
      "contribution_details": "details",
      "custom_contribution_records": [
        {
          "name": "Custom Contribution",
          "employee_contribution": 100,
          "employer_contribution": 200
        }
      ]
    }
  ]
}
```

{% endtab %}

{% tab title="404" %}
**Not Found**

```json
{
  "error": "User not found."
}
```

{% endtab %}
{% endtabs %}

***

## 6. Get All Custom Contributions for a Company

<mark style="color:green;">**GET**</mark> `/api/custom-contributions/{company_id}`

### **Description:**&#x20;

Retrieves all custom contributions for a specific company.

### **Path Parameters:**

| Parameter    | Type   | Description       |
| ------------ | ------ | ----------------- |
| `company_id` | String | ID of the company |

### **Response:**

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

```json
{
    "message": "Custom contributions retrieved successfully",
    "data": [
        {
            "id": 38,
            "company_id": 1,
            "name": "Jinx",
            "type": "amount",
            "apply_to": "net_pay",
            "employee_responsibility": 1,
            "employer_responsibility": 0,
            "employee_value": "300.00",
            "employer_value": null,
            "frequency": "per_paystub",
            "created_at": "2024-09-12T20:13:10.000000Z",
            "updated_at": "2024-09-13T21:36:37.000000Z",
            "is_active": 0,
            "targets": [
                {
                    "id": 180,
                    "custom_contribution_id": 38,
                    "user_type_id": 5,
                    "user_id": null,
                    "created_at": "2024-09-13T21:36:37.000000Z",
                    "updated_at": "2024-09-13T21:36:37.000000Z"
                }
            ]
        },
        {
            "id": 39,
            "company_id": 1,
            "name": "Gang",
            "type": "percentage",
            "apply_to": "gross_pay",
            "employee_responsibility": 1,
            "employer_responsibility": 0,
            "employee_value": "0.00",
            "employer_value": "0.00",
            "frequency": null,
            "created_at": "2024-09-12T21:18:08.000000Z",
            "updated_at": "2024-09-12T21:19:17.000000Z",
            "is_active": 1,
            "targets": []
        },
        {
            "id": 51,
            "company_id": 1,
            "name": "Health Insurance",
            "type": "percentage",
            "apply_to": "gross_pay",
            "employee_responsibility": 1,
            "employer_responsibility": 1,
            "employee_value": "5.00",
            "employer_value": "10.00",
            "frequency": "per_paystub",
            "created_at": "2024-09-13T21:38:07.000000Z",
            "updated_at": "2024-09-13T21:38:07.000000Z",
            "is_active": 1,
            "targets": [
                {
                    "id": 181,
                    "custom_contribution_id": 51,
                    "user_type_id": 12,
                    "user_id": null,
                    "created_at": "2024-09-13T21:38:07.000000Z",
                    "updated_at": "2024-09-13T21:38:07.000000Z"
                },
                {
                    "id": 182,
                    "custom_contribution_id": 51,
                    "user_type_id": 5,
                    "user_id": null,
                    "created_at": "2024-09-13T21:38:07.000000Z",
                    "updated_at": "2024-09-13T21:38:07.000000Z"
                },
                {
                    "id": 183,
                    "custom_contribution_id": 51,
                    "user_type_id": null,
                    "user_id": 140,
                    "created_at": "2024-09-13T21:38:07.000000Z",
                    "updated_at": "2024-09-13T21:38:07.000000Z"
                }
            ]
        }
    ]
}
```

{% endtab %}

{% tab title="Second Tab" %}

{% endtab %}
{% endtabs %}

***

## 7. Get a Specific Custom Contribution

<mark style="color:green;">**GET**</mark> `/api/custom-contributions/{company_id}/{contribution_id}`

### **Description:**&#x20;

Retrieves details of a specific custom contribution by its ID.

### **Path Parameters:**

| Parameter         | Type   | Description                   |
| ----------------- | ------ | ----------------------------- |
| `company_id`      | String | ID of the company             |
| `contribution_id` | String | ID of the custom contribution |

### **Response:**

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

```json
{
  "message": "Custom contribution retrieved successfully",
  "data": {
    "id": 1,
    "name": "Health Insurance",
    "type": "percentage",
    "apply_to": "gross_pay"
  }
}
```

{% endtab %}

{% tab title="404" %}
&#x20;**Not Found**

```json
{
  "error": "Custom contribution not found."
}
```

{% endtab %}
{% endtabs %}

***

## 8. Create a New Custom Contribution

<mark style="color:green;">**POST**</mark> `/api/custom-contributions/{company_id}`

### **Description:**&#x20;

Creates a new custom contribution for a specific company.

### **Path Parameters:**

| Parameter    | Type   | Description       |
| ------------ | ------ | ----------------- |
| `company_id` | String | ID of the company |

### **Body Parameters:**

| Parameter        | Type    | Description                                                |
| ---------------- | ------- | ---------------------------------------------------------- |
| `name`           | String  | Name of the custom contribution (required)                 |
| `type`           | String  | Contribution type (`amount`, `percentage`) (required)      |
| `apply_to`       | String  | Apply to (`gross_pay`, `net_pay`) (required)               |
| `responsibility` | String  | Responsibility (`employee`, `employer`, `both`) (required) |
| `employee_value` | Numeric | Employee contribution value (optional)                     |
| `employer_value` | Numeric | Employer contribution value (optional)                     |
| `frequency`      | String  | Frequency (`per_paystub`, `one_time`) (required)           |
| `user_types`     | Array   | Array of user types (optional)                             |
| `users`          | Array   | Array of user emails (optional)                            |
| `is_active`      | Boolean | Active status (optional)                                   |

### **Response:**

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

```json
{
    "message": "Custom contribution created successfully",
    "data": {
        "company_id": 1,
        "name": "Health Insurance",
        "type": "percentage",
        "apply_to": "gross_pay",
        "employee_responsibility": true,
        "employer_responsibility": true,
        "employee_value": 5,
        "employer_value": 10,
        "frequency": "per_paystub",
        "is_active": true,
        "updated_at": "2024-09-13T21:38:07.000000Z",
        "created_at": "2024-09-13T21:38:07.000000Z",
        "id": 51,
        "targets": [
            {
                "id": 181,
                "custom_contribution_id": 51,
                "user_type_id": 12,
                "user_id": null,
                "created_at": "2024-09-13T21:38:07.000000Z",
                "updated_at": "2024-09-13T21:38:07.000000Z"
            },
            {
                "id": 182,
                "custom_contribution_id": 51,
                "user_type_id": 5,
                "user_id": null,
                "created_at": "2024-09-13T21:38:07.000000Z",
                "updated_at": "2024-09-13T21:38:07.000000Z"
            },
            {
                "id": 183,
                "custom_contribution_id": 51,
                "user_type_id": null,
                "user_id": 140,
                "created_at": "2024-09-13T21:38:07.000000Z",
                "updated_at": "2024-09-13T21:38:07.000000Z"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Second Tab" %}

```json
{
    "message": "Custom contribution created successfully",
    "data": {
        "company_id": 1,
        "name": "Health Insurance",
        "type": "percentage",
        "apply_to": "gross_pay",
        "employee_responsibility": true,
        "employer_responsibility": true,
        "employee_value": 5,
        "employer_value": 10,
        "frequency": "per_paystub",
        "is_active": true,
        "updated_at": "2024-09-13T21:38:07.000000Z",
        "created_at": "2024-09-13T21:38:07.000000Z",
        "id": 51,
        "targets": [
            {
                "id": 181,
                "custom_contribution_id": 51,
                "user_type_id": 12,
                "user_id": null,
                "created_at": "2024-09-13T21:38:07.000000Z",
                "updated_at": "2024-09-13T21:38:07.000000Z"
            },
            {
                "id": 182,
                "custom_contribution_id": 51,
                "user_type_id": 5,
                "user_id": null,
                "created_at": "2024-09-13T21:38:07.000000Z",
                "updated_at": "2024-09-13T21:38:07.000000Z"
            },
            {
                "id": 183,
                "custom_contribution_id": 51,
                "user_type_id": null,
                "user_id": 140,
                "created_at": "2024-09-13T21:38:07.000000Z",
                "updated_at": "2024-09-13T21:38:07.000000Z"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

***

## 9. Update an Existing Custom Contribution

<mark style="color:blue;">**PUT**</mark>/<mark style="color:purple;">PATCH</mark>  `/api/custom-contributions/{company_id}/{contribution_id}`

### **Description:**&#x20;

Updates an existing custom contribution.

### **Path Parameters:**

| Parameter         | Type   | Description                   |
| ----------------- | ------ | ----------------------------- |
| `company_id`      | String | ID of the company             |
| `contribution_id` | String | ID of the custom contribution |

### **Body Parameters:**

| Parameter        | Type    | Description                                                |
| ---------------- | ------- | ---------------------------------------------------------- |
| `name`           | String  | Name of the custom contribution (optional)                 |
| `type`           | String  | Contribution type (`amount`, `percentage`) (optional)      |
| `apply_to`       | String  | Apply to (`gross_pay`, `net_pay`) (optional)               |
| `responsibility` | String  | Responsibility (`employee`, `employer`, `both`) (optional) |
| `employee_value` | Numeric | Employee contribution value (optional)                     |
| `employer_value` | Numeric | Employer contribution value (optional)                     |
| `frequency`      | String  | Frequency (`per_paystub`, `one_time`) (optional)           |
| `user_types`     | Array   | Array of user types (optional)                             |
| `users`          | Array   | Array of user emails (optional)                            |
| `is_active`      | Boolean | Active status (optional)                                   |

### **Response:**

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

```json
{
    "message": "Custom contribution updated successfully",
    "data": {
        "id": 38,
        "company_id": 1,
        "name": "Jinx",
        "type": "amount",
        "apply_to": "net_pay",
        "employee_responsibility": 1,
        "employer_responsibility": 0,
        "employee_value": "300.00",
        "employer_value": null,
        "frequency": "per_paystub",
        "created_at": "2024-09-12T20:13:10.000000Z",
        "updated_at": "2024-09-13T23:08:18.000000Z",
        "is_active": false
    }
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "error": "The company or contribution could not be found."
}
```

{% endtab %}
{% endtabs %}

***

## 10. Delete a Custom Contribution

&#x20;<mark style="color:red;">**DELETE**</mark> `/api/custom-contributions/{company_id}/{contribution_id}`

### **Description:**&#x20;

Deletes a custom contribution by its ID.

### **Path Parameters:**

| Parameter         | Type   | Description                   |
| ----------------- | ------ | ----------------------------- |
| `company_id`      | String | ID of the company             |
| `contribution_id` | String | ID of the custom contribution |

### **Response:**

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

```json
{
  "message": "Custom contribution deleted successfully"
}
```

{% endtab %}

{% tab title="404" %}

{% 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/payroll-settings.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.