Articles in this section

Configure lookups, imports, guardrails, AI agents, and tools in API builder

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

  1. Go to Build build-icon.png, and then select APIs. Open your API. If you haven't created one, see Create and manage APIs using API builder.
  2. On the canvas, select + to the right of the API request or after the step where the new step belongs.
  3. Select Add destination / lookup, Add AI agent, Add tool, or Add guardrail.

    The step menu in API builder

  4. Create a new step, or reuse an existing one.
  5. Enter a Name and a Description.
  6. 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.
  7. 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.

  1. In the application picker, select your application. For a generic REST connection, select HTTP.
  2. 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.
  3. 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.
  4. 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.

  1. On the step, open the menu and select Error handling.
  2. 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.