Skip to main content
Admin

Public API

API documentation, fair use policy, webhooks.

Written By Victor Raessen

Last updated 12 days ago

Public API

The Salesbuildr API lets you programmatically access and manage your data. Use it to build custom integrations, automate workflows, or connect Salesbuildr to tools that aren't covered by the built-in integrations.

Note: The Public API is a feature that must be enabled for your account.

API overview

The API follows REST conventions with JSON request and response bodies.

Base URL

All API requests use your tenant-specific URL:

https://[your-tenant-name].salesbuildr.com/public-api/

Authentication

Authenticate by passing your API key in the api-key header:

api-key: your-api-key-here

Generate API keys at Settings > Integrations > API Key. Only users with the Admin role can generate or regenerate keys.

Documentation

Full API specifications are available at:

  • API reference β€” https://portal.salesbuildr.com/public-api#/ (Redocly docs)
  • Interactive docs β€” https://[your-tenant].salesbuildr.com/public-api/swagger (Swagger UI)
  • Webhook docs β€” https://[your-tenant].salesbuildr.com/public-api/webhooks

Available resources

The API provides access to 14 resource endpoints:

ResourceOperationsDescription
CompanySearch, Get, Create, Update, DeleteFull CRUD. Supports external identifiers, delivery addresses, custom fields, labels
ContactSearch, Get, Create, Update, DeleteFull CRUD. Upsert by email or external ID. Linked to companies
OpportunitySearch, Get, Upsert, Win, LoseUpsert by external ID. Custom fields. Status change operations
ProductSearch, Get, Create, Update, Delete, Batch createFull CRUD. Batch create up to 100 at a time. MPN enrichment via ?enrich=true. Custom fields. Storefront category membership
Product InventoryReplaceReplace entire inventory list for a product
QuoteSearch, Get, Create, Update draft header, Edit draft lines and sections, OrderCreate quotes, update a draft's header, edit lines and sections on a draft, and trigger order flow. No delete via API
Quote TemplateList, Get, Create, UpdateManage quote templates. List returns listed items only; get-by-id still returns an unlisted template. Create defaults listed to true. The same listed rules apply to quote widget templates.
CategoryList, TreeRead-only internal product categories. Unchanged when you use storefront categories
Storefront CategoryList, Tree, Get, Create, Update, Access listsFeature-flagged. Manage the categories customers browse, plus company and classification access
FieldGet values, Upsert valuesManage field dropdown values (opportunity categories, payment terms, etc.)
Pricing BookList, Get, Create, UpdateManage pricing books with product assignments and company links
Discount GroupList, Get, Create, Update, Set companiesManage discount groups with category-level discounts
Sync StateUpdateReport synchronization status for quotes and products
Contract (Beta)Search itemsRead-only access to contract items. Beta β€” may change without notice

Quote search β€” list vs detail

GET /public-api/quote (and the deprecated GET /public-api/quote/approved) returns a slim quote by default: id, title, number, status, dates, contact, company name, opportunity id, attachments, staff link, customer shareLink, and isBasket. The response does not include an items key.

isBasket is always true or false. It is never empty. true means the quote is a storefront order: an open cart or a quote created as a basket. The same field is on the full quote, on a quote you just created, and on quote webhooks.

Filter the list with filters=isBasket:Yes or filters=isBasket:No. true and false mean the same thing. The deprecated approved list accepts the same filter. Yes together with approved status is a storefront order the customer has already placed.

GET /public-api/quote/{id} always returns the full quote, including items[]. Creating a quote (POST) is unchanged.

If an existing integration reads items[] from the list endpoint, switch those reads to GET /public-api/quote/{id}, or contact Salesbuildr to enable line items on quote search for your account.

Reading one quote

items[] is still the flat list of enabled lines, in display order. Bundle headers and optional add-ons that are not selected stay out of that list. Keep reading line prices from items[].

The same response also includes:

FieldMeaning
mutationSeqA counter that increases each time the quote is saved in Salesbuildr. If the quote was saved before this field existed, the value is 0. This is not the version number a customer sees when the quote is sent.
widgetsSections in order. Content sections include the stored content.
linesEvery line on the quote, including lines that items[] hides. Each line has lineType, parentItemId, addonType (for addon lines: required or optional), and selected when the line can be selected.
totals and churnTotalsThe totals already stored on the quote.
linkSigned-in staff quote editor. Opening this URL in a browser asks for a Salesbuildr login.
shareLinkCustomer Share URL (the same link as Share in the quote editor). Treat it as private: it opens the customer view. It is null while the quote is a draft or waiting for internal approval. Storefront baskets use a basket overview URL instead of a ?key= link. Quote webhook payloads use the same two fields.

The API never returns the raw share key as its own field. Use shareLink when you need to send the customer the quote; keep using link for staff.

product.externalIdentifier is unchanged. When your integration key has a product or line identifier, the response can also include that single key under externalIdentifiers. Identifiers that belong to other integrations are not returned.

Quote search does not include widgets, lines, totals, or mutationSeq unless line items are enabled for quote search on your account.

Creating a quote without a template

templateId is optional on POST /public-api/quote and POST /public-api/quote/approved. Leave it out to create the quote from the opportunity and the products[] you send, without copying a Salesbuildr template.

Updating a draft quote's header

PUT /public-api/quote/{id} updates a draft quote. The same body works on PUT /public-api/quote/ext/{externalIdentifier} for a quote that already exists. That route does not create a quote. The external id is the one stored for the integration-key header. If you omit that header, the key is public-api, which does not match an Autotask, Halo, ConnectWise, or Dynamics id.

Send operationId in the body and an Idempotency-Key header. Include at least one field you want to change. A body that only has operationId is rejected and does not change the quote. Leave a field out to keep its current value. Send null to clear an optional field. title cannot be null or empty.

You can set the title, notes, payment term, contract start, contract duration, discount, shipping, and delivery address. Duration units are months and years. A percentage discount amount is a fraction from 0 to 1 (0.1 is 10%). A fixed discount amount uses the same currency units as line prices.

The quote must still be a draft. A sent, approved, declined, or deleted quote is rejected.

Optional expectedMutationSeq must match the mutationSeq from GET /public-api/quote/{id}. If someone else saved the quote first, the call is rejected and nothing is written. Send the same Idempotency-Key and the same body to retry a call that already succeeded. A different body with that key is rejected.

The response is the full quote, plus the operationId you sent. Get quote, quote search, and webhooks do not include operationId.

Editing lines and sections on a draft quote

POST /public-api/quote/{id}/structure changes lines, sections, and their order on a draft in one call. The same body works on POST /public-api/quote/ext/{externalIdentifier}/structure for a quote that already exists. That route does not create a quote. The external id is the one stored for the integration-key header, the same way as a header update.

Send operationId in the body and an Idempotency-Key header. The call must change at least one line, section, order, or delete. A body that only names a section and changes nothing is rejected and does not save the quote.

Name each line or section with exactly one of these:

FieldUse it when
idYou already have the Salesbuildr id
extIdYou have the external id for your integration-key
clientReferenceThis call creates the line or section. You choose the token. resolvedReferences in the response maps it to the saved id

You can add, update, delete, reorder, and move lines and sections, including bundles, add-ons, and the distributor on a line.

HTML can be set only on an HTML content section, and only when the API key's user can manage quotes, or for a service account, when it has the Quote editor preset or sales documents write access. Salesbuildr cleans that HTML before saving it. A section title is stored as you typed it unless the title itself contains HTML. One section's HTML cannot be longer than 100,000 characters. HTML content on the quote cannot add up to more than 500,000 characters.

The quote must still be a draft. This call cannot send, approve, or retract a quote.

expectedMutationSeq and Idempotency-Key work the same way as on a header update. The response is the full quote, plus the operationId you sent and resolvedReferences.

Changing one line on a draft quote

Use these when you only need to add, update, or delete a single line. Reordering lines, moving a line between sections, and editing a section still use the structure call above. There is no external-id variant of these three calls.

CallWhat it does
POST /public-api/quote/{id}/linesAdds one product. Send exactly one of productId or productExtId. Optional: quantity (positive integer, defaults to 1), patch (line field overrides), parentItemId with addonType (adds as a child of an existing line). The line goes into the section for the product's category, or its parent category when the quote setting to use the root category as heading is on. To put it in a specific section, add it with POST /public-api/quote/{id}/structure under that section.
PUT /public-api/quote/{id}/lines/{itemId}Updates that line. itemId is the line id from the quote. Send at least one field to change, such as quantity (positive integer).
DELETE /public-api/quote/{id}/lines/{itemId}Deletes that line.

Send operationId in the body and an Idempotency-Key header, the same way as a structure call. The response is the full quote, plus operationId and resolvedReferences.

An added product is placed in the section for its category. A bundle child or add-on is updated or deleted with its own itemId. When both top-level quantity and patch.quantity are sent on an update, the top-level value is used.

Adding an add-on to an existing line

To add a product as a child of an existing line, include parentItemId (the id of the parent line) and addonType (required or optional). The parent must already exist on the quote. The new line appears under the parent in lines[] with lineType: addon.

{  "operationId": "add-addon-1",  "productId": "addon-product-id",  "parentItemId": "existing-line-id",  "addonType": "optional"}

Quote create β€” per-line pricing

When creating a quote (POST /public-api/quote or POST /public-api/quote/approved), each entry in products[] accepts id, quantity, and an optional price object to override catalog sellable fields for that line:

FieldDescription
originalPriceUnit sell price before line-level discount
costUnit cost
priceEffective unit sell price
markupMarkup as a decimal fraction (e.g. 0.25 = 25%)
termBilling term β€” must match a quote line-item dropdown value. Services cannot use one-time; bundle and labor lines cannot set term. Halo-expanded terms (e.g. 6-month) require Halo PSA on the tenant.

Omitted fields fall back to the product's catalog values. Unknown keys inside price are rejected.

Example request body:

{  "opportunityId": "abc123",  "title": "Integration quote",  "products": [    {      "id": "product-id",      "quantity": 2,      "price": {        "originalPrice": 150,        "cost": 60,        "price": 120,        "markup": 1,        "term": "month"      }    }  ]}

Quote line item pricing (response)

Each object in items[] on a quote response includes:

FieldDescription
priceEffective unit sell price after line-level discount
originalPriceUnit sell price before line-level discount (added in v220)
discountDecimal fraction derived from originalPrice and price (e.g. 0.1 = 10%)

Use originalPrice directly when syncing to external systems. Do not back-calculate it from price and discount β€” that can introduce rounding errors in tools that store only two decimal places.

Storefront categories

Use /public-api/storefront-category to manage the categories customers browse on the storefront. This is separate from /public-api/category, which still returns internal product categories only.

Features required. Both Storefront and storefront categories must be enabled for your account. The routes stay listed in Swagger when they are off; calls return 403 until both features are on.

There is no delete. Hide a category by setting listed to false. A top-level category that already exists as a reference can still be updated, including listed: false. You cannot move a reference category to the top level, and you cannot change a container into a reference while products are still assigned to it. Changes show immediately in Products β†’ Categories and on the storefront. See Categories for the matching admin screen.

OperationRouteNotes
TreeGET /public-api/storefront-category/treeIncludes listed, companyWhitelist, and companyClassificationWhitelist on each node. An open category returns null for those lists, not a missing field
ListGET /public-api/storefront-categoryFlat list of the same records
GetGET /public-api/storefront-category/{id}One category. Missing or deleted ids return 404
CreatePOST /public-api/storefront-categorySame validation as the admin screen. Roots are containers. Child categories send kind (container or reference)
UpdatePUT /public-api/storefront-category/{id}Sending companyWhitelist or companyClassificationWhitelist replaces that entire list
Get by your idGET /public-api/storefront-category/ext/{externalIdentifier}Looks up the category by the id you stored for the current integration-key
Upsert by your idPUT /public-api/storefront-category/ext/{externalIdentifier}Creates (201, name required) or updates (200) so onboarding scripts can rerun without duplicates
Add or remove a companyPOST / DELETE /public-api/storefront-category/{id}/companies/{companyId}Changes one company without replacing the rest of the list. Removing the last company opens the category to every customer. Unknown company ids are rejected
Add or remove a classificationPOST / DELETE /public-api/storefront-category/{id}/classifications/{classificationId}Same incremental pattern for company classifications. Removing the last classification opens the category to every customer. Unknown classification ids are rejected

The response includes externalIdentifier for your current integration key. It does not include the full identifier map.

Access lists:

  • Omit the list to keep the access list already stored.
  • Send null to open the category to every customer.
  • Send [] on create or update to hide the category from every customer.
  • Removing the last company or classification through the add/remove routes opens the category (null). It does not hide it.
  • Discover company ids with GET /public-api/company. Classification ids are not yet on the public company payload.

Product storefront membership

Product responses include storefrontCategoryIds. You can replace the full list on create or update, or add and remove ids without replacing the rest:

OperationRoute
ReplacePUT /public-api/product/{id} or PUT /public-api/product/ext/{externalIdentifier} with storefrontCategoryIds
AssignPOST /public-api/product/{id}/storefront-categories/assign (also …/ext/{externalIdentifier}/storefront-categories/assign)
UnassignPOST /public-api/product/{id}/storefront-categories/unassign (also the ext/ variant)

Assign and unassign send { "storefrontCategoryIds": ["…"] }. Only non-root container storefront categories can be assigned. These writes also require Storefront and storefront categories. Leave storefrontCategoryIds out of a product update to keep the current list. Send [] to clear it. null is rejected.

External identifiers

Most resources support operations by external identifier β€” a reference you provide to link Salesbuildr records to your external system. Use GET/PUT/DELETE /public-api/{resource}/ext/{externalIdentifier} to work with records by their external ID.

Search endpoints support:

  • from and size for pagination
  • query for text search
  • Resource-specific filters
  • Sort field and direction

Rate limits and fair use

Rate limits

Each tenant is limited to 500 API requests per 10-minute rolling window. This limit applies to Public API calls only β€” internal application requests and built-in PSA integrations do not count.

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating when requests can resume.

The sync state endpoint is exempt from rate limiting.

Rate limit response headers

Every API response includes headers showing your current rate limit status:

HeaderDescriptionExample
X-RateLimit-LimitMaximum number of requests allowed in the current window500
X-RateLimit-RemainingNumber of requests remaining before the limit is reached487
X-RateLimit-ResetUnix timestamp (seconds) when the current window resets1709301600
Retry-AfterSeconds to wait before retrying (only present on 429 responses)120

Handling rate limits

Follow these best practices to stay within rate limits and build a resilient integration:

  • Use webhooks instead of polling. Subscribe to events (e.g., quote.ordered, company.updated) rather than repeatedly calling search endpoints to detect changes.
  • Implement exponential backoff. When you receive a 429 response, wait for the number of seconds specified in the Retry-After header, then retry. If the retry also fails, double the wait time before each subsequent attempt.
  • Batch where possible. Use batch endpoints (e.g., POST /public-api/product/batch for up to 100 products at a time) instead of creating resources one by one.
  • Cache responses. Store data locally and refresh only when needed β€” avoid fetching the same resource repeatedly within a short window.
  • Monitor your usage. Check X-RateLimit-Remaining in response headers to proactively slow down before hitting the limit.

Fair use policy

The API is provided as part of your Salesbuildr subscription for normal integration usage. By using the API, you agree to the following terms:

Permitted uses:

  • Synchronizing data between Salesbuildr and your business systems (CRM, PSA, ERP)
  • Automating quote creation, product management, or order processing
  • Building custom dashboards or reporting tools
  • Triggering workflows based on webhook events

Prohibited uses:

  • High-volume bulk requests designed to overload the platform
  • Continuous polling for changes (use webhooks instead)
  • Scraping, data harvesting, or competitive analysis
  • Reselling or redistributing API access to third parties
  • Circumventing rate limits through multiple API keys or IP rotation
  • Any activity that degrades platform performance for other customers

Hosted platform obligations: Salesbuildr is a shared multi-tenant platform. API usage that impacts other customers' experience β€” even if unintentional β€” may be throttled or restricted without notice.

Consequences of violation: Salesbuildr reserves the right to restrict API access, suspend accounts, or apply additional usage charges for policy violations. Persistent or intentional abuse may result in account termination.

Policy updates: This policy may be updated at any time. Continued use of the API after changes constitutes acceptance.

For questions about API usage or to request higher rate limits, contact support@salesbuildr.com.

Webhooks

Webhooks notify your external systems in real time when events occur in Salesbuildr. Instead of polling the API for changes, you register endpoint URLs and Salesbuildr pushes event data to them automatically.

Note: Webhooks must be enabled for your account. Navigate to Settings > Integrations > Webhooks to manage your endpoints.

Available events

Salesbuildr supports 16 webhook event types across 6 entities:

EntityEventsDescription
Companycompany.created, company.updatedFires when a company is created or any field is updated
Contactcontact.created, contact.updatedFires when a contact is created or updated
Opportunityopportunity.created, opportunity.updated, opportunity.status_changedIncludes status transitions (open, won, lost)
Productproduct.created, product.updatedFires on product creation or changes to pricing, specs, etc.
Quotequote.created, quote.updated, quote.ordered, quote.deletedCovers the full quote lifecycle
Orderorder.created, order.updated, order.completedTracks procurement orders through completion

Creating a webhook endpoint

  1. Navigate to Settings > Integrations > Webhooks
  2. Click Add Webhook
  3. Configure the endpoint settings:
SettingDescription
NameA label to identify this endpoint (e.g., "CRM Sync", "Order Fulfillment")
URLThe HTTPS URL that receives webhook deliveries
Custom headersOptional key-value pairs sent with every delivery β€” use for authentication tokens or routing
Subscribed eventsSelect which events trigger deliveries to this endpoint
ActiveToggle to enable or disable without deleting the configuration
TimeoutHow long Salesbuildr waits for a response (default: 30 seconds)
Retry attemptsNumber of retries on failure (default: 3, maximum: 10)
  1. Click Save

You can create multiple endpoints, each subscribing to different events. For example, one endpoint for CRM updates and another for order notifications.

Payload structure

Each delivery sends an HTTP POST with a JSON body:

{  "event": "company.created",  "eventId": "unique-event-id",  "timestamp": "2026-02-20T10:30:00.000Z",  "data": { ... }}
  • event β€” The event type that triggered the delivery
  • eventId β€” A unique identifier for this specific delivery
  • timestamp β€” ISO 8601 timestamp of when the event occurred
  • data β€” The full entity object, using the same structure as the Public API response for that resource

For example, a company.created event delivers the same company object you'd get from GET /public-api/company/:id.

Delivery and retries

  • Deliveries are processed asynchronously via a background job queue
  • A delivery is considered successful when your endpoint returns any HTTP 2xx status
  • Failed deliveries (non-2xx response or timeout) are retried with a 2-second delay between attempts
  • Delivery history is visible per endpoint in the admin UI, showing timestamp, event type, HTTP status, and success/failure

Testing webhooks

Click the Send Test button on any configured endpoint to deliver a test event. This verifies:

  • Your URL is reachable from Salesbuildr
  • Authentication headers are accepted
  • Your endpoint returns a 2xx response

The test delivery uses a sample payload with realistic data so you can verify your integration's parsing logic.

Common patterns

CRM synchronization

Subscribe to company.created, company.updated, contact.created, and contact.updated to keep an external CRM in sync with Salesbuildr customer data.

Order fulfillment

Subscribe to quote.ordered and order.created to trigger fulfillment workflows when a quote is converted to an order.

Reporting and analytics

Subscribe to opportunity.status_changed and quote.created to feed sales metrics into a BI tool or dashboard.

Troubleshooting

  • Deliveries not arriving β€” Verify the endpoint is Active, the URL is reachable from the internet, and you're subscribed to the correct events
  • Authentication failures β€” Check that custom headers match what your endpoint expects
  • Timeouts β€” Ensure your endpoint responds within the configured timeout; process webhook data asynchronously if your handler is slow
  • Duplicate deliveries β€” Use the eventId field to deduplicate; retries may re-deliver the same event

See also