Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
description: Using the API for the CRM service, you can integrate your system with CRM from SendPulse and receive detailed information on pipelines, deals, contacts and their attributes and users. You can also create deals and contacts, assign and remove fields, tags, contact details and instant messengers. On the right, there is a button for authorizing requests made on this page. Click “Authorize,” then insert the ID and Secret from your account. To perform a request directly from the page, click the "Try it out" button within each method block. Then fill in input fields if any (for URL parameters, the description is right below the URL request; for body parameters, the description is under the “Scheme” button to the right of the example), and click “Run.” You will find the server response and description of received parameters below.
title: SendPulse CRM Public ECommerce Product API
version: 0.1.0
servers:
- url: https://api.sendpulse.com/crm/v1
security:
- apiKey: []
- oauth2: []
tags:
- name: ECommerce Product
paths:
/products/all:
post:
tags:
- ECommerce Product
summary: Get products by filter
requestBody:
content:
application/json:
schema:
properties:
categoryId:
type: number
description: Category ID to filter products.
dateFrom:
type: string
description: 'Start date for filtering (format: YYYY-MM-DD).'
dateTo:
type: string
description: 'End date for filtering (format: YYYY-MM-DD).'
search:
type: string
description: Text search by product name or code.
balance:
type: object
description: Filter by product stock balance and unit type.
properties:
expression:
type: string
enum:
- '='
- '>='
- <=
description: Comparison operator for balance.
type:
type: number
enum:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
description: Unit type of the product balance.
value:
type: number
description: Stock quantity value to compare.
description:
type: string
description: Description for products
purchases:
type: object
description: Filter by number of purchases.
properties:
expression:
type: string
enum:
- '='
- '>='
- <=
description: Comparison operator for purchases.
value:
type: number
description: Number of purchases to compare.
price:
type: object
description: Filter by product price or old price.
properties:
expression:
type: string
enum:
- '='
- '>='
- <=
description: Comparison operator for price.
currency:
type: string
description: Currency of the price (e.g., USD, EUR).
value:
type: number
description: Current price value.
oldValue:
type: number
description: Previous price value.
visible:
type: number
enum:
- 0
- 1
description: Product visibility status (0 = hidden, 1 = visible).
typeProduct:
type: number
enum:
- 1
- 2
description: Product type (1 = physical, 2 = digital/service).
limit:
type: number
description: Maximum number of results to return.
offset:
type: number
description: Offset for pagination.
orderBy:
type: object
description: Sorting options.
properties:
fieldName:
type: string
enum:
- id
- balance
- price
description: Field to sort by.
direction:
type: string
enum:
- asc
- desc
description: Sorting direction (asc or desc).
sections:
type: array
description: Filter by section-specific key-value attributes.
items:
properties:
key:
type: string
example: new
description: Section attribute key (e.g., color).
value:
type: string
example: york
description: Section attribute value (e.g., red).
categoryIds:
type: array
description: List of category IDs to include in filter.
items:
type: number
responses:
'200':
description: Successful response containing product data.
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: Product data result.
properties:
id:
type: integer
description: Product ID.
name:
type: string
description: Product name.
userId:
type: integer
description: Owner user ID.
images:
type: array
items:
type: string
default:
- url1
- url2
description: List of product image URLs.
vendorCode:
type: string
description: Product vendor or article code.
type:
type: number
description: Product internal type code.
categoryId:
type: number
description: Product category ID.
visible:
type: boolean
description: Visibility flag (true = visible).
balance:
type: object
description: Product stock info.
properties:
type:
type: number
description: Stock unit type (same as input).
value:
type: number
description: Stock quantity.
price:
type: object
description: Product pricing info.
properties:
id:
type: number
description: Price record ID.
currency:
type: string
description: Currency code (e.g., USD).
value:
type: number
description: Current price value.
oldValue:
type: number
description: Previous price value.
countSales:
type: number
description: Total number of product sales.
createdAt:
type: string
description: Product creation datetime.
typeProduct:
type: number
enum:
- 1
- 2
description: Product type (1 = physical, 2 = digital/service).
operationId: getProductsByFilter
x-ai-role: ecommerce_catalog_manager
x-ai-description: Fetches a filtered, paginated list of products from the ECommerce catalog. This is the primary product discovery endpoint — it acts as a flexible query interface supporting multi-dimensional filtering by category, price range, stock balance, visibility, and custom section attributes. Use it to power catalog search, inventory audits, and campaign product selection.
x-ai-reasoning-instructions:
- Determine which filters are actually needed — avoid sending empty filter objects as they may affect query performance.
- If the user wants all products, omit all filter fields and rely only on limit/offset for pagination.
- When filtering by price, always specify currency to ensure correct comparison across multi-currency catalogs.
- For stock balance filtering, clarify the unit type (enum 1–7) with the user if it's not obvious from context.
- Use categoryIds (array) instead of categoryId (single) when the user wants to query multiple categories at once.
- Always include limit and offset for large catalogs to avoid unintended full-dataset responses.
- If the user wants to find new or featured items, use the sections filter with appropriate key-value pairs.
x-ai-responding-instructions:
- Report the number of products returned and indicate if pagination is needed (i.e., if count equals limit).
- 'Highlight key fields in results: product name, vendorCode, price, balance, and visibility status.'
- If results are empty, suggest relaxing filters (e.g., broader date range, removing balance constraints).
- When returning products for campaign use, suggest following up with an endpoint to attach products to a mailing or automation flow.
x-ai-suggestions:
- 'Filter by visible: 1 to fetch only publicly listed products.'
- Use dateFrom/dateTo to find recently added or updated products.
- 'Combine typeProduct: 2 with price filter to audit digital product pricing.'
- 'Use orderBy: { fieldName: ''price'', direction: ''asc'' } to surface cheapest products first.'
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/products/categories/{categoryId}/{productId}:
get:
tags:
- ECommerce Product
summary: Get products by id
parameters:
- name: productId
in: path
required: true
schema:
type: number
- name: categoryId
in: path
required: true
schema:
type: number
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
data:
type: object
properties:
id:
type: integer
name:
type: string
description:
type: string
shortDescription:
type: string
images:
type: array
default:
- url1
- url2
vendorCode:
type: string
categoryId:
type: number
balance:
type: object
properties:
type:
type: number
value:
type: number
availability:
type: number
visible:
type: number
userId:
type: number
seo:
type: object
properties:
name:
type: string
description:
type: string
keys:
type: string
prices:
type: array
items:
properties:
id:
type: number
currency:
type: string
value:
type: number
oldValue:
type: number
isDefault:
type: boolean
productId:
type: number
sections:
type: array
items:
properties:
id:
type: number
name:
type: string
productId:
type: number
values:
type: array
items:
properties:
id:
type: number
sectionId:
type: number
key:
type: string
value:
type: string
categorySections:
type: array
items:
properties:
id:
type: number
name:
type: string
categoryId:
type: number
values:
type: array
items:
properties:
id:
type: number
sectionId:
type: number
key:
type: string
value:
type: string
operationId: getCategoryProduct
x-ai-role: ecommerce_catalog_manager
x-ai-description: Retrieves full product details within a specific category context, including pricing tiers, inventory balance, SEO metadata, and custom sections. This endpoint is the authoritative source for rendering a product page — it returns not just core product data but also category-scoped attribute sections (categorySections) alongside product-specific sections, enabling dynamic storefront rendering without additional calls.
x-ai-reasoning-instructions:
- Both categoryId and productId are required — verify both are available before calling; a mismatch (product not belonging to the category) may return empty or 404.
- Check the `availability` field (0 = unavailable, 1 = available) to determine whether to surface add-to-cart actions.
- Check the `visible` field before displaying the product — hidden products should not be rendered in public storefronts.
- 'When multiple prices are returned, use the one with `isDefault: true` as the primary display price; others may represent currency variants or tiered pricing.'
- The `balance` object contains inventory state — use `type` to interpret the balance model (e.g., numeric stock vs. unlimited).
- Use `sections` for product-specific attributes and `categorySections` for category-level attributes — both may need to be merged for complete spec display.
x-ai-responding-instructions:
- Present the product name, short description, and default price as the primary summary.
- If the product is not visible or not available, proactively flag this to the user rather than silently returning raw data.
- When showing prices, highlight the default currency/price and mention if multi-currency options exist.
- List sections and categorySections as structured attributes (key-value pairs) for clarity.
- If images are present, list URLs to assist with rendering or downloading assets.
- Mention the vendorCode if present — it's useful for inventory reconciliation or external system lookups.
x-ai-suggestions:
- Use this endpoint to populate a product detail page before rendering.
- Combine with category listing endpoints to build breadcrumb navigation using the returned categoryId.
- Cross-reference `vendorCode` with external ERP or warehouse systems for stock sync.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/products/deals:
post:
tags:
- ECommerce Product
summary: Add product to deal
requestBody:
content:
application/json:
schema:
properties:
productId:
type: number
dealId:
type: number
productPriceISO:
type: string
default: UAH
productPriceValue:
type: number
quantity:
type: number
allow_out_of_stock:
type: boolean
description: When true the product is attached even if stock is zero and inventory is not decremented
responses:
'200':
description: OK
operationId: addProductToDeal
x-ai-role: ecommerce_sales_manager
x-ai-description: Links a product to a CRM deal, capturing the exact commercial terms (price, currency, quantity) at the time of attachment. This is the core mechanism for building deal line-items — each attachment represents a unit of revenue within the deal pipeline and directly affects deal value calculations.
x-ai-reasoning-instructions:
- Verify that both productId and dealId exist before attempting to link them.
- Confirm the currency ISO code is valid (e.g., UAH, USD, EUR) before submission.
- If productPriceValue is not provided, check whether the product has a default price to suggest.
- If stock availability is uncertain, ask the user whether to set allow_out_of_stock=true rather than defaulting silently.
- Consider whether the same product is already attached to the deal to avoid duplicate line-items.
x-ai-responding-instructions:
- Confirm the product was successfully linked and mention both the product and deal IDs.
- If allow_out_of_stock was set to true, note that inventory was not decremented.
- Suggest reviewing total deal value after adding line-items.
- On failure, clarify whether the issue is with the product, the deal, or the stock constraint.
x-ai-suggestions:
- After attaching all products, retrieve the deal summary to verify total value.
- Use the deal update endpoint to adjust status if all required products are now linked.
x-ai-capabilities:
confirmation:
type: Recommended
message: Confirm attaching product {productId} to deal {dealId} at {productPriceValue} {productPriceISO} × {quantity}?
security_info:
data_handling:
- ResourceStateUpdate
- InventoryModification
/products/deals/{dealId}:
get:
tags:
- ECommerce Product
summary: Get products by deal id
parameters:
- name: dealId
in: path
required: true
schema:
type: number
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
data:
type: object
properties:
totalAmount:
type: integer
currency:
type: string
items:
type: array
items:
properties:
id:
type: integer
name:
type: string
description:
type: string
images:
type: array
default:
- url1
- url2
vendorCode:
type: string
extra:
type: object
properties:
quantity:
type: number
amount:
type: number
currency:
type: string
totalAmount:
type: number
outOfStock:
type: boolean
operationId: getProductsByDealId
x-ai-role: ecommerce_sales_analyst
x-ai-description: Retrieves the full product lineup attached to a specific CRM deal, including pricing summary and per-item detail. This endpoint is the primary way to inspect what a deal is worth and what SKUs it contains — critical for order confirmation, invoice generation, and upsell analysis.
x-ai-reasoning-instructions:
- Verify the dealId exists before interpreting an empty response as 'no products' — the deal itself may not exist.
- Check `totalAmount` against the sum of `extra.totalAmount` across items to detect data inconsistencies.
- If `extra.outOfStock` is true for any item, flag it to the user before proceeding with order or quote workflows.
- Note that `currency` at the top level may differ from `extra.currency` per item — surface any mismatch.
x-ai-responding-instructions:
- 'Present a concise summary: total amount, currency, and item count before listing individual products.'
- Highlight any out-of-stock items prominently.
- If the items array is empty, suggest verifying the dealId or checking whether products have been added to the deal.
- When relevant, suggest following up with a deal-update endpoint to add or modify products.
x-ai-suggestions:
- Use this endpoint to build a pre-invoice product summary for a deal.
- Combine with deal metadata endpoints to produce a full sales order view.
- Cross-reference `vendorCode` with your inventory system to verify stock levels.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/products/deals/{headId}:
put:
tags:
- ECommerce Product
summary: Update quantity or amount products in deal
parameters:
- name: headId
in: path
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
properties:
quantity:
type: integer
description: Product quantity in the deal
amount:
type: integer
description: Product amount in the deal
responses:
'200':
description: OK
operationId: updateProductsInDeal
x-ai-role: ecommerce_sales_manager
x-ai-description: Updates the quantity or monetary amount of products attached to a specific deal head. This is a core operation for maintaining accurate deal valuations in CRM pipelines — incorrect product quantities directly affect deal totals, forecasts, and revenue reporting.
x-ai-reasoning-instructions:
- Verify that the deal with the given headId exists before attempting an update.
- At least one of `quantity` or `amount` must be provided — warn the user if both are omitted.
- Clarify with the user whether `amount` represents unit price or total line value, as this affects downstream deal totals.
- If updating quantity, consider whether the amount should be recalculated proportionally.
x-ai-responding-instructions:
- Confirm which fields were updated (quantity, amount, or both).
- Suggest verifying the updated deal total using a deal retrieval endpoint.
- If the deal is in a closed/won stage, warn that modifying product values may affect historical reporting.
x-ai-suggestions:
- Fetch the current deal state before updating to avoid overwriting stale data.
- Use `getDealProducts` after updating to confirm the new values are reflected correctly.
x-ai-capabilities:
confirmation:
type: Recommended
message: Updating product values in a deal affects deal totals and may impact revenue forecasts.
security_info:
data_handling:
- ResourceStateUpdate
/products/contacts/{contactId}/deals:
get:
tags:
- ECommerce Product
summary: Get products by contact id
parameters:
- name: contactId
in: path
required: true
schema:
type: number
responses:
'200':
description: ''
content:
application/json:
schema:
properties:
data:
type: object
properties:
id:
type: integer
name:
type: string
totalAmount:
type: integer
currency:
type: string
items:
type: array
items:
properties:
id:
type: integer
name:
type: string
description:
type: string
images:
type: array
default:
- url1
- url2
vendorCode:
type: string
extra:
type: object
properties:
quantity:
type: number
amount:
type: number
currency:
type: string
totalAmount:
type: number
outOfStock:
type: boolean
operationId: getProductsByContactDeals
x-ai-role: ecommerce_crm_analyst
x-ai-description: Retrieves the list of products associated with deals linked to a specific CRM contact. This endpoint bridges CRM and eCommerce data — it allows agents to understand what products a contact has purchased or is interested in based on their deal history, enabling personalized follow-ups, upsell recommendations, and revenue attribution per contact.
x-ai-reasoning-instructions:
- Verify that the contactId corresponds to an existing CRM contact before calling this endpoint.
- Treat the response as deal-scoped product data — the same product may appear across multiple deals; aggregate carefully if computing totals.
- Check the `outOfStock` flag on individual items before recommending re-purchase or upsell actions.
- Use `currency` fields at both the deal and item level — they may differ if the account supports multi-currency.
x-ai-responding-instructions:
- Summarize the deal's total amount and currency alongside the product list for immediate business context.
- Highlight any items where `outOfStock` is true and suggest alternatives or follow-up actions.
- If multiple products are returned, group them logically (e.g., by category or vendor code) to aid readability.
- If the response is empty, clarify that this contact has no deals with associated products yet.
x-ai-suggestions:
- Use this endpoint before launching a re-engagement campaign to personalize product recommendations.
- Combine with contact profile data to build a complete purchase history view.
- Cross-reference `vendorCode` with your product catalog to enrich the response with additional metadata.
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- ReadOnly
/products/categories/{categoryId}/{productId}/deals/{headId}:
delete:
tags:
- ECommerce Product
summary: Detach products from deal
parameters:
- name: categoryId
in: path
required: true
schema:
type: number
- name: productId
in: path
required: true
schema:
type: number
- name: headId
in: path
required: true
schema:
type: number
responses:
'200':
description: OK
operationId: detachProductFromDeal
x-ai-role: ecommerce_catalog_manager
x-ai-description: Removes a product from a specific deal within a category, breaking the association between the product and the deal head. Use this when a product should no longer participate in a promotional deal or bundle without deleting the product or deal itself.
x-ai-reasoning-instructions:
- Confirm that the deal (headId) currently includes the specified product before attempting detachment to avoid misleading 404 errors.
- Verify that detaching this product will not violate any deal minimum-product requirements (e.g., a deal requiring at least one product).
- If bulk detachment is needed, check whether the API supports batch operations before calling this endpoint repeatedly.
x-ai-responding-instructions:
- Confirm that the product has been successfully detached from the deal.
- Clarify that neither the product nor the deal was deleted — only their association was removed.
- Suggest reviewing remaining deal products via the appropriate GET endpoint to verify deal integrity after detachment.
x-ai-suggestions:
- After detachment, use the deal GET endpoint to confirm remaining associated products.
- If you need to remo
# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendpulse/refs/heads/main/openapi/sendpulse-ecommerce-product-api-openapi.yml