Organizations

The buying company on revenexx — commercial terms, the three access axes, addresses, and the organization_metrics projection with its chunked refresh and freshness check.

An organization is the buying company: the unit a contract, a credit limit and a price list belong to. Its people are contacts.

Request

curl "https://api.revenexx.com/v1/customers/organizations?limit=50" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..."

The list also filters on these columns, each an exact match (timestamps match exactly, as there is no range filter):

Filter	What it matches
`block_reason`, `block_note`, `blocked_by`, `blocked_at`	The order block: why it was set, the note on it, who set it and when. Null while the company may order.
`delivery_block_reason`, `delivery_blocked_by`, `delivery_blocked_at`	The delivery block: why it was set, who set it and when. Null while shipments go out.
`account_manager_name`	The name of the company's responsible sales rep.
`city`	The city the company is listed under, from its addresses.
`credit_available`	The credit limit minus the open balance. Null where no limit is set.
`credit_utilisation`	The share of the credit limit in use, in whole percent. Null where no limit is set.
`last_order_at`	When the company last ordered.
`revenue_365d`	Revenue of the last 365 days.
`primary_contact_id`	The one contact marked as the company's main contact.
`parent_organization_id`	The head office, when this company is a subsidiary of a group.

The row

Field	Meaning
`name`	Legal or trading name of the company, never a person.
`customer_number`	The number the company carries in the merchant's own ERP — the key an ERP integration joins on. Free text, no enforced format.
`vat_id`	VAT identification number — the closest thing a B2B buyer has to a legal identity. How far it is checked is the market's `vat_id_validation` setting: `off` (default) stores it as typed, `format` checks the country prefix and national pattern, `vies` also asks the EU VIES registry. Only a definitive "not registered" answer is refused (`400`, naming the registry). A registry that is unreachable, times out or reports the member state unavailable never refuses the write, and the response does not say the check was skipped. A number outside the EU is not sent to VIES, and an update re-checks only a changed VAT id. `organization_vat_id_required` is a separate setting: it makes a self-registration that founds a company supply one.
`external_id`	The company's key in the system that owns it, such as the ERP's own customer key. Not the number a human quotes: that is `customer_number`. Writable on create and update, stored verbatim, unique per tenant while set, so an import upserts on it. Filter with `?external_id=`. Null for a company created in the shop.
`external_refs`	Every other system that knows the company, keyed by system name, such as `{"gln": "4012345000009"}`. Not a query filter.
`branche`	Industry, in the merchant's own words. Free text — no code list. Segment rules match it exactly and case-sensitively.
`status`	`active` or `blocked`. Access, not pipeline.
`lifecycle_stage`	Where the company stands in the sales pipeline. One of the tenant's own lifecycle stages.
`delivery_block`	`true` stops shipments while leaving login and ordering alone.
`credit_limit_mode`	Whether the company buys on credit, and how far: `unset` (nobody decided, so whoever checks credit applies its own fallback), `limited` (open receivables up to `credit_limit`) or `unlimited` (no ceiling, by decision). Read the mode to know whether there is a ceiling. A create that sends neither field inherits the market's default mode and amount, which may be `limited`, so an import should send the mode it means.
`credit_limit`	Ceiling on open receivables in the market's currency. Set exactly when `credit_limit_mode` is `limited`, and then above 0; null for every other mode, so a null amount says nothing on its own.
`payment_terms`	One of the tenant's own payment terms. Null falls back to the market's `default_payment_terms`.
`price_list`	The code of the price list this company buys on. Plain text pointing into the prices app; nothing here validates it, so a code naming no list simply prices nothing.
`settings`	Free-form per-organization settings. This app never branches on a key in here — but a segment rule can address a top-level key as `setting:<key>`, which is what the blob is for.
`external_team_id`	The platform team this organization is mirrored as, which is what makes its people a team for storefront auth. Written by the platform, ignored on any write you send.

Organizations are flat. There is no parent, no sub-organization and no business unit below a company (as of 2026-09). Cost centers group spend inside one organization, but they are a flat list too, not a hierarchy. A group with several legal entities is modelled as several organizations.

Two ways to stop a company, and a limit that does not

status: "blocked" stops the company's people logging in. It is also where a rejected registration parks the company it founded.
delivery_block: true stops shipments and leaves login and ordering alone — the "they may order, we are just not sending anything until this is settled" state.

Blocking the login to stop a delivery locks out exactly the people who could settle the invoice. Use delivery_block.

The credit limit does not stop anything. credit_limit_mode and credit_limit are stored, not enforced (as of 2026-10). They record a decision, and nothing on the platform compares them with an order or an open balance: orders are accepted and payment methods offered whatever their values. If you want a credit check, run it in your own system, for example before you place the order, and decide there what unset means for you.

Send the mode and the amount together. The API refuses a pair that does not fit with 400:

Code	When
`limited_mode_requires_limit`	`credit_limit_mode` is `limited` and no `credit_limit` is sent or stored.
`limit_requires_limited_mode`	A `credit_limit` is sent with `unset` or `unlimited`.
`limit_not_positive`	The amount is 0 or below.
`invalid_mode`	The mode is not one of the three values.

Switching away from limited needs only the mode: the stored amount is cleared with it.

Request

curl -X PUT https://api.revenexx.com/v1/customers/organizations/{id} \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{"credit_limit_mode": "limited", "credit_limit": 5000}'

A buyer acting for themselves, that is a storefront call made on a signed-in buyer's behalf, gets 403 (self_service_closed) on this call under self_service_master_data set to addresses_only or none, once the buyer checks pass: another company's id is 403 (not_own_record) and a buyer without the organization.manage grant 403 (not_self_service), whatever the setting says. A call that does not act for a buyer, such as an operator, an import or an ERP, is not refused for this reason.

A null credit_limit no longer means "no limit". If a company may buy without a ceiling, set credit_limit_mode to unlimited. A company written before the mode existed reads credit_limit_mode: "unset", with its old amount still in credit_limit if it had one. The next write that sends either field treats such an amount as limited. To be unambiguous, send the mode for every company you sync.

Addresses

Addresses live in their own entity at /v1/customers/addresses, and at least one of organization_id / contact_id is set: a company address shared by everyone in it, or a personal one only that contact uses. Both may be set when the contact belongs to that organization. The API reference still says exactly one of the two is set and that sending both is refused; the API accepts both when the contact belongs to that organization, as described here.

Address

{
  "organization_id": "…",
  "type": "shipping",
  "is_default": true,
  "name": "Wareneingang",
  "company": "Beispiel Industrietechnik GmbH",
  "street": "Industriestraße 14",
  "street2": "Tor 3",
  "zip": "80331",
  "city": "München",
  "country": "DE"
}

Field	Note
`type`	One of the tenant's own address types, seeded with `billing` and `shipping`. A merchant can add their own.
`is_default`	One default per owner and type. Setting it moves the flag off the previous holder.
`street`	Text, optional on write (leave it out rather than send null or an empty string); it can be null on read. Street and house number on one line, as the local post expects it. It can be left out: a German PO box is addressed by its number, its postcode and its town. The address type calls it `address_line1`.
`street2`	Text, nullable. The second address line. The address type calls it `address_line2`.
`address_line3`	Text, nullable. The third address line, where a country prints one. Null when there is none.
`house_number`	Text, nullable. The house number on its own, beside `street_name` (the street on its own, for a system that keeps the two apart). `street` is what the label prints.
`city`	Text, nullable. City or town. Null only where the country's rules do not ask for one. The address type calls it `locality`.
`zip`	Text, nullable. Leading zeros are real in most countries. The address type calls it `postal_code`.
`country`	Text, never null: ISO 3166-1 alpha-2, exactly two letters. What shipping and tax both key off. The address type calls it `country_code`.
`region`	Text, nullable. State, province or Bundesland, as written. Required by some destinations (US, CA, BR, IT, ES, JP, CN, IN), unused by most European ones. The address type calls it `administrative_area_name`.
`administrative_area_code`	Text, nullable. The region as an ISO 3166-2 code (`US-CA`, `BR-SP`), what shipping and tax read. Checked against the country's list where it has one. An address stored before the code existed answers the code its `region` names, when the country lists it.
`delivery_point_id`	Text, nullable. The number of the delivery point: the Packstation, the PO box.
`company`	Often the owning organization's name, but not always — a delivery to a construction site carries the site.

GET /v1/customers/addresses filters by exact match on the text fields in this table (for example ?city=München or ?administrative_area_code=US-CA), among them street, city, region, country, address_line3, administrative_area_code, house_number and delivery_point_id. The filters take the names in the table's first column, not the address type's names.

Add an address

Route What it does

POST /v1/customers/addresses Adds a postal address. Send organization_id, contact_id, or both when the contact belongs to that organization. Neither answers 400 (address_owner_required), and a contact of another company answers 400 (contact_not_in_organization). country is required, or country_code when the body uses the address type's names (one naming scheme per request, see below), and each country's rules for the postal code, town and state are checked (400, address_invalid). type is optional and defaults to the tenant's default address type. Answers 201 with the stored row. An external_id already taken in the tenant answers 409. A buyer acting for themselves gets 403: not_own_record for an owner that is not theirs, not_self_service for a company address without the addresses.manage grant, and, once those two checks pass, self_service_closed when self_service_master_data is none.

Route	What it does
`POST /v1/customers/addresses`	Adds a postal address. Send `organization_id`, `contact_id`, or both when the contact belongs to that organization. Neither answers `400` (`address_owner_required`), and a contact of another company answers `400` (`contact_not_in_organization`). `country` is required, or `country_code` when the body uses the address type's names (one naming scheme per request, see below), and each country's rules for the postal code, town and state are checked (`400`, `address_invalid`). `type` is optional and defaults to the tenant's default address type. Answers `201` with the stored row. An `external_id` already taken in the tenant answers `409`. A buyer acting for themselves gets `403`: `not_own_record` for an owner that is not theirs, `not_self_service` for a company address without the `addresses.manage` grant, and, once those two checks pass, `self_service_closed` when `self_service_master_data` is `none`.

One address by id

Route	What it does
`GET /v1/customers/addresses/{id}`	Reads one address, whichever of the two owners it hangs off.
`PUT /v1/customers/addresses/{id}`	A partial update: send only what changes. An empty body is refused. The owner is fixed: changing `organization_id` or `contact_id` is a `400` (`field_immutable`); create the address on the other owner instead. A buyer acting for themselves gets `403` (`self_service_closed`) under `self_service_master_data` set to `none`, once the buyer checks below pass; a call that does not act for a buyer is not refused for this reason.
`DELETE /v1/customers/addresses/{id}`	Removes the address. Orders already placed keep the address they were placed with. Contact points that point at it are removed with it, and a point removed this way does not hand its flag on: flag another point of that kind yourself. A buyer acting for themselves gets `403` (`self_service_closed`) under `self_service_master_data` set to `none`, once the buyer checks below pass; a call that does not act for a buyer is not refused for this reason.

When a buyer changes or deletes an address that is not theirs, the call is refused with 403 (not_own_record), and a company address also needs the addresses.manage grant (403, not_self_service). Those buyer checks come first on all three write routes: self_service_closed is the answer only for a buyer who passes them. A delete with an unknown id is a 404.

Address formats

Every country prints an address differently: which lines it has, which of them it requires, what a postal code looks like. Two read-only operations return those rules. They are the same for every tenant: a contract, not data.

GET /v1/customers/address-format returns countries, every country with rules (code, and name in English and German, sorted by code), and schema, the address type as a JSON Schema (2020-12). The schema carries a versioned $id, https://schemas.revenexx.com/apps/customers/address/1.1.0.json, that an app can pin its copy by. The type itself requires only country_code.
GET /v1/customers/address-format/{country} returns the rules of one country. {country} is an ISO 3166-1 alpha-2 code in upper case; an unknown code returns 404.

Request

curl "https://api.revenexx.com/v1/customers/address-format/DE" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..."

The response for one country carries these keys, besides code, name (English and German) and schema (the $id of the address type the rules apply to):

Key	What it tells you
`fields`	The fields this country uses, in the order they are printed.
`required`	The fields an address there cannot leave empty. A region is in `required` only where the country demands one.
`postal_code`	A `pattern` the whole code must match, and an `example` (which can be `null`). The whole object is `null` where the country has no postal codes.
`labels`	The English and German word a form shows for each field whose name varies by country.
`regions`	The regions as ISO 3166-2 `code`. Where the data names a region only in words, `code` is `null`, and the address gives the region by name in `administrative_area_name`.
`contact_fields`	`phone` and `email`. Every country takes them, they are optional, and they are never printed.
`format`	The print layout, in libaddressinput notation: `%N` recipient, `%O` organization, `%A` address lines, `%D` dependent locality, `%C` locality, `%S` region, `%Z` postal code, `%X` sorting code, `%n` line break.
`latin_format`	The print layout for the Latin-script form of the address, where it differs by script.
`upper`	The fields printed in capitals when the address is printed for a sender in another country. A domestic address prints as written.

Here is a shortened response, with the example values from the API reference (illustrative, not a promise about any one country):

Response

{
  "code": "DE",
  "fields": ["recipient_name", "organization_name", "address_line1", "address_line2", "address_line3", "postal_code", "locality"],
  "required": ["address_line1", "locality", "postal_code"],
  "postal_code": { "pattern": "\\d{5}", "example": "26133" },
  "format": "%N%n%O%n%A%n%Z %C",
  "contact_fields": ["phone", "email"]
}

An address has two naming schemes: the storefront names in the table (street, street2, zip, city, region, country) and the address type's names (address_line1, address_line2, postal_code, locality, administrative_area_name, country_code, and for the recipient fields organization_name, recipient_name and care_of, which stand for company, name and name2). They name the same fields. If a body uses any of the address type's names, it is read in those names alone: the storefront names beside them (street, street2, zip, city, region, country, company, name, name2) are ignored, so pick one scheme per request. That way a record read from the API and sent back saves unchanged. Use the rules to build or check an address form for one country before you POST to /v1/customers/addresses: print the fields in order, mark the required ones, check input against postal_code.pattern, and keep contact_fields out of the printed address.

Buying metrics

organization_metrics is a materialized projection: one row per organization, with what it bought. Revenue lives in the orders app and cannot be joined across apps, so it is pulled and stored here.

Request

curl "https://api.revenexx.com/v1/customers/organization_metrics?limit=50" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..."

Field	Meaning
`order_count`, `revenue_total`	Ever, in `currency`.
`order_count_30d/90d/365d`, `revenue_30d/90d/365d`	Rolling windows measured back from `orders_as_of`, not calendar months.
`avg_order_value`, `avg_order_value_365d`	Computed from the sums. Zero when there were no orders.
`first_order_at`, `last_order_at`	Null if the company never ordered — which is what makes them usable as "is this a customer at all?".
`currency`	The single currency all counted orders were in. Null when there were none, and also when there were several.
`currency_mixed`	`true` when the company ordered in more than one currency. The sums are still stored, but they are not comparable against a threshold.
`orders_as_of`	The instant the rolling windows were measured from.
`computed_at`	How stale the numbers are.

Rows exist for companies that never ordered — all zeros rather than missing, so a "never bought" rule matches something.

Refreshing, in a loop

Request

curl -X POST https://api.revenexx.com/v1/customers/organization_metrics/refresh \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{}'

The refresh walks organizations in id order, asks the orders app for a rollup of a batch at a time, and materializes the answer. Rows are only rewritten when a value actually changed, so a routine refresh costs almost no writes.

It is bounded by a wall-clock budget. While done is false, POST again with the returned cursorandas_of. Pinning as_of is what stops the rolling windows sliding underneath a multi-call refresh.

For the targeted case — a company just ordered — send organization_ids and it refreshes exactly those in a single call.

GET /v1/customers/organization_metrics/freshness answers how stale the projection is, which is what a "last updated" indicator and a scheduled job's decision to run should read.

Activity from the company page

Request

curl -X POST "https://api.revenexx.com/v1/customers/organizations/{id}/events" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{"contact_id":"…","kind":"call","subject":"Annual pricing review"}'

Timeline entries are always filed against a person, even when they are logged from the company page — see Contacts.

Account actions

Each action is one decision on one company, with its reason on the record. Use the action rather than a field edit when the change has a reason to keep: the block, the credit change and the rep and contact changes each have their own call. Every call answers 404 when the company does not exist. Reason codes are stored as their words in the tenant's default language.

Operation	What it does	Body
`POST /v1/customers/organizations/{id}/block`	Blocks ordering or shipping, with a reason. `kind: order` sets `status` to `blocked`, so every contact behind the company stops buying and `organization.blocked` is published. `kind: delivery` sets `delivery_block`: orders are still taken and nothing ships. Both land on the timeline as a system entry. A company that already carries that block answers `409 already_blocked`.	`reason` string, required, one of `payment_overdue`, `credit_exceeded`, `insolvency`, `dispute`, `compliance`, `customer_request`, `other`. `kind` string, optional, `order` (default) or `delivery`. `note` string or null, optional. `actor` string or null, optional.
`POST /v1/customers/organizations/{id}/unblock-order`	Lifts the order block. The reason, note, time and who are cleared from the record, and the lifting lands on the timeline. `409 not_blocked` when there is no such block.	`note` string, required, at least one character: why the block is lifted.
`POST /v1/customers/organizations/{id}/unblock-delivery`	Lifts the delivery block. `delivery_block_reason`, `delivery_blocked_at` and `delivery_blocked_by` are cleared, and the note lands on the timeline. `block_note` is not cleared. `409 not_blocked` when there is no such block.	`note` string, required, at least one character.
`POST /v1/customers/organizations/{id}/change-credit`	Changes the credit mode, and the amount for `limited`, with a reason, so the timeline shows what it was, what it is and why. The same rules as an edit apply: `limited` needs an amount, any other mode clears it. A request with neither field answers `400`.	`reason` string, required, one of `rating_changed`, `volume_changed`, `payment_behaviour`, `customer_request`, `other`. `credit_limit_mode` string, optional, `unset`, `limited` or `unlimited`. `credit_limit` number or null, optional, for `limited`. `note` string or null, optional.
`POST /v1/customers/organizations/{id}/set-account-manager`	Makes a sales rep the company's responsible rep. Responsibility lives in the sales-reps app, so the call asks that app to record the coverage and to name the rep responsible. The rep's name is copied to `account_manager_name`, and the change lands on the timeline. An unknown code answers `400 unknown_rep`. If the sales-reps app refuses the call, the answer is `400 sales_reps_refused`; if it cannot be reached, `502`. This App's record is unchanged either way; the sales-reps app may already hold the assignment.	`rep_code` string, required: the rep's code in the sales-reps app.
`POST /v1/customers/organizations/{id}/set-primary-contact`	Makes one person of the company the main contact, the recipient of documents and invitations, and releases whoever held the role. `primary_contact_id` follows. Naming the current main contact again changes nothing.	`contact_id` string (uuid), required: a person of this company. A person of another company answers `400`.
`GET /v1/customers/organizations/{id}/care`	Reads who looks after the company, the same card the company page shows. The rep fields come from the sales-reps app and are `null` when that app cannot be asked; the main contact is still named.	None.

What this App does with the credit amount. change-credit stores the mode and the amount, with the reason on the timeline. This App does not itself check an order against them: whoever checks credit reads them. See the credit limit.

What care returns. GET .../care returns account_manager, account_manager_code, account_manager_phone and account_manager_email for the rep, and main_contact, main_contact_id, main_contact_phone and main_contact_email for the main contact.

Request

curl -X POST https://api.revenexx.com/v1/customers/organizations/{id}/block \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "payment_overdue", "kind": "delivery", "note": "Invoice 4711 is 45 days overdue"}'

Founding a business customer in one call

POST /v1/customers/organizations/onboard creates the company, its billing address, its main contact and its responsible sales rep in one request. It answers 201 with the stored organization and primary_contact, the person founded with it (or null). The company and the person go through the same checks as their plain creates. If a step fails after the company exists, the call takes everything it founded back out. An unknown rep code, or a sales-reps app that cannot be reached, founds the customer without a rep. A field the API does not know answers 400 unknown_field. An identity or messaging service that cannot be reached answers 502, and nothing stays founded.

Any billing field makes billing_street, billing_zip and billing_city required, or the call answers 400 billing_incomplete. send_invite is on by default, so a call that gives a main contact sends that person the shop invitation at once, unless it sets send_invite: false. A test call therefore sends a real invitation unless you set send_invite: false. With no link origin configured for the shop, the invitation has nowhere to point: the call answers 400 and takes back what it founded.

The invitation mail goes out before the sales-rep and timeline steps. If one of those fails, the records are taken back, but the mail has already been sent. A duplicate under the duplicate keys the tenant enables for companies (vat_id by default, or name and customer_number) answers 409 duplicate_record, checked before anything is written. A customer_number or external_id held by a company in the trash answers 409 in_trash. The spec's 409 text, "a duplicate under the tenant's duplicate keys, or a reserved value", covers these two cases.

Field	Type	Required	Meaning
`name`	string	yes	The company name.
`customer_number`	string or null	no	The number the customer quotes.
`vat_id`	string or null	no	The VAT ID.
`branche`	string or null	no	The industry.
`lifecycle_stage`	string or null	no	A lifecycle stage code. The tenant's default when absent.
`payment_terms`	string or null	no	A payment terms code. The tenant's default when absent.
`billing_street`	string or null	no	Billing address: street and number. Required together with `billing_zip` and `billing_city` once any billing field is sent.
`billing_zip`	string or null	no	Billing address: postal code. Required together with `billing_street` and `billing_city` once any billing field is sent.
`billing_city`	string or null	no	Billing address: city. Required together with `billing_street` and `billing_zip` once any billing field is sent.
`billing_country`	string or null	no	Billing address: ISO 3166-1 alpha-2. `DE` when absent.
`account_manager`	string or null	no	The responsible sales rep's code.
`contact_first_name`	string or null	no	Main contact: first name.
`contact_last_name`	string or null	no	Main contact: last name.
`contact_email`	string or null	no	Main contact: email. With a main contact, give either this or `contact_username`.
`contact_phone`	string or null	no	Main contact: phone.
`contact_role`	string or null	no	Main contact: role key. The tenant's default when absent.
`contact_job_title`	string or null	no	Main contact: job title.
`contact_username`	string or null	no	Main contact: login name, which can stand in for `contact_email`.
`contact_locale`	string or null	no	Main contact: locale.
`send_invite`	boolean	no	Whether the main contact is invited to the shop now. `true` when absent. Only a call that gives a main contact sends an invitation.

Recomputing the derived columns

POST /v1/customers/derived/refresh recomputes every derived column from the rows as they stand: each company's city, revenue_365d, last_order_at, primary_contact_id and account_manager_name, each person's shop_access, and how many people hold each role. Every write already keeps these up to date. Use the call for rows written around the API, such as a direct table import. It writes only the values that are wrong, so repeating it is safe. The scheduled metrics refresh runs it too, after each run that the metrics_refresh_schedule tenant setting makes due: daily by default, hourly, or off. It takes no body.

Trash and restore

DELETE /v1/customers/organizations/{id} moves a company to the trash. Its live contacts go with it as one group: their logins are switched off and their sessions end, and nothing is deleted. Contacts already in the trash stay there. It is refused with 409 (trash_blocked) while one of its people is the approver on a pending approval. A second DELETE on the same id deletes the company for good, together with the contacts that went to the trash with it and their platform logins. That is refused with 409 (delete_blocked) while other apps still hold it. Deleting for good is an administrator's: a buyer's call gets 403 (purge_not_allowed).

POST /v1/customers/organizations/{id}/restore brings an organization back from the trash. Restore needs the same right as the delete.

The contacts that went with it come back too: the ones that carry the organization's trash_batch. A contact trashed on its own before stays in the trash. Their logins are switched back on unless the record says no (blocked, or an undecided registration).
409, not_in_trash, when the organization is not in the trash.
404 when no organization has that id.

POST /v1/customers/organizations/trash/empty deletes every organization in the trash for good, oldest first, at most 50 per call. Each one is checked on its own, as a second DELETE would be. An organization that something still blocks stays in the trash and is listed in blocked with the reason. Call again while more is true. Emptying the trash is an administrator's right: a buyer's call is refused with 403, purge_not_allowed.

Reading and filtering the trash. GET /v1/customers/organizations takes trashed: exclude (the default) leaves trashed organizations out, only returns the trash alone and include returns the live and the trashed organizations together. Each organization carries the fields below, and each one is also an exact-match filter on the list call. A call that acts for a buyer always behaves as exclude, whatever trashed says. deleted_at and purge_at match only an exact timestamp; there is no range filter, so to see what was trashed in a period, sort with order and page.

Field	What it holds
`deleted_at`	When the organization went to the trash; null while it is live.
`deleted_by`	Who moved it there: an e-mail, or `system`. A name for the trash view, not an identity to check.
`deleted_by_id`	The platform subject of that person, the stable id a privacy request pseudonymises. Null for the system.
`purge_at`	When the daily purge deletes it for good: `deleted_at` plus the tenant's trash retention (90 days unless the tenant says otherwise).
`trash_batch`	The trash action it went with. The contacts it took along share the same value, and a restore brings back exactly the records that carry it.
`purge_blocked_reason`	Why the purge could not delete it for good, in a sentence; null when nothing held it. Cleared by a restore.

The platform sets these fields when an organization is deleted and clears them when it is restored. They are information to read, so do not send them in a write.

The first delete fires organization.trashed and a restore organization.restored. organization.deleted fires only once the record is deleted for good. See Deletes and the trash.

Where to go next

Contacts — the people inside the company.
Segments — grouping companies by these columns and metrics.
Sales reps — which rep looks after the company, and who is responsible.
Value lists — payment terms, address types, lifecycle stages.
Price lists — what price_list points at.

Was this page helpful?