Steps in API builder run your business logic between the API request and the API response. Add a lookup to retrieve data from a connected application, an import to create or update records, a guardrail to check records against a policy, an AI agent to process records with an AI model, or a tool to reuse packaged integration logic. An API needs at least one of these steps to return data, because the request and response alone don't retrieve or change anything.
Step types
| Step | What it does |
|---|---|
| Lookup | Retrieves data from a connected system or repository and adds it to each record. |
| Import | Creates, updates, or deletes records in a destination application. |
| Guardrail | Evaluates each record against a safety, compliance, or governance policy and returns a structured JSON result that flags a violation. Learn more about guardrails. |
| AI agent | Sends the mapped input data for each record to an AI model and returns a standardized response that later steps can map. Learn more about AI agents. |
| Tool | Packages integration logic, such as lookups, imports, mappings, and branching, behind a strict JSON input and output contract so you can reuse it. Learn more about tools. |
Add a step
- Go to Build
, and then select APIs. Open your API. If you haven't created one, see Create and manage APIs using API builder.
- On the canvas, select + to the right of the API request or after the step where the new step belongs.
-
Select Add destination / lookup, Add AI agent, Add tool, or Add guardrail.
- Create a new step, or reuse an existing one.
- Enter a Name and a Description.
- Select or create a connection to the application. Connection requirements vary by application, so search the help center for your application. For a universal connector, see the application's own API documentation.
- Configure the step. For an HTTP import, see Create an HTTP import. For the other step types, see Create a guardrail, Create an AI agent, and Create a tool.
Imports and lookups can return media types other than JSON, such as XML or CSV, when you use Override request/response media type in the step. The final API response must be JSON.
Add a destination or lookup
When you select Add destination / lookup, the Create destination / lookup page opens.
- In the application picker, select your application. For a generic REST connection, select HTTP.
-
For Step type, select one of the following.
Step type Use it to Import records into destination application Create or update records. Look up additional records (per record) Retrieve related records for each record. Look up additional files (per record) Retrieve files for each record. Transfer files into destination application Send files to the application. - Optional: Under Optionally choose from pre-built steps, filter by Source and Connection, sort by Similarity score, and select Import on the pre-built step you want.
- Select Next.
Configure a step
Each step has a menu with the following components. Select a component to configure it. A component that is already configured is marked in the menu.
| Menu item | Available on | What it does |
|---|---|---|
| Input filter | Imports, lookups, AI agents | Processes only records that match a condition. |
| Pre map hook | Imports, AI agents | Runs a script before mapping. |
| Mapping | Imports, AI agents | Maps source fields to destination fields. See Mapping data in API builder. |
| Post map hook | Imports, AI agents | Runs a script after mapping. |
| Post submit hook | Imports, AI agents | Runs a script after records are submitted. |
| Transformation | Imports, lookups, AI agents | Restructures the result data. |
| Output filter | Lookups | Keeps only lookup results that match a condition. |
| Pre save page hook | Lookups | Runs a script before the lookup results are saved. |
| Response mapping | Imports, AI agents | Adds the import response to the records. See Mapping data in API builder. |
| Results mapping | Lookups | Merges the lookup results into the records. See Mapping data in API builder. |
| Post response map hook | Imports, lookups, AI agents | Modifies data after response or results mapping. |
| Error handling | Imports, lookups, AI agents | Defines what happens to a record that fails. See Failed records. |
For hooks, see Create destination application hooks. To change data between steps, select the transformation icon on the connector between them. See Configure an API request using API builder.
Failed records
Choose what happens when a lookup or import can't process a record.
- On the step, open the menu and select Error handling.
-
Under The failed record should, select one of the following.
Choice Result Stop and return error via the API response node (default) API execution stops for the record. The errors array, with the error code, message, and source, is available at the Response picker automatically, and the Success value in the API response changes to false. Proceed to the next application regardless API execution continues to the next step. Map the errors array in results mapping or response mapping to use it in later steps.
To return a specific response for a failure, add a branch to the Response picker that matches the error code. See Branching in API builder. To control the message callers see, see Error handling in API builder.
Skip aggregation
Turn on Skip aggregation in the import when you push an API or resource to API Management and the API uses an import for any of the following applications: Amazon S3, Google Drive, Box, Azure, Dropbox, or NetSuite.
For examples of APIs that use lookups and imports, see API builder examples.