Payroll Settings

1. Get All Contribution Settings

GET /api/contribution-settings

Description:

Retrieves all contribution settings for the authenticated company.

Response:

200

OK

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

500

Internal Server Error

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

---

2. Get Contribution Settings for a Specific Company

GET /api/contribution-settings/{company_id}

Description:

Retrieves contribution settings for a specific company by ID.

Path Parameters:

Parameter	Type	Description
company_id	String	ID of the company

Response:

200

OK

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

400

Bad Request

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

404

Not Found

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

---

3. Update Contribution Settings for a Company

PATCH /api/contribution-settings/{company_id}

Description:

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:

200

OK

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

400

Bad Request

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

404

Not Found

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

---

4. Get Contributions for a Company

GET /api/contributions/{company_id}

Description:

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

Path Parameters:

Parameter	Type	Description
company_id	String	ID of the company

Response:

200

OK

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

404

Not Found

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

---

5. Get Contributions for a User

GET /api/contributions/user/{user_id}

Description:

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

Path Parameters:

Parameter	Type	Description
user_id	String	ID of the user

Response:

200

OK

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

404

Not Found

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

---

6. Get All Custom Contributions for a Company

GET /api/custom-contributions/{company_id}

Description:

Retrieves all custom contributions for a specific company.

Path Parameters:

Parameter	Type	Description
company_id	String	ID of the company

Response:

200

OK

{
    "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"
                }
            ]
        }
    ]
}

Second Tab

---

7. Get a Specific Custom Contribution

GET /api/custom-contributions/{company_id}/{contribution_id}

Description:

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:

200

OK

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

404

Not Found

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

---

8. Create a New Custom Contribution

POST /api/custom-contributions/{company_id}

Description:

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:

201

Created

{
    "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"
            }
        ]
    }
}

Second Tab

{
    "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"
            }
        ]
    }
}

---

9. Update an Existing Custom Contribution

PUT/PATCH /api/custom-contributions/{company_id}/{contribution_id}

Description:

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:

200

OK:

{
    "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
    }
}

404

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

---

10. Delete a Custom Contribution

DELETE /api/custom-contributions/{company_id}/{contribution_id}

Description:

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:

200

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

404