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 string
  • You must authorize the Peppol registration to enroll.
  • Invalid profile parameter: must be a hash
  • Invalid <key> parameter: must be a string
  • Invalid 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 a kyb_failed or rejected enrollment)
  • 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. (existing pending_kyb enrollment)
  • This company is already enrolled for e-invoicing. (existing active enrollment)
  • 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.

Still have questions? We’re happy to help!

Contact Us