> This page is for version API + Legacy Read.
> For other versions, use one of these documentation indexes:
> - API (default): https://docs.getthera.com/api/llms.txt
> - API + Legacy Read: https://docs.getthera.com/api-legacy-read/llms.txt
> - API + Legacy Full: https://docs.getthera.com/api-legacy-full/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getthera.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getthera.com/_mcp/server.

# Get Contractor Fees

GET https://api.getthera.com/companies/{companyId}/fees/contractors

The contractor and US payroll subscription fees a company was charged for a range of months.
Each fee is filed under the month it covered, which is not always the month it was charged in.

Reference: https://docs.getthera.com/thera-api/company/contractor-fees-api/get-contractor-fees

## Authentication

- `X-Thera-API-Key` header (required) — API Key authentication via header

## Servers

- `https://api.getthera.com` (Production, default)
- `https://api.staging.getthera.com` (Staging)

## Request

### Path parameters

- `companyId` (string, required)

### Query parameters

- `fromMonth` (string, required) — First month of the range, as YYYY-MM, within the last 36 months counting the current one.
- `toMonth` (string, required) — Last month of the range, inclusive, as YYYY-MM. The range spans at most 12 months counting both ends, and cannot end in the future.

## Response

### 200

- `companyId` (string, required)
- `fromMonth` (string, required)
- `toMonth` (string, required)
- `totals` (list of FeeAmount, required) — Every contractor and US payroll fee in the range, one entry per currency.
- `months` (list of ContractorFeeMonth, required)
- `contractors` (list of ContractorFeeRow, required)
- `unattributedCharges` (list of UnattributedFeeCharge, required)
- `w2Charges` (list of W2FeeCharge, required) — US payroll subscription charges in the range, oldest first. Part of the totals.

## Types

### FeeAmount

An amount in minor units of the currency the company paid in.

- `amountMinor` (long, required)
- `currency` (string, required)

### ContractorFeeMonth

One month of the range. Months with no fees are included with empty totals.

- `month` (string, required)
- `contractorsCharged` (integer, required)
- `employeesCharged` (integer, required) — W-2 employees the month's US payroll subscription charges counted.
- `totals` (list of FeeAmount, required) — Contractor and US payroll fees for the month, one entry per currency.

### ContractorFeeRow

One contractor's fees across the range.

- `id` (string, required) — The contractor's user id, or the contract id when the contract no longer exists.
- `invoicesPaid` (integer, required) — Invoices paid to this contractor that fall in the same months as the fees.
- `charges` (list of ContractorFeeCharge, required) — Oldest first.
- `totals` (list of FeeAmount, required) — What this contractor's fees came to, one entry per currency.
- `name` (string, optional)
- `email` (string, optional)

### UnattributedFeeCharge

A monthly subscription charge whose contractors were not recorded. Only older charges are like this. Its amount is still part of the totals.

- `month` (string, required)
- `contractorCount` (integer, required)
- `amount` (FeeAmount, required) — An amount in minor units of the currency the company paid in.
- `chargedOn` (string, required)
- `paymentId` (string, required)

### W2FeeCharge

One monthly US payroll subscription charge: a company fee plus a fee for each W-2 employee counted. The run charges at the end of a month for the one before it.

- `month` (string, required) — The month the charge covered, as YYYY-MM.
- `chargedOn` (string, required) — The day the charge was raised, as YYYY-MM-DD.
- `paymentId` (string, required)
- `amount` (FeeAmount, required) — An amount in minor units of the currency the company paid in.
- `employees` (list of W2FeeEmployee, required) — Who was counted, by name. Empty for charges that did not record them.
- `employeeCount` (integer, optional) — Missing when the charge recorded no headcount, as manual charges don't.
- `companyFee` (FeeAmount, optional) — An amount in minor units of the currency the company paid in.
- `perEmployeeFee` (FeeAmount, optional) — An amount in minor units of the currency the company paid in.

### ContractorFeeCharge

One fee charged for one contractor.

- `month` (string, required) — The month the fee covered, as YYYY-MM. Since 17 July 2026 this is the month of the work the invoice was for. Before that it was the month the payment was made.
- `amount` (FeeAmount, required) — An amount in minor units of the currency the company paid in.
- `chargedOn` (string, required) — The day the payment carrying the fee was raised, as YYYY-MM-DD.
- `paymentId` (string, required)
- `billingMethod` (enum, required) — How a fee was collected, which also decides which receipt it appears on. PAYMENT_RUN fees were added to a payment to the contractor; MONTHLY_CYCLE fees were collected in the company's monthly subscription charge.
  - Allowed values: `PAYMENT_RUN`, `MONTHLY_CYCLE`

### W2FeeEmployee

One W-2 employee a US payroll subscription charge counted.

- `id` (string, required) — The employee's user id, or the contract id when the contract no longer exists.
- `name` (string, optional)
- `email` (string, optional)

## Examples

**Response**

```json
{
  "companyId": "companyId",
  "fromMonth": "fromMonth",
  "toMonth": "toMonth",
  "totals": [
    {
      "amountMinor": 1000000,
      "currency": "currency"
    },
    {
      "amountMinor": 1000000,
      "currency": "currency"
    }
  ],
  "months": [
    {
      "month": "month",
      "contractorsCharged": 1,
      "employeesCharged": 1,
      "totals": [
        {
          "amountMinor": 1000000,
          "currency": "currency"
        },
        {
          "amountMinor": 1000000,
          "currency": "currency"
        }
      ]
    },
    {
      "month": "month",
      "contractorsCharged": 1,
      "employeesCharged": 1,
      "totals": [
        {
          "amountMinor": 1000000,
          "currency": "currency"
        },
        {
          "amountMinor": 1000000,
          "currency": "currency"
        }
      ]
    }
  ],
  "contractors": [
    {
      "id": "id",
      "invoicesPaid": 1,
      "charges": [
        {
          "month": "month",
          "amount": {
            "amountMinor": 1000000,
            "currency": "currency"
          },
          "chargedOn": "chargedOn",
          "paymentId": "paymentId",
          "billingMethod": "PAYMENT_RUN"
        },
        {
          "month": "month",
          "amount": {
            "amountMinor": 1000000,
            "currency": "currency"
          },
          "chargedOn": "chargedOn",
          "paymentId": "paymentId",
          "billingMethod": "PAYMENT_RUN"
        }
      ],
      "totals": [
        {
          "amountMinor": 1000000,
          "currency": "currency"
        },
        {
          "amountMinor": 1000000,
          "currency": "currency"
        }
      ],
      "name": "name",
      "email": "email"
    },
    {
      "id": "id",
      "invoicesPaid": 1,
      "charges": [
        {
          "month": "month",
          "amount": {
            "amountMinor": 1000000,
            "currency": "currency"
          },
          "chargedOn": "chargedOn",
          "paymentId": "paymentId",
          "billingMethod": "PAYMENT_RUN"
        },
        {
          "month": "month",
          "amount": {
            "amountMinor": 1000000,
            "currency": "currency"
          },
          "chargedOn": "chargedOn",
          "paymentId": "paymentId",
          "billingMethod": "PAYMENT_RUN"
        }
      ],
      "totals": [
        {
          "amountMinor": 1000000,
          "currency": "currency"
        },
        {
          "amountMinor": 1000000,
          "currency": "currency"
        }
      ],
      "name": "name",
      "email": "email"
    }
  ],
  "unattributedCharges": [
    {
      "month": "month",
      "contractorCount": 1,
      "amount": {
        "amountMinor": 1000000,
        "currency": "currency"
      },
      "chargedOn": "chargedOn",
      "paymentId": "paymentId"
    },
    {
      "month": "month",
      "contractorCount": 1,
      "amount": {
        "amountMinor": 1000000,
        "currency": "currency"
      },
      "chargedOn": "chargedOn",
      "paymentId": "paymentId"
    }
  ],
  "w2Charges": [
    {
      "month": "month",
      "chargedOn": "chargedOn",
      "paymentId": "paymentId",
      "amount": {
        "amountMinor": 1000000,
        "currency": "currency"
      },
      "employees": [
        {
          "id": "id",
          "name": "name",
          "email": "email"
        },
        {
          "id": "id",
          "name": "name",
          "email": "email"
        }
      ],
      "employeeCount": 1,
      "companyFee": {
        "amountMinor": 1000000,
        "currency": "currency"
      },
      "perEmployeeFee": {
        "amountMinor": 1000000,
        "currency": "currency"
      }
    },
    {
      "month": "month",
      "chargedOn": "chargedOn",
      "paymentId": "paymentId",
      "amount": {
        "amountMinor": 1000000,
        "currency": "currency"
      },
      "employees": [
        {
          "id": "id",
          "name": "name",
          "email": "email"
        },
        {
          "id": "id",
          "name": "name",
          "email": "email"
        }
      ],
      "employeeCount": 1,
      "companyFee": {
        "amountMinor": 1000000,
        "currency": "currency"
      },
      "perEmployeeFee": {
        "amountMinor": 1000000,
        "currency": "currency"
      }
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.getthera.com/companies/companyId/fees/contractors"

querystring = {"fromMonth":"fromMonth","toMonth":"toMonth"}

headers = {"X-Thera-API-Key": "<apiKey>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.getthera.com/companies/companyId/fees/contractors?fromMonth=fromMonth&toMonth=toMonth';
const options = {method: 'GET', headers: {'X-Thera-API-Key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getthera.com/companies/companyId/fees/contractors?fromMonth=fromMonth&toMonth=toMonth"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Thera-API-Key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.getthera.com/companies/companyId/fees/contractors?fromMonth=fromMonth&toMonth=toMonth")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Thera-API-Key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.getthera.com/companies/companyId/fees/contractors?fromMonth=fromMonth&toMonth=toMonth")
  .header("X-Thera-API-Key", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.getthera.com/companies/companyId/fees/contractors?fromMonth=fromMonth&toMonth=toMonth', [
  'headers' => [
    'X-Thera-API-Key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.getthera.com/companies/companyId/fees/contractors?fromMonth=fromMonth&toMonth=toMonth");
var request = new RestRequest(Method.GET);
request.AddHeader("X-Thera-API-Key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["X-Thera-API-Key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.getthera.com/companies/companyId/fees/contractors?fromMonth=fromMonth&toMonth=toMonth")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```