Skip to main content
Custom API is the most useful action type. It lets the employee call an external HTTP endpoint mid-conversation — checking an order status, looking up live stock, creating a support ticket, or updating a CRM record.

​
Build the action

  1. Name it. Any language, any characters — this is for you and the employee to recognize the action, not code. “Check Order Status” is fine.
  2. Add input parameters. Define the values the employee needs to gather before it can call the action. For each one, set:
  3. Configure the endpoint. Set the method (GET, POST, PUT, PATCH, DELETE) and the URL, plus any query parameters appended to the request and headers the target API requires, such as authentication tokens. For POST, PUT, PATCH, and DELETE, you also get a JSON request body editor.
  4. Reference values with the insert button. Reference input parameters as input.parameter_name and contact attributes as contact.attribute_name inside the URL, headers, query parameters, or body. Use the editor’s insert button rather than typing the prefix by hand, so you do not end up with a broken reference.
  5. Test before saving, using both modes available:
  6. Map the response. Choose which fields come back to the employee — see Response mapping below.
Custom API action builder
Input parameter names must be code-style, no spaces — they are referenced directly in the endpoint and body. If you catch yourself typing one with a space, fix it before saving.
Keep endpoints idempotent where possible, and never return sensitive data the employee should not repeat to a contact. Pair API actions with Boundaries so the employee knows when not to call an external system.

​
Response mapping

After you test a Custom API Call, the raw response comes back — and it usually contains more than the employee needs: internal IDs, success flags, metadata, timestamps. Response mapping is where you trim that down.

​
Why it matters

None of that extra data helps answer the contact, and all of it adds noise the employee has to sift through every time the action runs. Response mapping lets you select only the fields that matter — an order status, a price, a stock count — and drop everything else.

​
How to use it

  1. Select the fields you want to keep. If the response includes an id or success flag you do not need, leave it unmapped — you are choosing what reaches the employee, not editing the API itself.
  2. Rename fields for clarity, if needed. Some APIs return vague or technical names. If a value comes back as val_1 or stat_cd, give it a friendlier output name so both the employee and your team understand what it represents.
Response mapping table with API response fields selected and renamed for the employee to use
Response mapping earns its keep on APIs that return a large or deeply nested response — a full order object with shipping details, line items, and internal metadata benefits from mapping just the two or three fields your guideline actually references. A simple lookup that returns three fields probably needs little trimming.
If a guideline references a specific value from an action’s response, make sure that field is actually mapped. A field the employee cannot see is a field it cannot use, no matter how clearly the guideline describes it.

​
Example: live stock instead of a crawled page

A crawled page cannot reliably answer “is the medium blue hoodie in stock?” — the count it saw during the crawl may already be wrong. A Custom API Call can:
  1. Be named something like Check Product Stock.
  2. Take an input parameter, product_name or sku, so the employee knows what to look up.
  3. Point at your store’s product API, using input.product_name in the request.
  4. Map the response to just in_stock, quantity, and price — not the raw JSON your store returns.
See Add your website for why crawled links are the wrong tool for data like this in the first place.