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 and its locations with POST /public/v1/companies/{id}/locations 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 returns 404, and one your team restrictions hide returns 403.
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.
BearerAuthorizationBearer <token>API token generated in Distru (Settings → Distru API). Send it on every request as Authorization: Bearer YOUR_API_TOKEN.
application/json- body
id?stringID 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 (otherwise the request returns 404) that you can access under team restrictions (otherwise 403).
name?stringDisplay 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.
category?stringBusiness category for the company, returned verbatim in the response's category field (note these are Title Case, not the SCREAMING_CASE used by other enums in this API). Optional; left as-is when omitted on update. The allowed values depend on the US state of YOUR company (the CRM company inherits it): • Every state accepts Dispensary, Delivery, Cultivator, Manufacturer, Distributor, Microbusiness, Lab, and Other. • Outside Michigan, Retail is also accepted. Retail - Affiliated and Retail - Unaffiliated are rejected with a 400 whose message names your state (e.g. This category is not available for California companies). • In Michigan, Retail - Affiliated and Retail - Unaffiliated replace Retail. Sending Retail for a Michigan company is rejected with a 400 unless the company already has Retail saved, in which case it is kept until you change it. Any value outside these sets is rejected with a 400 is invalid.
legal_business_name?stringThe company's registered legal business name, distinct from its display name. Left as-is when omitted on update.
default_email?stringPrimary email address for the company. Must be a valid email address when provided. Left as-is when omitted on update.
phone_number?stringPhone number for the company. Free-text; not format-validated. Left as-is when omitted on update.
website?stringWebsite URL for the company. Left as-is when omitted on update.
default_sales_order_notes?stringNotes pre-filled onto new sales orders created for this company. Left as-is when omitted on update.
default_purchase_order_notes?stringNotes pre-filled onto new purchase orders created for this company. Left as-is when omitted on update.
invoice_email?stringEmail address that invoices for this company are sent to. Left as-is when omitted on update.
sales_order_email?stringEmail address that sales orders for this company are sent to. Left as-is when omitted on update.
purchase_order_email?stringEmail address that purchase orders for this company are sent to. Left as-is when omitted on update.
order_shipment_email?stringEmail address that order shipment notifications for this company are sent to. Left as-is when omitted on update.
relationship_type_id?stringID 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_id?stringID of the group to assign to this company (surfaces as the group object in responses). Left as-is when omitted on update.
owner_id?stringID 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_id?stringID 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_threshold?integerOutstanding-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_id?stringLinks 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_id?stringLinks 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_id?integerLinks 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_data?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.
An updated company relationship
*/*- response
A single company relationship
data?A business in your network — a customer, a vendor, or both. Holds contact details, locations, licenses, and the terms you deal on.
curl -X POST 'https://app.distru.com/public/v1/companies' \ -H 'Content-Type: application/json' \ -d '{ "id": "00000000-0000-0000-0000-000000000155", "name": "Updated Name"}'{ "data": { "category": "Delivery", "custom_data": [], "default_email": "[email protected]", "default_payment_term": null, "default_purchase_order_notes": null, "default_sales_order_notes": null, "deleted_at": null, "group": null, "id": "00000000-0000-0000-0000-00000001ae59", "inserted_datetime": "2026-11-05T10:59:44.268171Z", "invoice_email": null, "leaflink_brand_id": null, "leaflink_customer_id": null, "legal_business_name": "Company Legal Name 1938", "licenses": [ { "active": true, "expiry_datetime": "2026-12-05T10:59:44.262196Z", "id": "00000000-0000-0000-0000-000000006cf7", "inserted_datetime": "2026-11-05T10:59:44.262236Z", "issue_datetime": "2026-11-05T10:59:44.262195Z", "license_number": "CDPH-00000134", "license_type": "Type 11 Distributor" } ], "locations": [ { "address": "123 Fake Street, Beverly Hills, CA 90210, US", "company": { "id": "00000000-0000-0000-0000-00000001ae59", "name": "Updated Name", "updated_datetime": "2026-11-05T10:59:44.281964Z" }, "company_id": "00000000-0000-0000-0000-00000002c7b5", "id": "00000000-0000-0000-0000-00000001200c", "license_id": null, "name": "Place 492" } ], "name": "Updated Name", "order_shipment_email": null, "outstanding_balance": "0", "outstanding_balance_threshold": null, "owner": { "banned": false, "deleted_at": null, "email": "[email protected]", "full_name": "FirstName6302 LastName6303", "id": "00000000-0000-0000-0000-00000003da4f", "inserted_datetime": "2026-11-05T10:59:44.266228Z", "role": { "id": "00000000-0000-0000-0000-00000003f876", "name": "Admin 3337" }, "updated_datetime": "2026-11-05T10:59:44.266228Z" }, "owner_id": "00000000-0000-0000-0000-00000003da4f", "past_due_balance": "0", "phone_number": null, "purchase_order_email": null, "qb_customer_id": null, "qb_vendor_id": null, "relationship_type": null, "sales_order_email": null, "tasks": [], "updated_datetime": "2026-11-05T10:59:44.281964Z", "website": null }}