Skip to main content

Custom APIs

A Custom API is a single endpoint the AI can call to fetch data or perform an action — "get order status," "create a Freshdesk ticket," "check pincode serviceability." Custom APIs are what let flows answer with real, account-specific information beyond standard ecommerce data, and they're the layer that data points and execute actions are built on.

Custom APIs live in the API Library, on top of integrations (the reusable connection to a provider — base URL, authentication, credentials). One integration is defined once and reused by every endpoint built on it. See Integrations → API Library for the connection layer.

Build and change Custom APIs conversationally with the Copilot.

Anatomy of a Custom API​

  • Name & description — a snake_case name (get_order_status, freshdesk_create_ticket) and a description of what it does.
  • Input fields — the parameters the endpoint accepts, each with a type (string, number, boolean, enum, or date) and, for enums, the allowed options. Some inputs are required.
  • Integration(s) — the connection the call runs on. A Custom API usually points at one integration, but it can draw on more than one when a single call needs data from several providers.
  • Logic & formatting — how inputs are shaped before the call goes out (strip the # from an order ID, reformat a date, add a prefix). This transformation lives inside the Custom API, not in the data point that calls it.
  • Sample inputs — example values used while building and testing the endpoint.
  • Dependent APIs — other Custom APIs this one relies on, when a call needs a prior lookup.

Provider API documentation can also be saved against the library — endpoint docs plus non-endpoint facts like a provider's custom fields, channels, status mappings, and enum values. The Copilot uses this when generating new Custom APIs and to answer provider-metadata questions ("what are the Freshdesk ticket custom fields?"). Anything you tell it to remember about a provider ("our Unicommerce channel codes are…") is stored here and reused by every future endpoint on that provider.

Flowcall's own APIs​

Not every endpoint points outward. The Flowcall Integration exposes Flowcall's own capabilities as endpoints you can build on — send an email from the connected mailbox, search your product catalog, search or count tickets, and read or write resource records. They behave like any other Custom API and can be mixed with external ones in the same flow.

See Flowcall Built-in APIs for what each one does and how it's configured.

Dependent APIs and samples​

A Custom API can call another Custom API instead of an integration directly. That's what the dependent APIs field records, and it's how bigger endpoints stay maintainable: a small "raw" endpoint fetches provider data in the provider's own shape, and a wrapper on top calls it — possibly several of them — and returns the combined result.

Two things follow from this:

  • Build the raw endpoint first. A wrapper can only be generated once the endpoints it depends on actually exist.
  • Save a sample response on each one. Source APIs in particular are only generated after every dependency has saved sample data, because that saved response is what the mapping into Flowcall's normalized shape is written against. If a dependency has no sample, the Copilot asks you to test and save it first instead of guessing the field names.

A wrapper that composes several providers is built to tolerate partial failures — if one client returns nothing, the result is assembled from whichever ones did.

Testing a draft​

When the Copilot drafts an endpoint and every required input already has a sample value, it runs the draft immediately and shows you the real response — the underlying calls it made, their status, and the shape of what came back — before you save anything.

This only happens for calls that are safe to repeat: reads and lookups. Anything that creates, updates, cancels, refunds, or otherwise changes state is never fired automatically; test those yourself from the draft card when you're ready.

Source APIs​

By default, the built-in data the AI relies on comes from your default ecommerce store (for example, Shopify). A source API overrides that: you designate a Custom API as the source for a category of built-in data, and the AI uses it everywhere it would normally use the default store.

This is what makes Flowcall work when your operational data doesn't live in Shopify — orders in Unicommerce, a custom ERP, a homegrown backend. A Custom API can be set as the source for:

Source categoryWhat it supplies
Order detailsThe full order record — status, fulfillment, tracking, dates, line items. This feeds the order data points and the order context the AI reads in any flow.
Order listThe customer's orders, used to select which order a conversation is about.
Product listThe product catalog used for search and recommendations.
Order timelineThe order's tracking/status events over time.

Each source has its own prompt describing how to map the provider's raw response into the shape Flowcall expects, so the rest of the product — flows, built-in data points, order selection — keeps working unchanged.

Why this matters​

The order and customer data points don't fetch data themselves — they read from whatever you've set as the order-detail (and customer/order-list) source. So designating an order-detail source API is what points "order status," "is delivered," "days since delivered," and every other order data point at your real system of record. Set it once, and every flow that looks up an order uses it — no per-flow wiring.

"Use our Unicommerce order API as the source for order details instead of Shopify." "Set get_orders_erp as the order-list source."

Editing safely​

The Copilot distinguishes edits to the Custom API from edits to the data point that calls it:

  • Adding, removing, or renaming a field on the endpoint, or changing how a value is formatted before it's sent → a Custom API change.
  • Changing which conversation value feeds an endpoint's field → a data point change.

Naming the layer when it matters ("edit the API, not the data point") keeps the change where you intend it.