Manufacturers

A manufacturer is an entry in your organization's directory of the companies that make what you sell. It holds contact details, the country and the validity window of the authorization letter, links to catalog products, and is the base for price intelligence and authorization letters. The directory belongs to the whole organization: what a teammate adds, you see.

Reading the directory

Search the directory, read one manufacturer, or export the whole directory.

manufacturers_list

Lists the manufacturers in your organization's directory alphabetically, each with the number of catalog products linked to it. Search with plain words or with the directory's fielded syntax in q.

Read-only · scope manufacturers.read · all roles · Pro and Enterprise plans

{
  "q": "country:germany -name:acme",
  "page": 1,
  "page_size": 20
}

Returns: A page of manufacturers, each with its fields and product_count, the number of its live products, plus total, page, page_size and total_pages.

• A search the parser cannot read answers 400 with the reason.

manufacturers_get

Returns one manufacturer with all its fields and the number of catalog products linked to it.

Read-only · scope manufacturers.read · all roles · Pro and Enterprise plans

Returns: The manufacturer with its fields, among them contact_person, country_code, authorization_start_date, authorization_end_date and agency_type, plus product_count.

• Answers 404 when the manufacturer is not in your organization's directory.

manufacturers_export_csv

Exports the entire directory as CSV text: every row, not one page, with each manufacturer's product count. Limited to the owner and admin roles.

Read-only · scope export · roles: owner, admin · Pro and Enterprise plans

No parameters.

Returns: CSV text in UTF-8 with a byte order mark, with the columns ID, Name, Contact person, Country, Email, Phone, Website, Address, Notes, Agency type, Authorization start, Authorization end, Products and Created at.

• The country is exported as its two-letter code, a missing value is an empty cell, and Products counts live products. Attachment links are not exported because they expire quickly.
• The column names are the field names of the spreadsheet import, so the file can go back through sheet_import with the manufacturers target. The import only creates manufacturers whose names are not already in the directory.
• An Excel version of the same export is available to REST callers. See the API reference.

Adding, editing and deleting

Four tools edit the directory. All are open to the owner, admin, sales and purchasing roles.

manufacturers_create

Adds a manufacturer to your organization's directory. In the same call it can link existing catalog products to it or create new products under it. The name is unique, so a name already in use answers with a conflict.

Changes data · scope manufacturers.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "name": "Medline Europe GmbH",
  "contact_person": "Anna Keller",
  "email": "export@medline-europe.example",
  "country_code": "DE",
  "authorization_start_date": "2026-01-01",
  "authorization_end_date": "2027-12-31",
  "agency_type": "Distribution as authorized",
  "new_products": [
    {
      "product_name": "Syringe 5 ml with needle, sterile",
      "nupco_product_code": "4111610529900",
      "cost_price": 0.34,
      "cost_currency": "USD",
      "units_per_case": 1000
    }
  ]
}

Returns: The new manufacturer with its fields, plus product_count, linked_count (existing products linked), created_count (new products created) and created_products, the index and id of each new product in the order you sent them.

• The call checks the products and your plan's limit before it creates the manufacturer. It answers 400 with product_not_found for an ID that is not live, and 402 when the new products would pass your plan's product limit.
• The sales role cannot see cost prices, so cost_price and cost_currency are silently dropped from the new products, and sale_price_sar is kept.

manufacturers_update

Changes a manufacturer in the directory. Only the fields you send change, and null clears an optional field. To change the contact fields of many manufacturers at once, use manufacturers_bulk_update.

Changes data · scope manufacturers.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "id": 118,
  "phone": "+49 40 5550 1234",
  "authorization_end_date": "2028-12-31"
}

Returns: The manufacturer after the change.

• Answers 400 when the call names no field, and 409 with manufacturer_exists when the new name belongs to another manufacturer.
• Answers 404 when the manufacturer is not in your organization's directory.

manufacturers_delete

Deletes a manufacturer from the directory permanently. Its links to products are removed and its uploaded files are erased, while the products themselves stay in the catalog. It cannot be undone, and there is no trash for manufacturers.

Deletes or overwrites data · scope manufacturers.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Returns: A confirmation, success: true.

• Answers 404 when the manufacturer is not in your organization's directory.

manufacturers_bulk_update

Updates up to 200 manufacturers in one transaction: all succeed or nothing changes. Each row replaces the eight contact fields completely, so read the current values first and send every field, with null clearing a value.

Changes data · scope manufacturers.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "updates": [
    {
      "id": 118,
      "name": "Medline Europe GmbH",
      "contact_person": "Anna Keller",
      "country_code": "DE",
      "email": "export@medline-europe.example",
      "phone": "+49 40 5550 1234",
      "website": "https://medline-europe.example",
      "address": null
    },
    {
      "id": 121,
      "name": "Hartmann Medical AG",
      "contact_person": null,
      "country_code": "DE",
      "email": null,
      "phone": null,
      "website": null,
      "address": null
    }
  ]
}

Returns: The number of manufacturers changed, as updated.

• The notes, the authorization dates and the agency type are not part of this tool and are never touched. To change them, use manufacturers_update.
• An ID that is not in your organization rejects the whole batch with 400 and manufacturer_not_found, and a name that matches another manufacturer rejects it with 409 and manufacturer_exists. In both cases nothing changes.

Price intelligence

Price analysis for one manufacturer, computed from the quotes recorded in your organization only. Because it is cost data, it needs the Pro or Enterprise plan and the owner, admin, purchasing or viewer role.

manufacturer_intel_get

Shows how a manufacturer's prices have moved, computed from the quote lines it gave your organization on RFQs and recorded supplier prices: each product's price series, the change from the first quote to the last, and products quoted at different prices. It also returns the stored AI summary when one exists, and never writes a new one: that is the job of manufacturer_intel_generate.

Read-only · scope manufacturers.read · roles: owner, admin, purchasing, viewer · Pro and Enterprise plans

Returns: facts: lineCount, responseCount, productCount, firstQuoteAt, lastQuoteAt and medianPctChange, the products list (each with label, series of dated prices, firstUsd, lastUsd, minUsd, maxUsd, pctChange, trend and spreadPctMaxOverMin), and the shortlists topIncreases and topSpreads. ai: the stored summary (headline_en, headline_ar, body_en, body_ar, model and generated_at) or null. And ai_stale.

• All prices are in USD. pctChange compares the last quote with the first and is null for a product with fewer than two quotes, which means no trend, not zero. trend is flat within 2%, otherwise up or down. spreadPctMaxOverMin is the gap between the highest and lowest price as a share of the lowest, and is null unless two different prices exist.
• Only quotes attributed to this manufacturer in your directory count, not quotes recorded under a free-text supplier name. A manufacturer with no quotes returns zeroed facts.
• ai_stale: true means the quote data changed since the summary was written.
• Answers 404 when the manufacturer is not in your organization's directory.

manufacturer_intel_generate

Writes, or refreshes, the stored bilingual AI summary of a manufacturer's price intelligence. It narrates the figures that manufacturer_intel_get returns and adds no figure of its own. It runs the model only when the manufacturer's quotes changed since the last summary, and otherwise returns the stored one at no cost.

Changes data · scope manufacturers.write · roles: owner, admin, purchasing · Pro and Enterprise plans

Returns: ai with the summary (headline_en, headline_ar, body_en, body_ar, model and generated_at) and ai_stale: false. Instead you may get ai: null with no_data: true (no priced quotes to narrate) or disabled: true (the feature is switched off), or a 202 with status: "generating" while another request is writing it.

• On a 202, call manufacturer_intel_get a little later to read the summary.
• After a failed attempt the call answers 503 with a message and does not try again for ten minutes.
• The summary is written from the aggregated price figures alone, not from contact details or notes.
• Answers 404 when the manufacturer is not in your organization's directory.

Authorization letters

A ready-to-print authorization letter, issued by the manufacturer in favor of your organization.

manufacturer_letter_pdf

Generates an authorization letter PDF for a manufacturer. The top and bottom of the page are left blank so you can print it on the manufacturer's own letterhead for them to sign. The letter is in English, dated today, and names your organization's legal name in English as the distributor. Nothing is stored: every call generates it again.

Read-only · scope manufacturers.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "id": 118,
  "letter_type": "new_relation",
  "tender_number": "NPT0042/26"
}

Returns: A PDF file: filename, content_type, size_bytes and the content as base64 in base64.

• The manufacturer's address is not printed: a blank line is left for the signatory to fill in.
• The tool changes nothing, yet it needs the manufacturers.write scope and the editing roles, like the screen that creates the letter.
• Answers 404 when the manufacturer is not in your organization's directory.