curl --request POST \
--url https://qubesync.com/api/v2/connections/{connection_id}/employees \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "[email protected]",
"name": "Jane Doe",
"phone": "555-0100"
}
'import requests
url = "https://qubesync.com/api/v2/connections/{connection_id}/employees"
payload = {
"email": "[email protected]",
"name": "Jane Doe",
"phone": "555-0100"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({email: '[email protected]', name: 'Jane Doe', phone: '555-0100'})
};
fetch('https://qubesync.com/api/v2/connections/{connection_id}/employees', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://qubesync.com/api/v2/connections/{connection_id}/employees",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => '[email protected]',
'name' => 'Jane Doe',
'phone' => '555-0100'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://qubesync.com/api/v2/connections/{connection_id}/employees"
payload := strings.NewReader("{\n \"email\": \"[email protected]\",\n \"name\": \"Jane Doe\",\n \"phone\": \"555-0100\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://qubesync.com/api/v2/connections/{connection_id}/employees")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"[email protected]\",\n \"name\": \"Jane Doe\",\n \"phone\": \"555-0100\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://qubesync.com/api/v2/connections/{connection_id}/employees")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"[email protected]\",\n \"name\": \"Jane Doe\",\n \"phone\": \"555-0100\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"links": {
"connection_ui": "<string>",
"pages": "<string>",
"self": "<string>",
"ui": "<string>"
},
"request_xml": "<string>",
"state": "waiting",
"error": {
"debug_message": "<string>",
"error_code": 123,
"error_type": "xml_error",
"hresult": "<string>",
"message": "<string>",
"user_message": "<string>"
},
"inserted_at": "2023-11-07T05:31:56Z",
"iteration_state": "not_applicable",
"original_request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"page": 123,
"request_types": [
"<string>"
],
"response_json": {
"status": "success",
"data": {
"department": "<string>",
"mobile": "<string>",
"work_auth_expire_date": "2023-12-25",
"employee_type": "Officer",
"disabled": "No",
"ssn": "<string>",
"fax": "<string>",
"hired_date": "2023-12-25",
"time_modified": "2023-11-07T05:31:56Z",
"employee_payroll_info": {
"class_ref": {
"full_name": "<string>",
"list_id": "<string>"
},
"clear_earnings": true,
"earnings": [
{
"payroll_item_wage_ref": {
"full_name": "<string>",
"list_id": "<string>"
},
"rate": 123,
"rate_percent": 123
}
],
"pay_period": "Biweekly",
"sick_hours": {
"accrual_period": "BeginningOfYear",
"accrual_start_date": "2023-12-25",
"hours_accrued": "<string>",
"hours_available": "<string>",
"hours_used": "<string>",
"is_resetting_hours_each_new_year": true,
"maximum_hours": "<string>"
},
"use_time_data_to_create_paychecks": "DoNotUseTimeData",
"vacation_hours": {
"accrual_period": "BeginningOfYear",
"accrual_start_date": "2023-12-25",
"hours_accrued": "<string>",
"hours_available": "<string>",
"hours_used": "<string>",
"is_resetting_hours_each_new_year": true,
"maximum_hours": "<string>"
}
},
"part_or_full_time": "FullTime",
"list_id": "<string>",
"us_citizen": "No",
"us_veteran": "No",
"gender": "Female",
"billing_rate_ref": {
"full_name": "<string>",
"list_id": "<string>"
},
"additional_notes_ret": [
{
"date": "2023-12-25",
"note": "<string>",
"note_id": 123
}
],
"description": "<string>",
"job_title": "<string>",
"name": "<string>",
"email": "<string>",
"supervisor_ref": {
"full_name": "<string>",
"list_id": "<string>"
},
"pager_pin": "<string>",
"time_created": "2023-11-07T05:31:56Z",
"salutation": "<string>",
"edit_sequence": "<string>",
"military_status": "Active",
"phone": "<string>",
"key_employee": "No",
"data_ext_ret": [
{
"data_ext_name": "<string>",
"data_ext_type": "AMTTYPE",
"data_ext_value": "<string>",
"owner_id": "<string>"
}
],
"external_guid": "<string>",
"employee_address": {
"addr1": "<string>",
"addr2": "<string>",
"addr3": "<string>",
"addr4": "<string>",
"city": "<string>",
"country": "<string>",
"postal_code": "<string>",
"state": "<string>"
},
"ethnicity": "AmericianIndian",
"alt_phone": "<string>",
"print_as": "<string>",
"emergency_contacts": {
"primary_contact": {
"contact_name": "<string>",
"contact_value": "<string>",
"relation": "Brother"
},
"secondary_contact": {
"contact_name": "<string>",
"contact_value": "<string>",
"relation": "Brother"
}
},
"middle_name": "<string>",
"last_name": "<string>",
"birth_date": "2023-12-25",
"released_date": "2023-12-25",
"suffix": "<string>",
"additional_contact_ref": [
{
"contact_name": "<string>",
"contact_value": "<string>"
}
],
"adjusted_service_date": "2023-12-25",
"is_active": true,
"pager": "<string>",
"target_bonus": 123,
"exempt": "Exempt",
"disability_desc": "<string>",
"original_hire_date": "2023-12-25",
"first_name": "<string>",
"on_file": "No",
"notes": "<string>",
"account_number": "<string>"
},
"message": "<string>",
"warning": {
"code": 530,
"message": "<string>"
}
},
"response_xml": "<string>",
"webhook_attempts": [
{}
],
"webhook_error": "<string>",
"webhook_state": "not_applicable",
"webhook_url": "<string>"
}
}{
"errors": "unknown parameter: \"emial\""
}Unauthorized{
"errors": {
"detail": "Sandbox access is paused for this organization because the sandbox period expired and the organization does not currently have both active billing and a recent production connection. Please request an extension if you're still working on your integration or contact support if you have questions."
}
}{
"errors": {
"detail": "Not Found"
}
}{
"errors": {
"webhook_url": [
"may not contain a username or password"
]
}
}Create employee
qbXML: EmployeeAddRq. The employee_add wrapper from qbXML is also accepted.
Adds an employee with personal data about the employee as well as certain payroll-related data.
Intuit’s reference: EmployeeAdd.
curl --request POST \
--url https://qubesync.com/api/v2/connections/{connection_id}/employees \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"email": "[email protected]",
"name": "Jane Doe",
"phone": "555-0100"
}
'import requests
url = "https://qubesync.com/api/v2/connections/{connection_id}/employees"
payload = {
"email": "[email protected]",
"name": "Jane Doe",
"phone": "555-0100"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({email: '[email protected]', name: 'Jane Doe', phone: '555-0100'})
};
fetch('https://qubesync.com/api/v2/connections/{connection_id}/employees', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://qubesync.com/api/v2/connections/{connection_id}/employees",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'email' => '[email protected]',
'name' => 'Jane Doe',
'phone' => '555-0100'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://qubesync.com/api/v2/connections/{connection_id}/employees"
payload := strings.NewReader("{\n \"email\": \"[email protected]\",\n \"name\": \"Jane Doe\",\n \"phone\": \"555-0100\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://qubesync.com/api/v2/connections/{connection_id}/employees")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"[email protected]\",\n \"name\": \"Jane Doe\",\n \"phone\": \"555-0100\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://qubesync.com/api/v2/connections/{connection_id}/employees")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"email\": \"[email protected]\",\n \"name\": \"Jane Doe\",\n \"phone\": \"555-0100\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"links": {
"connection_ui": "<string>",
"pages": "<string>",
"self": "<string>",
"ui": "<string>"
},
"request_xml": "<string>",
"state": "waiting",
"error": {
"debug_message": "<string>",
"error_code": 123,
"error_type": "xml_error",
"hresult": "<string>",
"message": "<string>",
"user_message": "<string>"
},
"inserted_at": "2023-11-07T05:31:56Z",
"iteration_state": "not_applicable",
"original_request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"page": 123,
"request_types": [
"<string>"
],
"response_json": {
"status": "success",
"data": {
"department": "<string>",
"mobile": "<string>",
"work_auth_expire_date": "2023-12-25",
"employee_type": "Officer",
"disabled": "No",
"ssn": "<string>",
"fax": "<string>",
"hired_date": "2023-12-25",
"time_modified": "2023-11-07T05:31:56Z",
"employee_payroll_info": {
"class_ref": {
"full_name": "<string>",
"list_id": "<string>"
},
"clear_earnings": true,
"earnings": [
{
"payroll_item_wage_ref": {
"full_name": "<string>",
"list_id": "<string>"
},
"rate": 123,
"rate_percent": 123
}
],
"pay_period": "Biweekly",
"sick_hours": {
"accrual_period": "BeginningOfYear",
"accrual_start_date": "2023-12-25",
"hours_accrued": "<string>",
"hours_available": "<string>",
"hours_used": "<string>",
"is_resetting_hours_each_new_year": true,
"maximum_hours": "<string>"
},
"use_time_data_to_create_paychecks": "DoNotUseTimeData",
"vacation_hours": {
"accrual_period": "BeginningOfYear",
"accrual_start_date": "2023-12-25",
"hours_accrued": "<string>",
"hours_available": "<string>",
"hours_used": "<string>",
"is_resetting_hours_each_new_year": true,
"maximum_hours": "<string>"
}
},
"part_or_full_time": "FullTime",
"list_id": "<string>",
"us_citizen": "No",
"us_veteran": "No",
"gender": "Female",
"billing_rate_ref": {
"full_name": "<string>",
"list_id": "<string>"
},
"additional_notes_ret": [
{
"date": "2023-12-25",
"note": "<string>",
"note_id": 123
}
],
"description": "<string>",
"job_title": "<string>",
"name": "<string>",
"email": "<string>",
"supervisor_ref": {
"full_name": "<string>",
"list_id": "<string>"
},
"pager_pin": "<string>",
"time_created": "2023-11-07T05:31:56Z",
"salutation": "<string>",
"edit_sequence": "<string>",
"military_status": "Active",
"phone": "<string>",
"key_employee": "No",
"data_ext_ret": [
{
"data_ext_name": "<string>",
"data_ext_type": "AMTTYPE",
"data_ext_value": "<string>",
"owner_id": "<string>"
}
],
"external_guid": "<string>",
"employee_address": {
"addr1": "<string>",
"addr2": "<string>",
"addr3": "<string>",
"addr4": "<string>",
"city": "<string>",
"country": "<string>",
"postal_code": "<string>",
"state": "<string>"
},
"ethnicity": "AmericianIndian",
"alt_phone": "<string>",
"print_as": "<string>",
"emergency_contacts": {
"primary_contact": {
"contact_name": "<string>",
"contact_value": "<string>",
"relation": "Brother"
},
"secondary_contact": {
"contact_name": "<string>",
"contact_value": "<string>",
"relation": "Brother"
}
},
"middle_name": "<string>",
"last_name": "<string>",
"birth_date": "2023-12-25",
"released_date": "2023-12-25",
"suffix": "<string>",
"additional_contact_ref": [
{
"contact_name": "<string>",
"contact_value": "<string>"
}
],
"adjusted_service_date": "2023-12-25",
"is_active": true,
"pager": "<string>",
"target_bonus": 123,
"exempt": "Exempt",
"disability_desc": "<string>",
"original_hire_date": "2023-12-25",
"first_name": "<string>",
"on_file": "No",
"notes": "<string>",
"account_number": "<string>"
},
"message": "<string>",
"warning": {
"code": 530,
"message": "<string>"
}
},
"response_xml": "<string>",
"webhook_attempts": [
{}
],
"webhook_error": "<string>",
"webhook_state": "not_applicable",
"webhook_url": "<string>"
}
}{
"errors": "unknown parameter: \"emial\""
}Unauthorized{
"errors": {
"detail": "Sandbox access is paused for this organization because the sandbox period expired and the organization does not currently have both active billing and a recent production connection. Please request an extension if you're still working on your integration or contact support if you have questions."
}
}{
"errors": {
"detail": "Not Found"
}
}{
"errors": {
"webhook_url": [
"may not contain a username or password"
]
}
}Authorizations
Use your app's API key as the username, and leave the password blank
Headers
Makes a retry safe when you never got the answer to a call: a timeout, a dropped connection, a worker that crashed. Send a new key (a UUID, say) with each request you mean to make once, and the same key when you send that request again. A repeat with the key and the same method, path, query and body answers 201 with what the first call created, as it is now, marked Idempotent-Replayed: true, and queues nothing. The same key with a different request is a 422. A key belongs to your app (sandbox and production apps never share one), lasts as long as what it created, and is 1 to 255 printable ASCII characters.
1 - 255^[\x20-\x7E]+$Path Parameters
The connection (a customer's QuickBooks company file) this request is queued for.
Query Parameters
Where QuBe Sync POSTs the answered request (this same document with response_json filled in), signed with X-QUBE-Signature. Send one with every request: it is how answers are delivered. Optional only so a script can queue and look up links.self by hand. It must be an absolute http or https URL. It may not contain a username or password, and in production it may not point at localhost or a private, loopback or link-local address. A qube listen URL must be one of this app's.
2048Body
The name of the department in the employment job details section.
Your own label for the request, sent to QuickBooks as its qbXML requestID and echoed in the raw answer (response_xml); optional, since the answer's webhook already carries the request's id.
Mobile telephone number.
Date the employee’s work authorization expires.
employee_type can affect payroll taxes for an employee. A statutory employee is a person who is defined as an employee by statute. Usually an owner or partner will be on the Other Names list, but if they are on the Employee list, their employee_type will be Owner.
Officer, Owner, Regular, Statutory Is employee disabled?
No, Yes Social security number. When you add an SSN value to an employee record, it doesn’t have to include dashes; for example, either 123-45-6789 or 123456789 would be valid.
Fax number.
An employee’s date of hire.
Pay information for this employee.
Show child attributes
Show child attributes
Full or Part time status of the employee.
FullTime, PartTime Is employee a US citizen?
No, Yes Is employee a US veteran?
No, Yes Show child attributes
Show child attributes
The gender of this employee.
Female, Male Billing rates are used to override the service item rate in a time transaction (TimeTrackingAdd) based on the employee or vendor performing the work. Billing rates are assigned to an employee or a vendor to specify overrides to service items.
Show child attributes
Show child attributes
The description details in the employment job details section.
The job title of a customer, vendor, employee, or person on the “other names” list.
A concatenation of first_name, middle_name, and last_name.
E-mail address.
The name of a customer, vendor, employee, or person on the “other names” list in the employment job details section.
Show child attributes
Show child attributes
A personal identification number for this employee’s pager.
A formal reference, such as Mr. or Dr., that precedes a name.
Military status if the employee is a US veteran.
Active, Reserve The telephone number.
Is employee a key or critical employee.
No, Yes Allows for the attachment of a user defined GUID value.
If an address request fails, some combination of address fields might be too long. If you use payroll, you must specify the employee’s city, state (or province), ZIP (or postal) code, and at least one line of the street address. (Note that the State element has restrictions when it’s used in the employee_address aggregate. For more information, click State in the table.)
Show child attributes
Show child attributes
Ethnicity of employee from AmericianIndian, Asian, Black, Hawaiian, Hispanic, White, TwoOrMoreRaces
AmericianIndian, Asian, Black, Hawaiian, Hispanic, TwoOrMoreRaces, White A telephone number given as an alternative to Phone.
By default within QuickBooks, the print_as element is the same as the Name element.
Emergency Contact information for the employee.
Show child attributes
Show child attributes
The middle name of a customer, vendor, employee, or person on the “other names” list.
The last name of a customer, vendor, employee, or person on the “other names” list.
Date of birth.
The date on which this person’s employment with the company ended.
Show child attributes
Show child attributes
Adjusted service date for the employee.
If is_active is true, this object is currently enabled for use by QuickBooks. The default value is true.
The pager number.
The target bonus amount in the employment job details section.
Exempt or Non-exempt status of the employee.
Exempt, NonExempt Description of employee’s disablitily.
Original hire date the employee was hired.
The first name of a customer, vendor, employee, or person on the “other names” list.
Is the employee’s I-9 on file?
No, Yes Additional information.
AccountNumber, AdditionalContactRef, AdditionalNotesRet, AdjustedServiceDate, AltPhone, BillingRateRef, BirthDate, DataExtRet, Department, Description, DisabilityDesc, Disabled, EditSequence, Email, EmergencyContacts, EmployeeAddress, EmployeePayrollInfo, EmployeeType, Ethnicity, Exempt, ExternalGUID, Fax, FirstName, Gender, HiredDate, IsActive, JobTitle, KeyEmployee, LastName, ListID, MiddleName, MilitaryStatus, Mobile, Name, Notes, OnFile, OriginalHireDate, OwnerID, Pager, PagerPIN, PartOrFullTime, Phone, PrintAs, ReleasedDate, SSN, Salutation, Suffix, SupervisorRef, TargetBonus, TimeCreated, TimeModified, TxnID, TxnNumber, USCitizen, USVeteran, WorkAuthExpireDate Account numbers appear in the QuickBooks chart of accounts, Account fields, and reports and graphs. If the IsUsingAccountNumber preference is false (that is, if the QuickBooks user has the account numbers Preference turned off), you can still set account numbers through the SDK, but the numbers won’t be visible in the user interface.
Callbacks
POST{$request.query.webhook_url}answered
Body
POSTed to webhook_url as JSON, signed with X-QUBE-Signature (t=<timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>" with your app's webhook secret>).
Your app's id.
Set when state is error, retryable, timed_out or discarded. error_type says where it failed: for a timed_out request it is timed_out, and for a discarded one discarded, unless the request was retryable when your app discarded it, which keeps the connection error that held it up. user_message is safe to show an end user; error_code is QuickBooks' own status code for a business error, hresult the Web Connector's for a connection/XML error; debug_message is for you.
Show child attributes
Show child attributes
The request's id, as the 201 returned it. For an iterated query, every page carries the first page's id here.
This page's own id. Equal to id except on later pages of an iterated query.
QuBe Sync's summary of QuickBooks' answer. Only an Error severity from QuickBooks is status: "error" (and makes the request's state error), so a query that matched nothing is still success. A Warn severity is a success with warning beside it.
- Success
- Error
Show child attributes
Show child attributes
Whether the app is a sandbox app.
response_received: QuickBooks accepted it; read response_json. error: it is over and QuBe Sync won't try again -- see error, and response_json.error for a QuickBooks business error; with error_type outcome_unknown a write may still have been applied, so look before sending it again. retryable: QuickBooks could not be reached and QuBe Sync keeps trying; show the customer error.user_message so they can fix it. timed_out: no answer came back -- the customer's computer lost its connection, or QuickBooks or the Web Connector was closed, mid-request. QuickBooks may still have applied it, so look before sending it again. discarded: your app discarded it before the Web Connector picked it up, so QuickBooks never got it. Both carry an error.
response_received, error, retryable, timed_out, discarded Unix seconds; the same t the signature covers.
continue: more pages will follow, each its own webhook. done: this was the last page. max_sandbox_iterations_reached: a sandbox app's page limit stopped the iteration.
not_applicable, continue, done, max_sandbox_iterations_reached Present only with response_xml_omitted.
Show child attributes
Show child attributes
The page number, when iterated.
QuickBooks' raw qbXML answer. response_json is the same, summarized. One answer can be at most 4 MB as the Web Connector sends it, about 3 MB of qbXML; QuickBooks' answer over that isn't kept: this is null and error.error_type is response_too_large. A webhook whose body would be over 1 MB is sent without it: null, with response_xml_omitted true; fetch it from links.self.
Present, and true, only when response_xml was left out to keep the body under 1 MB. response_json is still here; GET links.self for response_xml.
Response
Received. Anything else is retried with backoff for about 8 hours.
Response
Queued for the connection's Web Connector. Pass webhook_url and QuBe Sync POSTs the answer to it once QuickBooks has answered (see the answered callback: its own payload, not this document). links.self returns this document on demand, with response_json filled in.
Show child attributes
Show child attributes