Sign in
Company

Upsert a company

Create or update one company in your CRM through a single endpoint. Omit id to create; pass an existing company id to update that entry. The response is the same object returned by GET /public/v1/companies/{id}, with status 201 on create and 200 on update.

A company here is your relationship with another business plus the underlying business record. The two are written together: name, category, legal_business_name, default_email, phone_number, website, default_sales_order_notes, and default_purchase_order_notes describe the business itself, while the emails, owner_id, group_id, relationship_type_id, default_payment_term_id, outstanding_balance_threshold, and custom_data describe your relationship with it. On create both records are created in one call; on update both are amended in place — no second company is created.

Updates are sparse: only the fields you send change, and any field you omit keeps its current value. Sending custom_data, however, replaces the entire custom-field map — any custom field not present in the map you send is cleared, so send the full set you want to keep. Required custom fields are enforced on both create and update, so a create or update that leaves a required custom field unset is rejected. Renaming a company also updates its public menu URLs, so previously shared menu links for that company change.

This endpoint does not touch inventory and has no state-traceability (Metrc/BioTrack) effect — companies are CRM records only. A few response fields are read-only and cannot be set here: the computed outstanding_balance, leaflink_brand_id, and the nested licenses and locations — manage a company's licenses with POST /public/v1/companies/{id}/licenses instead.

You can link this company to your QuickBooks Online and LeafLink records through qb_customer_id, qb_vendor_id, and leaflink_customer_id. These run the same checks and side effects as the in-app mapping screens: the id must exist in your synced QuickBooks Online / LeafLink data, each may be linked to only one company on your account, and linking a leaflink_customer_id reassigns that customer's existing LeafLink orders to this company. Send an explicit null to unlink; omit the field to leave the current link unchanged. The link runs in the same transaction as the rest of the upsert, so if it is rejected the whole request is rolled back and nothing is persisted.

Validation is all-or-nothing: if any field is rejected the whole upsert fails and nothing is persisted; errors come back as a 400 with an errors array. Referencing an id that does not exist on your account (or that your team restrictions hide) returns 404.

Required permission: companies_permissions_create to create; companies_permissions_edit, plus access to the company under team restrictions, to update. Setting qb_customer_id or qb_vendor_id additionally requires settings_permissions_quickbooks; setting leaflink_customer_id additionally requires companies_permissions_update_leaflink_data.

post/public/v1/companies

Request body

idstring

ID of the company to update. When present, that company is updated and its business record amended in place; when absent, a new company and its underlying business record are created together. Must reference a company on your account that you can access under team restrictions, otherwise the request returns 404.

namestring

Display name of the company. Required on create; left as-is when omitted on update. Must be at least one character and cannot contain special characters. Must be unique among the active companies on your account, on both create and update — a duplicate name is rejected. Renaming an existing company also rewrites its public menu URLs, so previously shared menu links for that company change.

categorystring

Business category for the company. Must be one of a fixed set of values, returned verbatim in the response's category field (note these are Title Case, not the SCREAMING_CASE used by other enums in this API): Dispensary, Delivery, Cultivator, Manufacturer, Distributor, Microbusiness, Lab, Retail, or Other. Any other value is rejected. Optional; left as-is when omitted on update.

legal_business_namestring

The company's registered legal business name, distinct from its display name. Left as-is when omitted on update.

default_emailstring

Primary email address for the company. Must be a valid email address when provided. Left as-is when omitted on update.

phone_numberstring

Phone number for the company. Free-text; not format-validated. Left as-is when omitted on update.

websitestring

Website URL for the company. Left as-is when omitted on update.

default_sales_order_notesstring

Notes pre-filled onto new sales orders created for this company. Left as-is when omitted on update.

default_purchase_order_notesstring

Notes pre-filled onto new purchase orders created for this company. Left as-is when omitted on update.

invoice_emailstring

Email address that invoices for this company are sent to. Left as-is when omitted on update.

sales_order_emailstring

Email address that sales orders for this company are sent to. Left as-is when omitted on update.

purchase_order_emailstring

Email address that purchase orders for this company are sent to. Left as-is when omitted on update.

order_shipment_emailstring

Email address that order shipment notifications for this company are sent to. Left as-is when omitted on update.

relationship_type_idstring

ID of the relationship type to assign to this company (surfaces as the relationship_type object in responses). Left as-is when omitted on update.

group_idstring

ID of the group to assign to this company (surfaces as the group object in responses). Left as-is when omitted on update.

owner_idstring

ID of the user who owns this company. Must be a user visible to the authenticated user under their team restrictions, otherwise the request is rejected. Left as-is when omitted on update.

default_payment_term_idstring

ID of the payment term applied by default to this company. Use GET /public/v1/payment-terms to look up available payment term IDs. Left as-is when omitted on update.

outstanding_balance_thresholdinteger

Outstanding-balance (unpaid invoice total) at which Distru starts showing warnings and sending alerts for this company. A positive integer in your account's currency major unit (e.g. whole dollars), compared directly against the company's outstanding balance. When null, the account-wide default threshold applies; when set, it supersedes that default. Left as-is when omitted on update.

qb_customer_idstring

Links this company to a QuickBooks Online customer. Must be a customer id present in your synced QuickBooks Online data, and each customer may be linked to only one company on your account. Left as-is when omitted; send null to unlink. Requires the settings_permissions_quickbooks permission.

qb_vendor_idstring

Links this company to a QuickBooks Online vendor. Must be a vendor id present in your synced QuickBooks Online data, and each vendor may be linked to only one company on your account. Left as-is when omitted; send null to unlink. Requires the settings_permissions_quickbooks permission.

leaflink_customer_idinteger

Links this company to a LeafLink customer. Must be a customer id present in your synced LeafLink data, and each customer may be linked to only one company on your account. Linking also reassigns that customer's existing LeafLink orders to this company. Cannot be set on a company that represents your own business. Left as-is when omitted; send null to unlink (existing orders keep their current company). Requires the companies_permissions_update_leaflink_data permission.

custom_dataobject

A map of custom field IDs to their values. Use GET /public/v1/custom-fields?parent_object=company to retrieve available custom fields, their IDs, and their types. The value format depends on the field's type: a text field takes a string, a date field takes a full ISO8601 datetime, and a checkbox field takes an array of its selected options. This replaces the whole custom-field map — any field you omit from the map is cleared, so send every value you want to keep. Fields configured as required must be present with a value or the request is rejected.

Response

An updated company relationship

Changes

No recorded changes to this endpoint across all 1 revision of this API.