Overview

Vendr API Documentation

Introduction

Vendr’s APIs enable you to power software pricing experiences within your applications including websites and AI agents.

Catalog API - The foundation of multi-dimensional price profiles is a structured product catalog derived from thousands of unstructured quotes. The catalog API vends these neatly structured catalog attributes. Use this API to help users understand the breadth of a seller’s products, including add-ons they won’t find anywhere else.

Scope API - Use this API to share the user’s purchase requirement with Vendr. Whether it’s buying 10 licenses of PagerDuty’s Enterprise Tier with 200,000 AIOps events and Live Call Routing, or just uploading a quote document, the Scope API makes it easy to communicate detailed purchasing needs in text or file format.

Pricing API - The Pricing API delivers the power of Vendr’s Pricing AI. By submitting a registered scope ID, you’ll receive actionable pricing insights-including fair price predictions and negotiation guidance-tailored to the user’s requirements.

Webhooks API - The webhooks API helps to create and manage webhook to listen to the status of Vendr’s data processing events.

Access

Access Key

Please email us at [email protected] to get your API key.

Header Fields

All Vendr APIs have a required header field for your API Key. In addition, there are 4 optional header fields. We use these optional fields to identify the end user of Vendr’s pricing insights on your application. Based on your partnership terms, your Vendr contact will inform you if are required to pass one or more of these fields when calling these APIs.

Rate Limits and Quotas

All API keys are subjected to a rate limit of 250 requests per minute and a quota of 150k requests per day.

Catalog API

Vendr’s catalog is structured as a hierarchy - company > product families > products. Each of these entities has various attributes. The catalog API gives you details of these entities and their attributes. You can use this API to:

  1. Create and maintain a mapping of Vendr’s catalog to your catalog. For example, a product name and ID vended by the API helps you to map it to your desired webpage for that product.
  2. Get seller company and product level metadata. For example, product name, description, median price, the company it belongs to, dimensions that impact the price of a product.

Catalog API has 7 endpoints:

Get a Company

Use this endpoint to get details about a company. The endpoint takes in a single company ID and gives you all the details about the company available in Vendr’s catalog including the name, ID and description of the products offered by that company.

Get a Product Family

A product family is a group of products. For example, Zoominfo offers the Chat Product Family which contains Advanced, Custom and Professional+ products. The endpoint takes in a single company ID and gives you all the details about the product family including the products that are part of the product family as well as a range of minimum to maximum default prices for products in that family. When you want to power product specific pages, use this endpoint instead of Get a Company endpoint. For example, if you have a webpage for Zoominfo Chat product, use this endpoint to get the products under that family i.e. Advanced, Custom and Professional+ and then use the Get a Product endpoint to get details about the specific products.

Get a Product

Use this endpoint to get details about a product. The endpoint takes in a single product ID and gives you all the details about the company available in Vendr’s catalog including product name, description and details of dimensions that impact prices for this product. You would typically use the dimension data this API vends to show the end user pricing dimensions, along with the options, that they could select to request a customized price estimate.

List Categories

All companies are assigned categories and sub-categories in the Vendr catalog which you can use to list a group of companies together using this endpoint. See categories and sub-categories on Vendr website here. For example, Collaboration and Communication is a category with Appointment Scheduling as one of its sub-category. This sub-category contains companies like Calendly.

List Companies

This endpoint gives you a paginated list of companies in the Vendr catalog. The endpoint response includes company id, name, domain, description (100 character limit), icon, category ID and a flag to show whether the company is part of the Vendr Verified program or not. You can add multiple filters to you query as mentioned in the Query Parameters section.

List Product Families

This endpoint gives you a paginated list of product families for a company. The endpoint takes in a single company ID and lists all the details of all the product families offered by the company including some details of the products within the product family and the default price range for the product family.

List Products

Use this endpoint to get the details of all the products for a company, including product dimensions. The endpoint takes in a single company ID and gives you a paginated list of all products offered by the company. list of the details about the company available in Vendr’s catalog including the name, ID and description of the products offered by that company.

Important Notes

Understanding product properties:

  • Included Features

    The Included features object contains a list of features and their description that are available with the product generally at no additional cost. You can share the list of these features with software buyers at any point in their price estimate journey - as part of the product features list, as part of the list of deliverables included in a price estimate or as a Q&A about included features on the product’s listing page.

  • Pricing Dimensions

    The pricing dimensions object contains the details of all the possible dimension related questions you could ask the end user to help them get a custom price estimate. Sometimes, there are pricing dimensions for which we don’t know the full price impact yet. With the priceImpactKnown flag, you can ensure that you do not ask users questions about such dimensions, as there response to that question does not impact the price estimate.

    The dimension Id, name, description and unit name help you frame the question to the user e.g. for Slack Enterprise “How many seats (unit name) do you want?” or “Would you like to include Slack AI (name)? Slack AI enhances workspaces with AI-powered conversation summaries and answers, available as a premium add-on. (description)”

    The following quantity properties help you define the responses to those questions.

    1. min/max Quantity - Min/Max quantity represents the constraints you need to set to ensure that the end user can provide only certain values of these dimensions. The lowest possible value of min quantity is 0 i.e. dimension values are always 0 or a positive number. There are multiple use cases for this.

      1. A dimension with min quantity 0 and max quantity 1 is one that is either included or not. Since this requires a binary response from the user, you can either show the 2 options - 0 or 1 to select or frame it as a Yes/No question. For example, you can have 2 responses to the question ““Would you like to include Slack AI (name)? Slack AI enhances workspaces with AI-powered conversation summaries and answers, available as a premium add-on. (description)” - Yes (1) or No (0).
      2. A dimension with min quantity 1 and max quantity 1 means that the dimension is mandatorily included. Therefore, the user has no choice to exclude it from the estimate. Therefore, we recommend to not ask the user about this dimension, though you option of showing this to the user without the option for them to change the min/max quantities.
      3. A dimension with any other min and max quantities represents constraints specified by the seller in quantity selection e.g. up to 10 million (max quantity) API calls offered as part of a product. In such case, you can use the min/max values to ensure that the user is presented with these constraints when providing these dimensions values. For example, the user should not be able to enter or select max quantity more than 10 million.
      4. A dimension with null max quantity represents the absence of any man quantity constraints i.e. the user can enter or select any maximum value.

    2. stepSize - For cases with max quantity >1 or null, sellers can specify the incremental values that a dimension can take. For example, number of API calls can be dimension with min/max values of 1 million and 10 million, along with stepSize of 100,000. This ensures that the user can’t enter any other numbers between 1 and 10 million.

    3. allowedQuantities - For cases with max quantity >1, sellers specify the incremental values that a dimension can take but they are not linear stepSize increments. For example, For example, number of API calls can be dimension with min/max values of 1 million and 10 million, along with allowedQuantities of 1 million, 2 million, 5 million and 10 million. This ensures that you can just present the allowedQuantities for the user to select for a particular dimension.

    4. Default Quantity - You can use this dimension property to show default values to users, which they can then edit as per their needs.

    Here is the list of recommended user experiences you can create based on min/max quantity, stepSize and allowedQuantities combinations.

    minQuantitymaxQuantitystepSizeallowedQuantitiesRecommended User Experience
    01N/AN/AQuestion with Yes/No radio buttons in response options.
    11N/AN/ANo question for the user
    ≥0>1510, 30, 45, 80, 135 etc.Question with a dropdown or quantity slider in response, that lets users select numeric values with min and max as specified. Allow selection of specific values only if stepSize or allowedQuantities is provided. If not provided, allow selection of consecutive whole numbers.
    ≥0null500N/AQuestion with a whole number input box in response, in which users can type in their numeric response. If stepSize is provided, add guidance description such as “Enter values in multiples of 500.”

Scope API

A scope, identified by a Scope ID, is a set of dimensions that defines the criteria based on which the pricing API comes up with a price estimate. A scope can include multiple products across multiple companies. Scope API has 3 endpoints:

Create a Scope

Use this endpoint to register the scope with us when the end user shares the scope on your application. For example, after seeing the product details powered by Vendr catalog on your application, an end user can specify that they need 100 licenses of a product along with an add-on such as support. In the API call, you can optionally also specify desired start/end date, term length, price and discount the end user has already received for this product. These additional fields are generally available when the end user already has a quote for their needs and is looking to verify the price they have received. When you register a scope, you receive a scope ID in return. You can use this scope ID to get pricing insights from the pricing API.

If you want to edit a scope you previously registered, add the previousScopeID to your API call. We will store both scopes and maintain the association between them.

Create a Scope via Document

When the end user already has a quote for their needs and is looking to verify the price they have received, they can simply upload the pricing part of the quote as well in one of the following file formats - pdf, doc, docx, xls, xlsx, csv, png, jpg and jpeg. Use this endpoint to create a scope using a document. Our services extract the scope from the submitted document automatically. Similar to create a scope, when you register a scope, you receive a scope ID in return. You can use this scope ID to get pricing insights from the pricing API. Please note that there is a time lag in scope ID generation when using this endpoint. Please create a webhook to get a notification when the scope ID is ready (see Webhook API section for details).

Get a Scope

Call this endpoint with a scope ID to retrieve the details of a previously created scope including when it was created, how it was created (manual or with a document) and the other scope IDs it is associated with (previous and next scope IDs).

Pricing API

Call this API with a scope ID to get a price estimate. You can show this estimate to the user as is or compare it with the quote that they have received. The API has 2 endpoints - the basic endpoint enables you to create a price range experience for users while the advanced endpoint enables you to create additional experiences such as dimension details.

Basic Price Estimate

Call this endpoint with a scope ID to get a price estimate for the scope. The price estimate generated by Vendr’s Pricing AI is a price distribution and the API response contains the 25 percentile, 50 percentile and 75 percentile values of that distribution. Use these values to show the fair price range (25-75 percentile) for their scope along with a median price.

Advanced Price Estimate

Call this endpoint with a scope ID to get a more detailed price estimate for the scope. The API response contains:

  1. Overall Price Estimate: The 10-90 percentile values of the overall price estimate distribution in increments of 5 (i.e. 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85 and 90 percentile values).
  2. Product Level Estimate: If you share a multi-product scope, this would give you granular product level insights i.e. the 10-90 percentile values of the product level estimate distribution in increments of 5. Please be aware that in case of a multi-product scope, the product level estimate is likely to be different that the individual price estimate for that product. This is because combining products during a purchase can impact the overall price.

Please note that the API response is a point-in-time price estimate. The estimate could be different at different points in time as Vendr’s AI is continuously learning from new data points.

Webhooks API

The purpose of webhooks is to notify your application when a specific event occurs in Vendr’s services. By listening to these events, you can trigger automated actions. You can use webhooks especially for Vendr’s data processing events in which the API response is not real-time. For example, when you use the Create a Scope via Document endpoint to create a scope by submitting a document, there is a time lag in scope ID generation. You can setup a webhook to get a notification when the scope is ready.

Webhook API has 5 endpoints:

  • Create a Webhook
  • Get Webhook Event
  • List Webhook
  • List Webhook Events
  • Delete Webhook

Headers

All delivered webhook events include the following headers:

HeaderValues
Acceptapplication/json, text/plain, */*
Accept-Encodinggzip, compress, deflate, br
Content-Typeapplication/json
Idempotency-Key--
X-Vendr-Webhook-Signature--

Body

The event payload matches the shape of the data.body property from the GET webhook event endpoint

For example, a successful scope.extracted event will have the following shape:

{
  "eventType": "scope.extracted",
  "data": {
    "scopeId": "a4e66d9f-0622-4cc9-bdfe-0f69847a9c34",
    "status": "completed"
  }
}
json

Verification

Each delivered webhook event includes an x-vendr-webhook-signature header you can use to verify that the request originated from official Vendr servers and was not tampered with

This signature is computed as an HMAC SHA-256 hash and base64 encoded, using the raw binary content of the request body and your auto-generated webhook secret

To verify the integrity of your webhook events, compute a hash of the request body in this same manner, and exert a time-safe comparison of the two hashes

Example: TypeScript w/ Express.js

Assuming you have a single-tenant configuration where you need only a single webhook for your platform:

// Returned once from the create webhook endpoint; store securely
const VENDR_WEBHOOK_SECRET = process.env.VENDR_WEBHOOK_SECRET;

const verifyWebhookSignature = ({
  body,
  secret,
  signature: prefixedSignature,
}: {
  body: Buffer;
  secret: string;
  signature: string;
}): boolean => {
  try {
    const hash = crypto
      .createHmac("sha256", secret)
      .update(body)
      .digest("base64");

    const signature = prefixedSignature.replace("sha256=", "");

    const expectedBuffer = Buffer.from(hash, "base64");
    const providedBuffer = Buffer.from(signature, "base64");

    // Ensure buffers have the same length before comparison to prevent `RangeError`
    if (expectedBuffer.length !== providedBuffer.length) {
      return false;
    }

    return crypto.timingSafeEqual(expectedBuffer, providedBuffer);
  } catch (error) {
    console.error("Unhandled error during signature verification", error);
    return false;
  }
};

app.use(
  express.json({
    // Store the rawBody buffer on the request
    verify: (req, res, buffer) => {
      req.buffer = buffer;
    },
  }),
);

app.post("/webhook", async (req, res) => {
  const signature = req.get("x-vendr-webhook-signature");

  if (!signature || !(req.buffer instanceof Buffer) || !VENDR_WEBHOOK_SECRET) {
    console.log("Unable to verify payload signature");
    return res.sendStatus(401);
  }

  if (
    !verifyWebhookSignature({
      body: req.buffer,
      secret: VENDR_WEBHOOK_SECRET,
      signature,
    })
  ) {
    console.log("Signature is invalid");
    return res.sendStatus(401);
  }

  // ... continue with your business logic
});
typescript

Confirmation

Return a 2XX response from your endpoint to confirm that the event was received successfully. Any status code >400 is assumed to be a failure and triggers retry attempts

Add Action Link