Create Supplier

Create a new supplier (or reuse an existing one with the same fingerprint) and link it to your organization.

Dedup behaviour

  • New fingerprint โ†’ a new global supplier row is inserted and your organization's link is created. Status 201.
  • Existing fingerprint, no prior link from your organization โ†’ your organization is linked to the existing global row. Status 200.
  • Existing fingerprint, already linked to your organization โ†’ no-op idempotent reuse. Status 200.
  • external_id already linked AND any supplied body field disagrees with the stored supplier โ†’ 409 CONFLICT. POST is not an edit channel; use PATCH /parties/suppliers/{id} instead. Omitted fields never conflict โ€” a re-POST that only re-states name and external_id of the existing row is still a 200 no-op.

For the first three cases the response body is the joined supplier view (identity fields from the global row + your organization's external_id from the link).

Attributes

FieldTypeRequiredDescription
namestringyes1โ€“512 chars
address_line1string | nullnoโ‰ค512 chars
address_line2string | nullnoโ‰ค512 chars
citystring | nullnoโ‰ค512 chars
regionstring | nullnoโ‰ค512 chars
postcodestring | nullnoโ‰ค512 chars
countrystring | nullnoISO 3166-1 alpha-2; lower-case accepted
statementstring | nullno1โ€“4000 chars
external_idstring | nullnoโ‰ค256 chars; per-organization

Invalid country codes, oversize fields, or unknown keys return 400. A duplicate external_id for your organization (already bound to a different supplier) also returns 400.

Required scope: parties:write