Use data from your own system in a workflow

When to use it

Use a Call an API step when a workflow needs something only your own system knows or does: look up an order, check whether a subscription is active, or create a record such as a return request. The step calls your system, picks the values you ask for out of the reply, and the rest of the workflow can show them or branch on them.

This is different from the AI's API tools on Brand → Knowledge. The AI decides by itself whether and when to call one of those while it answers. A Call an API step always runs, exactly at the point in the workflow where you put it.

1. Add the step

Open the workflow, click Add a step on a card and pick Call an API from the group Ends the card — the last step, one per card. It is always the last step of its card, and it has two exits: Worked and Failed. Add the next card on each with its +.

If the call needs something from the visitor first, such as an order number, ask for it in an earlier step and save the answer under a name — see Collect data with a workflow.

2. Set up the request

• Method — GET, POST, PUT, PATCH or DELETE.
• Address — the full address, starting with https. It can contain values the workflow already has, such as https://api.example.com/orders/{{ order_id }}; they are encoded for you. The Values you can use here card lists them. While the address is empty, the card reads Not set up yet — enter the address and the workflow cannot be switched on (see section 7).
• Yaplet signature — the easiest way to prove to your own system that the call comes from Yaplet. Switch it on and type a shared secret that your server also keeps. Every call then sends a Signature header with the SHA-256 hash of that secret — the same header the AI's API tools send — and your server compares it with the hash of its own copy. The secret is kept like a password (see below).
• Headers — one row per header, added with Add header. For anything secret, such as an API key, switch on Password.
• Body (not for GET) — under What to send pick No body, Fields (sent as JSON) or Write the JSON myself. Values are escaped for you, and Content-Type: application/json is added unless you set your own.
• Wait at most (seconds) — 8 by default, 30 at most.

A header, body field or address parameter whose value turns out empty is left out of the request.

How passwords are kept

Once you save the workflow, a header marked with the Password switch shows only saved •••• and a Replace button. The value is stored on our servers and never shown again, to anyone. It is sent only to the web address it was saved for: if you change the address to point somewhere else, the password is cleared and you enter it again. For the same reason, a password needs the address written out in full — values can go into the path and the query, not into the domain name.

A step the AI left as a draft

When the Copilot builds a workflow for you and the call it needs does not exist on your system yet, it adds the Call an API step without an address. The step's panel then shows a note, What this call must do (written by the AI), that tells your developer what to build. Once it exists, type the address — and the shared secret or any password — into the step yourself, never into the chat with the AI. Click Remove to delete the note when you no longer need it. More in Build a workflow with AI.

3. Read values from the reply

Under Values to read from the reply, add one row per value with Add value — up to 20:

• Where in the reply — the path to the value. A dot goes one level deeper and [0] is the first item of a list: order.status, items[0].name. Spelling and capitals must match.
• Save as — the name later steps use, such as order_status. Letters, digits and underscore only.
• Type — Text, Number, Yes / no or Date. A Number can be compared as greater or less than in Conditions. Pick Text if unsure.

Your system must answer with Content-Type: application/json; no value can be read from any other reply. Show an example in the panel shows a sample reply and what each path reads from it.

4. Test it

The Test button calls the address right away, with a made-up sample visitor and the sample values you type for each {{ … }} in the request. It shows whether the call worked or failed, the status, how long it took, the reply itself and what each value came out as. A password you typed but have not saved yet is used for that one test and is not stored. Your organization can run 10 tests a minute.

5. Worked and Failed

The step goes on through Failed when:

• your system answers with an error status,
• it does not answer within the time limit,
• the address is not allowed — for example plain http, or an address on an internal network,
• the reply is larger than 5 MB,
• a value you read is missing or empty in the reply (for example null), or does not fit the type you picked. A value you ticked Optional is the exception: when the reply leaves it out, it simply stays empty and the step still goes on through Worked. Use it for something your system only sends sometimes, such as a flag that says a person should take over.

A GET is tried once more after a time-out, a network error or a server error. Other methods are never repeated, because a second try could change something twice.

The editor offers the values only on the cards after Worked. If Failed has no card after it, the visitor gets "We encountered an issue processing your request. An agent will assist you shortly." and the conversation goes to your team. Add your own card on Failed (its +) to handle it differently.

The workflow's Runs tab shows every call: the status, the attempts, which values were missing and, when there was trouble, the first part of the reply.

6. Use the values

After Worked, every later step can use the values. Type {{ order_status }} into Write a message, an Open link address, the note of Request agent, Send to VEX AI, a form pre-fill or another Call an API step — or pick the value in a Conditions rule. Nothing from the reply reaches the visitor unless a step prints it.

7. Keep it safe

• https only. A call over plain http is refused.
• No address, no switching on. While any Call an API step has no address, Publish in the editor and the Active switch on the Workflows list are refused with "Fill in the address of every Call an API step before switching this workflow on." Saving a workflow that is already switched on is refused too: "Fill in the address of every Call an API step before saving — a switched-on workflow cannot have a Call an API step without an address." A switched-off workflow saves as usual, so a draft step can wait for its address.
• Nobody confirms the call. It runs the moment the workflow reaches the step, without asking the visitor first. With the User says trigger, the AI even starts the workflow on its own. Before anything that changes data — cancelling an order, changing an address — add a Buttons step that asks the visitor to confirm, and make the call only from the "Yes" card.
• Only the external ID is verified. {{ external_id }} is the user id your website signs when it identifies a logged-in user (see Identify your logged-in users with custom data). Everything else — name, email, the visitor's answers — comes from their browser and can be made up. Never let your system show or change someone's data just because a name or email matches.
• Copies carry the passwords. Duplicate and Copy to another brand… copy the saved passwords along with the workflow.

8. On phone calls

The step also runs on calls answered by a voice agent. There it waits at most 4 seconds, whatever you set, and tries only once. If it fails and Failed has no card after it, the caller hears a short apology ("Sorry, I couldn't complete that request right now.") instead of being handed to your team.

Next step

See where else a workflow runs in Where a workflow can run, and pass the results to your team in a note with Hand off from a workflow to a human agent. For the workflow editor itself, see the Flow editor documentation.