> This page is for version API + Legacy Full. > 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. # Create Contractor POST https://api.getthera.com/external/v2/contractor Content-Type: application/json Creates a contractor and their contract in a single call, for any contract type: fixed rate, flexible rate, milestone, or time tracking. The contractor is invited by email and becomes payable once they complete onboarding. Reference: https://docs.getthera.com/api-legacy-full/external-api-deprecated/external-api/create-contractor-v-2 ## 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 ### Body (application/json) This endpoint expects an ExternalCreateContractorRequestV2. - `email` (string, required) - `firstName` (string, required) - `lastName` (string, required) - `country` (string, required) - `currency` (string, required) - `wageType` (enum, required) - Allowed values: `HOURLY`, `DAILY`, `MONTHLY`, `SEMIMONTHLY`, `BIWEEKLY`, `WEEKLY`, `MILESTONE` - `payCycle` (PayCycle, required) - `contractType` (enum, required) - Allowed values: `FIXED_RATE`, `FLEXIBLE_RATE`, `MILESTONE`, `TIME_TRACKING` - `contractName` (string, required) - `contractDocumentType` (enum, required) - Allowed values: `NO_CONTRACT`, `CONTRACT_WIZARD` - `verificationSetting` (VerificationSetting, required) - `rate` (long, optional) — In the smallest unit possible. Minor Unit if exists, else use Major Unit. Adheres to [ISO 4217](https://simple.wikipedia.org/wiki/ISO_4217) standard. This field is not needed for Milestone Contractors. - `companySigningAuthorityUserId` (string, optional) — The Thera User ID of signer from the company side. Must be an Admin or a Manager. - `clientCanSubmitWork` (boolean, optional) - `workerCanSubmitWork` (boolean, optional) - `scopeOfWork` (string, optional) - `teamId` (string, optional) — The team the contract is created under, from Get Teams. Required when your company has more than one team; optional when it has exactly one, which is then used automatically. ## Response ### 200 - `success` (boolean, required) ## Errors ### 401 Unauthorized Error The X-Thera-API-Key header is missing, or the key does not exist. - `message` (string, required) - `displayMessage` (string, required) — Safe to show an end user. Conflicts return a generic message rather than the specific reason. - `timestamp` (string, required) — Format dd-MM-yyyy hh:mm:ss. - `type` (string, optional) — Present as GeneralError on 400, 401 and 404. Null on 409. - `debugMessage` (string, optional) - `subErrors` (list of any, optional) ### 400 Bad Request Error A field failed validation, for example an invalid ISO 3166-1 alpha-2 country code. - `message` (string, required) - `displayMessage` (string, required) — Safe to show an end user. Conflicts return a generic message rather than the specific reason. - `timestamp` (string, required) — Format dd-MM-yyyy hh:mm:ss. - `type` (string, optional) — Present as GeneralError on 400, 401 and 404. Null on 409. - `debugMessage` (string, optional) - `subErrors` (list of any, optional) ### 409 Conflict Error That contractor already has an active API-created contract with your company. - `message` (string, required) - `displayMessage` (string, required) — Safe to show an end user. Conflicts return a generic message rather than the specific reason. - `timestamp` (string, required) — Format dd-MM-yyyy hh:mm:ss. - `type` (string, optional) — Present as GeneralError on 400, 401 and 404. Null on 409. - `debugMessage` (string, optional) - `subErrors` (list of any, optional) ## Types ### PayCycle - `cycleStartDate` (date, required) — The contractor's contract's start date - `cycleEnd` (PayCycleEnd, required) - `paymentDueDays` (integer, required) - `firstPayDate` (date, required) - `lastPayDate` (date, optional) - `firstPayTotal` (long, optional) — In the smallest unit possible. Minor Unit if exists, else use Major Unit. Adheres to [ISO 4217](https://simple.wikipedia.org/wiki/ISO_4217) standard. - `lastPayTotal` (long, optional) — In the smallest unit possible. Minor Unit if exists, else use Major Unit. Adheres to [ISO 4217](https://simple.wikipedia.org/wiki/ISO_4217) standard. ### VerificationSetting - `kycEnabled` (boolean, required) - `complianceEnabled` (boolean, required) ### PayCycleEnd - `type`: `weekly` - `dayOfWeek` (enum, required) - Allowed values: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY` - `type`: `biweekly` - `dayOfWeek` (enum, required) - Allowed values: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY` - `type`: `monthly` - `value` (MonthlyPayCycleEnd, required) - `type`: `semimonthly` - `value` (SemiMonthlyPayCycleEnd, required) ### MonthlyPayCycleEnd - `type`: `dayOfMonth` - `value` (integer, required) - `type`: `lastDayOfMonth` - `type`: `lastDayOfWeekOfMonth` - `value` (enum, required) - Allowed values: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY` ### SemiMonthlyPayCycleEnd - `type`: `fifteenthAndEndOfMonth` - `type`: `dayOfMonth` - `value` (integer, required) ## Examples **Request** ```json { "email": "email", "firstName": "firstName", "lastName": "lastName", "country": "country", "currency": "currency", "wageType": "HOURLY", "payCycle": { "cycleStartDate": "2023-01-15", "cycleEnd": { "type": "weekly", "dayOfWeek": "MONDAY" }, "paymentDueDays": 1, "firstPayDate": "2023-01-15" }, "contractType": "FIXED_RATE", "contractName": "contractName", "contractDocumentType": "NO_CONTRACT", "verificationSetting": { "kycEnabled": true, "complianceEnabled": true } } ``` **Response** ```json { "success": true } ``` **SDK Code** ```python import requests url = "https://api.getthera.com/external/v2/contractor" payload = { "email": "email", "firstName": "firstName", "lastName": "lastName", "country": "country", "currency": "currency", "wageType": "HOURLY", "payCycle": { "cycleStartDate": "2023-01-15", "cycleEnd": { "type": "weekly", "dayOfWeek": "MONDAY" }, "paymentDueDays": 1, "firstPayDate": "2023-01-15" }, "contractType": "FIXED_RATE", "contractName": "contractName", "contractDocumentType": "NO_CONTRACT", "verificationSetting": { "kycEnabled": True, "complianceEnabled": True } } headers = { "X-Thera-API-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.getthera.com/external/v2/contractor'; const options = { method: 'POST', headers: {'X-Thera-API-Key': '', 'Content-Type': 'application/json'}, body: '{"email":"email","firstName":"firstName","lastName":"lastName","country":"country","currency":"currency","wageType":"HOURLY","payCycle":{"cycleStartDate":"2023-01-15","cycleEnd":{"type":"weekly","dayOfWeek":"MONDAY"},"paymentDueDays":1,"firstPayDate":"2023-01-15"},"contractType":"FIXED_RATE","contractName":"contractName","contractDocumentType":"NO_CONTRACT","verificationSetting":{"kycEnabled":true,"complianceEnabled":true}}' }; 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" "strings" "net/http" "io" ) func main() { url := "https://api.getthera.com/external/v2/contractor" payload := strings.NewReader("{\n \"email\": \"email\",\n \"firstName\": \"firstName\",\n \"lastName\": \"lastName\",\n \"country\": \"country\",\n \"currency\": \"currency\",\n \"wageType\": \"HOURLY\",\n \"payCycle\": {\n \"cycleStartDate\": \"2023-01-15\",\n \"cycleEnd\": {\n \"type\": \"weekly\",\n \"dayOfWeek\": \"MONDAY\"\n },\n \"paymentDueDays\": 1,\n \"firstPayDate\": \"2023-01-15\"\n },\n \"contractType\": \"FIXED_RATE\",\n \"contractName\": \"contractName\",\n \"contractDocumentType\": \"NO_CONTRACT\",\n \"verificationSetting\": {\n \"kycEnabled\": true,\n \"complianceEnabled\": true\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Thera-API-Key", "") req.Header.Add("Content-Type", "application/json") 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/external/v2/contractor") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-Thera-API-Key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"email\": \"email\",\n \"firstName\": \"firstName\",\n \"lastName\": \"lastName\",\n \"country\": \"country\",\n \"currency\": \"currency\",\n \"wageType\": \"HOURLY\",\n \"payCycle\": {\n \"cycleStartDate\": \"2023-01-15\",\n \"cycleEnd\": {\n \"type\": \"weekly\",\n \"dayOfWeek\": \"MONDAY\"\n },\n \"paymentDueDays\": 1,\n \"firstPayDate\": \"2023-01-15\"\n },\n \"contractType\": \"FIXED_RATE\",\n \"contractName\": \"contractName\",\n \"contractDocumentType\": \"NO_CONTRACT\",\n \"verificationSetting\": {\n \"kycEnabled\": true,\n \"complianceEnabled\": true\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.getthera.com/external/v2/contractor") .header("X-Thera-API-Key", "") .header("Content-Type", "application/json") .body("{\n \"email\": \"email\",\n \"firstName\": \"firstName\",\n \"lastName\": \"lastName\",\n \"country\": \"country\",\n \"currency\": \"currency\",\n \"wageType\": \"HOURLY\",\n \"payCycle\": {\n \"cycleStartDate\": \"2023-01-15\",\n \"cycleEnd\": {\n \"type\": \"weekly\",\n \"dayOfWeek\": \"MONDAY\"\n },\n \"paymentDueDays\": 1,\n \"firstPayDate\": \"2023-01-15\"\n },\n \"contractType\": \"FIXED_RATE\",\n \"contractName\": \"contractName\",\n \"contractDocumentType\": \"NO_CONTRACT\",\n \"verificationSetting\": {\n \"kycEnabled\": true,\n \"complianceEnabled\": true\n }\n}") .asString(); ``` ```php request('POST', 'https://api.getthera.com/external/v2/contractor', [ 'body' => '{ "email": "email", "firstName": "firstName", "lastName": "lastName", "country": "country", "currency": "currency", "wageType": "HOURLY", "payCycle": { "cycleStartDate": "2023-01-15", "cycleEnd": { "type": "weekly", "dayOfWeek": "MONDAY" }, "paymentDueDays": 1, "firstPayDate": "2023-01-15" }, "contractType": "FIXED_RATE", "contractName": "contractName", "contractDocumentType": "NO_CONTRACT", "verificationSetting": { "kycEnabled": true, "complianceEnabled": true } }', 'headers' => [ 'Content-Type' => 'application/json', 'X-Thera-API-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.getthera.com/external/v2/contractor"); var request = new RestRequest(Method.POST); request.AddHeader("X-Thera-API-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"email\": \"email\",\n \"firstName\": \"firstName\",\n \"lastName\": \"lastName\",\n \"country\": \"country\",\n \"currency\": \"currency\",\n \"wageType\": \"HOURLY\",\n \"payCycle\": {\n \"cycleStartDate\": \"2023-01-15\",\n \"cycleEnd\": {\n \"type\": \"weekly\",\n \"dayOfWeek\": \"MONDAY\"\n },\n \"paymentDueDays\": 1,\n \"firstPayDate\": \"2023-01-15\"\n },\n \"contractType\": \"FIXED_RATE\",\n \"contractName\": \"contractName\",\n \"contractDocumentType\": \"NO_CONTRACT\",\n \"verificationSetting\": {\n \"kycEnabled\": true,\n \"complianceEnabled\": true\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-Thera-API-Key": "", "Content-Type": "application/json" ] let parameters = [ "email": "email", "firstName": "firstName", "lastName": "lastName", "country": "country", "currency": "currency", "wageType": "HOURLY", "payCycle": [ "cycleStartDate": "2023-01-15", "cycleEnd": [ "type": "weekly", "dayOfWeek": "MONDAY" ], "paymentDueDays": 1, "firstPayDate": "2023-01-15" ], "contractType": "FIXED_RATE", "contractName": "contractName", "contractDocumentType": "NO_CONTRACT", "verificationSetting": [ "kycEnabled": true, "complianceEnabled": true ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.getthera.com/external/v2/contractor")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data 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() ```