Docs / API and agents
Supplier listing API
Read and save the optional tagline and rich text a supplier shows to customers in the Find vendors marketplace.
A supplier may add a short tagline and a longer "About your company" text to its marketplace listing. Both are optional: a supplier with neither is still listed, with its name, category and computed facts. Customers see the text on the supplier's card and page in Find vendors. The editor is the Listing tab of the Application form.
Who can use it#
A session that holds the builder.manage permission and belongs to an organization, the same bar as publishing the application form the listing advertises. Anyone else gets 403. The listing always belongs to the caller's own organization; there is no organization id in the path or the body.
Endpoints#
| Method and path | What |
|---|---|
GET /v1/listing | The caller's listing: { tagline, body, updatedAt }, each field null when empty. Answers private, no-store. |
PUT /v1/listing | Replaces both fields with { tagline, body } and returns the saved listing. |
Rules for the text#
tagline: one line, at most 140 characters. A line break is a 400.body: at most 6000 characters of Markdown.- Both are required keys in the request but may be empty. An empty string (or only whitespace) clears the field and is stored as
null. - Text is cleaned before it is checked: control characters are dropped, line endings are normalised, runs of blank lines collapse to one, and the ends are trimmed. The saved value, not the sent one, is returned.
The body is rendered with a fixed set of elements: paragraphs and line breaks, bold, italic, level 2 and 3 headings, bulleted and numbered lists, quotes and links. Images, tables and raw HTML are not rendered; their text stays, the element does not. Links must be http, https or mailto, and open in a new tab marked nofollow and ugc.
Errors#
| Status | When |
|---|---|
| 400 | A value is too long, the tagline has a line break, or the body is not an object with those fields. |
| 403 | No session permission builder.manage, or the session has no organization. |
The database also enforces both length limits.
Audit#
Every save records a listing.updated event on the organization, in the same transaction as the write, with the actor and, for support sessions, the impersonating user. The metadata holds the lengths of the tagline and body only, never the text.