Documentation menu

Suppliers reference

The caller org's supplier pool (read).

GET/suppliers

List the org supplier pool (manager+)

Parameters

NameInTypeRequiredDescription
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.
pagequeryintegeroptionalPage number to retrieve (1-based); integer, minimum 1, defaults to 1.
limitqueryintegeroptionalPage size (number of records per page); integer, minimum 1, maximum 100, defaults to 25.
includeDisabledquerybooleanoptionalWhen true, include disabled (unlinked) supplier pool entries in the list; by default only active entries are returned.

Responses

  • 200Paginated suppliers.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
POST/suppliers

Add a supplier to the pool (managers+). Creates the supplier user if needed.

Parameters

NameInTypeRequiredDescription
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.
pagequeryintegeroptionalPage number to retrieve (1-based); integer, minimum 1, defaults to 1.
limitqueryintegeroptionalPage size (number of records per page); integer, minimum 1, maximum 100, defaults to 25.
includeDisabledquerybooleanoptionalWhen true, include disabled (unlinked) supplier pool entries in the list; by default only active entries are returned.
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Request body SupplierAdd (required, application/json)

Responses

  • 201Pool entry.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 402Plan quota reached for this resource (code `QUOTA_EXCEEDED`).
  • 403Authenticated but not allowed (role or cross-org).
  • 409Conflict.
  • 429Rate limit exceeded.
GET/suppliers/{id}

Get a supplier from the org pool (manager+)

Parameters

NameInTypeRequiredDescription
idpathstringrequired
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Responses

  • 200The supplier.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
  • 404Not found (or not in the caller's org).
DELETE/suppliers/{id}

Remove from the pool (managers+) — disables if the supplier has live events, else unlinks.

Parameters

NameInTypeRequiredDescription
idpathstringrequired
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Responses

  • 200{outcome: 'DISABLED'|'UNLINKED', supplier}.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
  • 404Not found (or not in the caller's org).
  • 429Rate limit exceeded.
POST/suppliers/{id}/enable

Re-enable a disabled supplier (managers+)

Parameters

NameInTypeRequiredDescription
idpathstringrequiredSupplier pool doc id.
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Responses

  • 200Enabled supplier.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
  • 404Not found (or not in the caller's org).
  • 409Conflict.
  • 429Rate limit exceeded.
POST/suppliers/{id}/events

Assign the supplier to an event (managers+). The event must be in the caller org.

Parameters

NameInTypeRequiredDescription
idpathstringrequiredSupplier pool doc id.
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Request body SupplierAssign (required, application/json)

Responses

  • 201Updated pool.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
  • 404Not found (or not in the caller's org).
  • 409Conflict.
  • 429Rate limit exceeded.
DELETE/suppliers/{id}/events/{eventId}

Unassign the event (soft — status REMOVED, managers+)

Parameters

NameInTypeRequiredDescription
idpathstringrequiredSupplier pool doc id.
eventIdpathstringrequired
X-Organization-IdheaderstringoptionalTarget organization ObjectId; required for APP_ADMIN and SUPPLIER callers and ignored (must match the caller's own org) for org admins, managers, and users.

Responses

  • 204Unassigned.
  • 400Request body/params failed validation.
  • 401Missing/invalid token.
  • 403Authenticated but not allowed (role or cross-org).
  • 404Not found (or not in the caller's org).
  • 429Rate limit exceeded.

Supplier schema

FieldTypeRequiredDescription
_idstringoptionalServer-generated unique identifier of the supplier pool entry (read-only).
organizationIdstringoptionalIdentifier of the organization that owns this supplier pool entry; server-controlled and bound from the caller's tenant context, never the request body.
supplierIdobjectoptionalThe populated supplier User record (firstName, lastName, email, companyName) linked to this pool entry.
statusPENDING | ACCEPTED | DECLINEDoptionalThe supplier's invitation/acceptance state — one of PENDING, ACCEPTED, or DECLINED.
poolStatusstringoptionalThe supplier's pool membership state — one of pending_invite, invited, connected, or active.
categorystringoptionalOptional supplier category; one of Venue, Catering, Transport, Accommodation, Printed Materials, AV & Production, or Other.
disabledAtstring (date-time)optionalTimestamp when the supplier was soft-disabled in the pool, or null if active; server-controlled.

SupplierAdd schema

FieldTypeRequiredDescription
emailstring (email)requiredRequired email address of the supplier user to invite and add to the pool.
firstNamestringoptionalOptional first name of the supplier contact.
lastNamestringoptionalOptional last name of the supplier contact.
companyNamestringoptionalOptional company name of the supplier.
categorystringoptionalOptional supplier category to record for the pool entry; one of Venue, Catering, Transport, Accommodation, Printed Materials, AV & Production, or Other.
notestringoptionalOptional free-text message included in the invitation email to the supplier.

SupplierAssign schema

FieldTypeRequiredDescription
eventIdstringrequiredRequired identifier of the event to assign the supplier to; verified to belong to the caller's organization server-side.
eventParamsarray of stringoptionalOptional array of carbon-source category keys (the *_PARAMETER vocabulary) the supplier is responsible for on the event.
reductionStrategyIdsarray of stringoptionalOptional array of reduction-strategy identifiers assigned to the supplier for the event.
datestring (date-time)optionalOptional due date for the supplier's assignment to the event.
notestringoptionalOptional free-text note with brief instructions or context for the supplier on this assignment.