Company
Admin permissions required.
The company object
| Attribute | Type | Description |
|---|---|---|
base_uri |
string | The Harvest URL for the company. |
full_domain |
string | The Harvest domain for the company. |
name |
string | The name of the company. |
is_active |
boolean | Whether the company is active or archived. |
week_start_day |
string | The weekday used as the start of the week. Returns one of: Saturday, Sunday, or Monday. |
wants_timestamp_timers |
boolean | Whether time is tracked via duration or start and end times. |
time_format |
string | The format used to display time in Harvest. Returns either decimal or hours_minutes. |
date_format |
string | The format used to display date in Harvest. Returns one of: %m/%d/%Y, %d/%m/%Y, %Y-%m-%d, %d.%m.%Y,.%Y.%m.%d or %Y/%m/%d. |
plan_type |
string | The type of plan the company is on. Examples: trial, free, or simple-v4 |
clock |
string | Used to represent whether the company is using a 12-hour or 24-hour clock. Returns either 12h or 24h. |
currency_code_display |
string | How to display the currency code when formatting currency. Returns one of: iso_code_none, iso_code_before, or iso_code_after. |
currency_symbol_display |
string | How to display the currency symbol when formatting currency. Returns one of: symbol_none, symbol_before, or symbol_after. |
decimal_symbol |
string | Symbol used when formatting decimals. |
thousands_separator |
string | Separator used when formatting numbers. |
color_scheme |
string | The color scheme being used in the Harvest web client. |
weekly_capacity |
integer | The weekly capacity in seconds. |
expense_feature |
boolean | Whether the expense module is enabled. |
invoice_feature |
boolean | Whether the invoice module is enabled. |
estimate_feature |
boolean | Whether the estimate module is enabled. |
approval_feature |
boolean | Whether the approval module is enabled. |
team_feature |
boolean | Whether the team module is enabled. |
e_invoicing_status |
string | The state of the company’s Peppol e-invoicing enrollment: pending_kyb, kyb_failed, active, rejected, or null when the company has no enrollment. |
Retrieve a company
Retrieves the company for the currently authenticated user. Returns a
company object and a 200 OK response code.
GET /v2/company
Example requests:
Postman Collection
We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!
curl "https://api.harvestapp.com/v2/company" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example response:
{
"base_uri":"https://{ACCOUNT_SUBDOMAIN}.harvestapp.com",
"full_domain":"{ACCOUNT_SUBDOMAIN}.harvestapp.com",
"name":"API Examples",
"is_active":true,
"week_start_day":"Monday",
"wants_timestamp_timers":true,
"time_format":"hours_minutes",
"date_format":"%Y-%m-%d",
"plan_type":"sponsored",
"expense_feature":true,
"invoice_feature":true,
"estimate_feature":true,
"approval_feature":true,
"clock":"12h",
"currency_code_display":"iso_code_none",
"currency_symbol_display":"symbol_before",
"decimal_symbol":".",
"thousands_separator":",",
"color_scheme":"orange",
"weekly_capacity": 126000
}Update a company
Updates the company setting the values of the parameters passed. Any parameters not provided will be left unchanged. Returns a company object and a 200 OK response code if the call succeeded.
PATCH /v2/company
| Attribute | Type | Description |
|---|---|---|
wants_timestamp_timers |
boolean | Whether time is tracked via duration or start and end times. |
weekly_capacity |
integer | The weekly capacity in seconds. |
Example requests:
Postman Collection
We have a collection of API requests in Postman that makes it easy to try this out. Click here to learn more!
curl "https://api.harvestapp.com/v2/company" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
-X PATCH \
-H "Content-Type: application/json" \
-d '{"weekly_capacity":108000, "wants_timestamp_timers":false}'
Example response:
{
"base_uri":"https://{ACCOUNT_SUBDOMAIN}.harvestapp.com",
"full_domain":"{ACCOUNT_SUBDOMAIN}.harvestapp.com",
"name":"API Examples",
"is_active":true,
"week_start_day":"Monday",
"wants_timestamp_timers":false,
"time_format":"hours_minutes",
"date_format":"%Y-%m-%d",
"plan_type":"sponsored",
"expense_feature":true,
"invoice_feature":true,
"estimate_feature":true,
"approval_feature":true,
"clock":"12h",
"currency_code_display":"iso_code_none",
"currency_symbol_display":"symbol_before",
"decimal_symbol":".",
"thousands_separator":",",
"color_scheme":"orange",
"weekly_capacity": 108000
}Retrieve reimbursement settings
Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes
Harvest-Api-Stability: beta.
Retrieves the company’s expense reimbursement preferences. Returns a flat object with the current values and a 200 OK response code.
GET /v2/company/reimbursement_settings
Example Request:
curl "https://api.harvestapp.com/v2/company/reimbursement_settings" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"expense_reimbursement_enabled": true,
"expense_reimbursement_approval_required": false,
"expense_reimbursement_decline_requests": false
}| Attribute | Type | Description |
|---|---|---|
expense_reimbursement_enabled |
boolean | Whether members may flag expenses as needing reimbursement. |
expense_reimbursement_approval_required |
boolean | Whether expense approval is required before reimbursement. Takes effect only when approval workflows are enabled for the company; GET /v2/company reports approval_feature for that precondition. |
expense_reimbursement_decline_requests |
boolean | true means the company declined the request-to-enable flow, so members cannot ask an administrator to enable reimbursement. |
The response contains exactly these three fields. GET /v2/company does not include them.
Update reimbursement settings
Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes
Harvest-Api-Stability: beta.
Updates the company’s expense reimbursement preferences. Only the parameters provided are changed; any parameter omitted keeps its value. A request with none of these parameters is a successful no-op. Unknown parameters are ignored. Returns the updated object and a 200 OK response code.
PATCH /v2/company/reimbursement_settings
| Parameter | Type | Description |
|---|---|---|
expense_reimbursement_enabled |
boolean | Whether members may flag expenses as needing reimbursement. |
expense_reimbursement_approval_required |
boolean | Whether expense approval is required before reimbursement. |
expense_reimbursement_decline_requests |
boolean | true means the company declined the request-to-enable flow. |
Each parameter accepts true, false, "true", "false", "1", "0", 1, or 0; values are normalized to booleans. Any other value, including "yes", "True", another number, null, "", an array, or an object, returns 422. null does not clear a setting. Form-encoded bodies are accepted.
Example Request:
curl "https://api.harvestapp.com/v2/company/reimbursement_settings" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])" \
-X PATCH \
-H "Content-Type: application/json" \
-d '{"expense_reimbursement_enabled": true}'
Example Response:
{
"expense_reimbursement_enabled": true,
"expense_reimbursement_approval_required": false,
"expense_reimbursement_decline_requests": false
}Enroll in e-invoicing
Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes
Harvest-Api-Stability: beta.
Enrolls the company as a Peppol sender. Returns an e-invoicing status object and a 201 Created response code. Enrollment is registered asynchronously; the resulting state is readable as e_invoicing_status on Retrieve a company.
Admin permissions (company write access) required.
POST /v2/company/e_invoicing
| Parameter | Type | Required | Description |
|---|---|---|---|
contact_email |
string | required | Address that receives e-invoicing status updates. A blank or null value returns 422. A non-string value returns 422 and is not coerced. |
consent |
boolean | required | Explicit Peppol registration consent. Only true, 1, "true", or "1" is accepted. |
profile |
object | optional | The company’s legal-identity information to store before enrollment. An omitted or empty object writes nothing. A non-object value returns 422. Unknown keys are ignored. |
The profile object accepts these keys:
| Key | Type | Description |
|---|---|---|
registered_name |
string | Registered legal name. |
address_line1 |
string | Street address, first line. |
address_line2 |
string | Street address, second line. |
address_city |
string | City. |
address_state |
string | State or province. |
address_postal_code |
string | Postal code. |
address_country |
string | Country code. |
tax_id |
string | Tax identifier. |
peppol_endpoint_id |
string | Peppol endpoint identifier. |
peppol_endpoint_scheme |
string | Peppol endpoint scheme. |
bank_account_number |
string | Bank account number. |
bank_account_routing_number |
string | Bank account routing number. |
bank_account_holder_name |
string | Bank account holder name. |
contact_name |
string | Contact name. |
contact_email |
string | Contact email address. |
contact_phone |
string | Contact phone number. |
company_registration_number |
string | Company registration number. |
legal_form |
string | Legal form. |
payment_means_codes |
array | Array of payment-means code strings. |
A known string key with a non-string value returns 422, and a payment_means_codes value that is not an array of strings returns 422. If the company already has a pending_kyb or active enrollment, the request returns 422 before anything is written. Re-enrolling after a kyb_failed or rejected enrollment is allowed, but tax_id, peppol_endpoint_id, peppol_endpoint_scheme, and address_country still cannot be changed; supplying one returns 422. Disconnect first to change them.
Example Request:
curl -X POST "https://api.harvestapp.com/v2/company/e_invoicing" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: MyApp ([email protected])" \
-d '{"contact_email":"[email protected]","consent":true,"profile":{"registered_name":"ABC Corp B.V.","address_line1":"Keizersgracht 100","address_city":"Amsterdam","address_postal_code":"1015 CJ","address_country":"NL","tax_id":"NL123456789B01","peppol_endpoint_id":"12345678","peppol_endpoint_scheme":"0106","contact_name":"Kim Allen","contact_email":"[email protected]"}}'
Example Response:
{
"status": "pending_kyb"
}Disconnect from e-invoicing
Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes
Harvest-Api-Stability: beta.
Disconnects the company’s Peppol enrollment. Returns an e-invoicing status object and a 200 OK response code. Repeating the call after the enrollment is gone returns 200 OK with status null and has no further effect.
Admin permissions (company write access) required.
DELETE /v2/company/e_invoicing
This endpoint takes no parameters.
Example Request:
curl -X DELETE "https://api.harvestapp.com/v2/company/e_invoicing" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp ([email protected])"
Example Response:
{
"status": null
}status is one of:
| Status | Description |
|---|---|
pending_kyb |
Enrollment was submitted and registration is running. |
kyb_failed |
Registration failed. A subsequent enrollment request can be submitted. |
active |
The company is registered on Peppol and can send e-invoices. |
rejected |
Registration was rejected. A subsequent enrollment request can be submitted. |
null |
No enrollment exists. |
Errors
The following status codes are returned for the reimbursement settings and e-invoicing endpoints:
| Status | Description |
|---|---|
400 |
A required User-Agent header is missing (User-Agent header required). |
401 |
Authentication failed (Authentication failed for API request.). |
403 |
The account is inactive (Account inactive), the account is on hold or its sponsorship expired, the caller does not have the required permission (Not authorized!), or e-invoicing is not enabled for the account (E-invoicing is not enabled for this account). |
415 |
The request body’s media type is neither application/json, application/xml, nor form data. |
422 |
A reimbursement setting has an unsupported boolean value (Invalid <key> boolean provided: <value>, one message per key, joined with , ), or an e-invoicing parameter is invalid. See the messages below. |
500 |
An unexpected error occurred. |
The e-invoicing 422 responses include these messages:
Notification email is required.Invalid contact_email parameter: must be a stringYou must authorize the Peppol registration to enroll.Invalid profile parameter: must be a hashInvalid <key> parameter: must be a stringInvalid payment_means_codes parameter: must be an array of strings<fields> cannot be changed while an e-invoicing enrollment exists. Disconnect first, then enroll again.(only when re-enrolling after akyb_failedorrejectedenrollment)Your e-invoicing identity couldn’t be synced with the Peppol network, so your changes weren’t saved. Please try again or contact support.An e-invoicing enrollment is already in progress for this company.(existingpending_kybenrollment)This company is already enrolled for e-invoicing.(existingactiveenrollment)This company has e-invoices still in flight. Wait for them to reach a terminal state before deleting the enrollment.We couldn’t remove your e-invoicing registration right now. Please try again or contact support.Complete your company information first: …E-invoicing enrollment isn’t available for <country> yet.Peppol scheme '<scheme>' is not currently supported for e-invoicing.
Profile and enrollment validation can also return country-specific messages not listed here.