After configuring your API request and responses, you can incorporate lookups and imports into your API. Lookups allow your API to dynamically reference and retrieve critical data from connected systems or internal repositories, ensuring that each transaction is enriched with accurate and current information. Imports facilitate the integration of external data and enable you to update records or execute specific actions based on that data. Combined with branching, transformation, and other configurations, these features empower your API to execute sophisticated business logic, enforce data integrity, and drive real-time decision-making across your operations.
You can't create an API without adding a lookup or import. These steps allow you to execute your API. For example, if you want to create an API to retrieve pet data from a pet store, you need to:
-
Create an API request: This determines how the user will request your data (e.g., authentication, headers, query and path parameters, etc.).
-
Add a lookup: This will retrieve your pet data from the pet store database.
-
Create an API response: This determines the response you send to your API consumer (e.g., success, failed, etc.).
You're not retrieving pet data from a pet store without a lookup.
In the context of an API, a lookup searches for data. If you want to build an API that retrieves a list of dogs from the pet store database and other information, such as health records from a health application, you can add lookups to retrieve this information from your database or application.
An import receives data into an application. Where a lookup retrieves information from an application, an import writes data into an application or database (or deletes data from it). If you want to build an API that adds a new pet to the pet store database and adds the pet's health record to a destination application, you can add imports in your API.
You can directly reuse existing lookups and imports in the API builder, or clone and modify them before using them. After adding lookups and imports, you can map the lookup results and responses from the applications to the source record, which you can then return as the API response.
A composite API allows you to perform multiple related actions in a single call, representing a unit of business functionality. Instead of making separate API calls for each step, a composite API orchestrates them within one request, simplifying integration and ensuring consistency. Common use cases include placing an order, onboarding a customer, or processing a loan application, where multiple dependent operations must be executed together.
POST is often used because composite APIs involve executing multiple operations in a single request, including retrieving, creating, updating, or deleting data across different endpoints. Since POST allows sending a structured request body, it enables the API to bundle multiple actions and process them sequentially or as a batch.
GET aggregates or retrieves multiple data sources in a single request. For example, retrieving pet details and storing the information at once. It's helpful in APIs that require:
-
Faster data retrieval – Retrieving multiple resources in one call.
-
Reduced client-side processing – The server aggregates the data before responding.
-
Better API efficiency – Fewer round trips between client and server.
Creating a composite API requires a well-made request body and multiple lookups/imports.
To create or add a lookup or import, navigate to your API builder and add a step using the plus sign (+) to the right of the API request:
-
Click Add destination/lookup.
-
Search for your application or use a pre-built step created by Celigo. You can also describe your flow step, and Celigo will recommend a lookup or import that matches your requirements.
-
Select whether you'd like to create a lookup or import.
-
Add a Name and Description.
-
Create or use an existing connection to your application. The requirements for creating a connection vary greatly depending on the application. Always check the requirements for your specific application by searching for the application in our help center. If you're using a universal connector, you'll need to use a search engine like Google, Bing, or DuckDuckGo to find the API requirements for your application.
-
Build your lookup or import. Here's an example HTTP import.
Note
You can use the Override request/response media type field in imports to use a different media type (e.g., XML or CSV). However, the final API response must be in JSON.
-
Add additional configurations to your lookup or import. This can include:
-
Hooks and scripts
-
Use Failed records (
) to choose whether the process should stop and return an error in the API response node if a record fails or continue to the next step. Based on the error code received at the Response picker, branching rules can be added, an error response can be configured and customized, and an error message can be sent to the user. When one of the lookups or imports encounters an error, you can:
Tip
You can configure additional error handling aside from failed records.
-
Stop and return error via the API response node: This is the default. The API execution will stop for the record, and the errors array (including the error code, message, and source) will automatically be available in the API response branching node. Additionally, the “Success” boolean in the API response will be updated to
false. -
Proceed to the next application regardless: The API execution will continue to the next step; however, the "errors" array needs to be manually mapped in results/response mapping to use that information in downstream steps.
-
Below are some resources you can use to create effective lookups and imports:
Relative URI: /stores/
This API includes one request, one lookup, and two responses.
{
"method": "GET",
"endpoint": "/stores/",
"headers": {
"Authorization": "Bearer <your_api_token>",
"Content-Type": "application/json"
},
"query_parameters": {
"limit": 10,
"offset": 0,
"sort": "name",
"order": "asc"
}
}
A lookup allows you to process the request data and use it to search ("look up") the information for all pet stores. In this lookup step, you'll want to configure the request mapping so the data your API consumer sends is properly mapped to your database.
{
"status": "success",
"data": {
"stores": [
{
"id": 123,
"name": "Happy Paws Pet Store",
"location": "123 Main St, Springfield, IL",
"phone": "+1-555-1234",
"hours": {
"monday": "8 AM - 6 PM",
"tuesday": "8 AM - 6 PM",
"wednesday": "8 AM - 6 PM",
"thursday": "8 AM - 6 PM",
"friday": "8 AM - 6 PM",
"saturday": "9 AM - 3 PM",
"sunday": "Closed"
}
},
{
"id": 124,
"name": "Furry Friends Pet Store",
"location": "456 Elm St, Austin, TX",
"phone": "+1-555-5678",
"hours": {
"monday": "9 AM - 5 PM",
"tuesday": "9 AM - 5 PM",
"wednesday": "9 AM - 5 PM",
"thursday": "9 AM - 5 PM",
"friday": "9 AM - 5 PM",
"saturday": "10 AM - 2 PM",
"sunday": "Closed"
}
}
]
}
}
This API includes one request, three lookups, and two responses. The request retrieves details of a specific pet and its health records from a store.
Relative URI: /stores/:storeId/pets/:petId,
-
storeId(123): Represents the specific store (vet office or pet store). -
petId(101) → Unique identifier for the pet.
{
"method": "GET",
"endpoint": "/stores/123/pets/101",
"headers": {
"Authorization": "Bearer <your_api_token>",
"Content-Type": "application/json"
}
}
A lookup allows you to process the request data and use it to search for ("look up") a dog. In this lookup step, you'll want to configure the request mapping so the data your API consumer sends is properly mapped to your database.
A lookup allows you to process the request data and use it to search for ("look up") a cat. In this lookup step, you'll want to configure the request mapping so the data your API consumer sends is properly mapped to your database.
A lookup allows you to process the request data and use it to search for ("look up") the dog or cat's health records. In this lookup step, you'll want to configure the request mapping so the data your API consumer sends is properly mapped to your database.
{
"status": "success",
"data": {
"id": 101,
"name": "Buddy",
"age": 3,
"breed": "Labrador Retriever",
"weight_kg": 28.5,
"store": {
"id": 123,
"name": "Happy Paws Pet Store",
"location": "123 Main St, Springfield, IL",
"phone": "+1-555-1234"
},
"owner": {
"id": 1001,
"name": "John Doe",
"phone": "+1-555-1234"
},
"last_visit": "2024-01-15",
"vaccinations": ["Rabies", "Distemper", "Parvovirus"]
}
}
This request creates a new pet using the relative URI: /stores/:storeId/pets/. It includes one request, one import, four branches, and four responses. Each branch ends in a different response node.
Note
In this example, the API request data and the API response data are identical. In practice, the API request data may include different or additional fields. This is where mapping helps.
-
Uses
POST /stores/123/pets/to create a new pet instore ID 123. -
Includes detailed pet information such as microchip ID, breed information, and medical history.
{
"name": "Buddy",
"age": 3,
"breed": "Labrador Retriever",
"weight_kg": 28.5,
"microchip_id": "982000411234567",
"owner": {
"id": 1001,
"name": "John Doe",
"phone": "+1-555-1234"
},
"last_visit": "2024-01-15",
"vaccinations": ["Rabies", "Distemper", "Parvovirus"],
"medical_history": [
{
"date": "2023-06-10",
"condition": "Ear infection",
"treatment": "Antibiotics"
},
{
"date": "2022-09-05",
"condition": "Allergic reaction",
"treatment": "Antihistamines"
}
],
"dietary_preferences": {
"food_brand": "Hill’s Science Diet",
"meal_frequency": 2,
"allergies": ["Chicken", "Soy"]
},
"exercise_routine": {
"daily_walks": 2,
"walk_duration_minutes": 30,
"favorite_activity": "Fetch"
}
}
An import step allows you to take the request data provided above and send it to your database, thus adding the pet to the database. In this import step, you'll want to configure the import and response mapping so the data your API consumer sends is properly mapped to your database.
This is one branch ending in a successful pet creation. You'll want to add API response schema mapping here to include the unique ID and any other data you'd like to include in your response.
-
201 Created→ Indicates successful creation. -
Includes a unique ID (
101) for the newly created pet. -
Returns a timestamp (
created_at) to confirm when the record was created.
{
"status": "success",
"message": "Pet record created successfully.",
"data": {
"id": 201,
"name": "Buddy",
"age": 3,
"breed": "Labrador Retriever",
"weight_kg": 28.5,
"microchip_id": "982000411234567",
"store": {
"id": 123,
"name": "Happy Paws Veterinary Clinic",
"location": "123 Main St, Springfield, IL"
},
"owner": {
"id": 1001,
"name": "John Doe",
"phone": "+1-555-1234"
},
"last_visit": "2024-01-15",
"vaccinations": ["Rabies", "Distemper", "Parvovirus"],
"medical_history": [
{
"date": "2023-06-10",
"condition": "Ear infection",
"treatment": "Antibiotics"
},
{
"date": "2022-09-05",
"condition": "Allergic reaction",
"treatment": "Antihistamines"
}
],
"dietary_preferences": {
"food_brand": "Hill’s Science Diet",
"meal_frequency": 2,
"allergies": ["Chicken", "Soy"]
},
"exercise_routine": {
"daily_walks": 2,
"walk_duration_minutes": 30,
"favorite_activity": "Fetch"
},
"created_at": "2025-02-10T14:30:00Z"
}
}
This is one branch ending in a "bad request" response.
{
"status": "error",
"message": "Missing required fields: name, breed"
}
This is one branch ending in an "unauthorized" response.
{
"status": "error",
"message": "Unauthorized. Invalid API token."
}
Here’s an example of a composite API. This request performs multiple actions in a single API call. The relative URI in this case is /v1/composite . This API enables you to:
-
Checks if the pet exists in the system using its
microchip_id. -
A new pet record is added to the system if the pet does not exist.
-
If the pet exists, it orders pet food based on the pet’s dietary preferences.
Note
In this example, the API request data and the API response data are identical. In practice, the API request data may include different or additional fields. This is where mapping helps.
-
Methods (
POST) – Defines the HTTP method to be used. -
Requests Array – Specifies each action that can be performed:
-
Get Pet (
getPet) – Fetches pet details using apetId. -
Create Pet (
createPet) – Creates pet details using the response fromgetPet. -
Create Order (
createOrder) – Places an order only after the pet is updated.
-
-
Dependencies (
dependsOn) – Ensures correct execution order. -
Aggregated Response – Combines all individual responses into a single output.
{
"transactions": [
{
"id": "get_pet",
"method": "GET",
"endpoint": "/pets",
"query_parameters": {
"microchip_id": "982000411234567"
}
},
{
"id": "create_pet",
"method": "POST",
"endpoint": "/pets",
"dependsOn": "get_pet",
"condition": "not_found",
"body": {
"name": "Buddy",
"age": 3,
"breed": "Labrador Retriever",
"weight_kg": 28.5,
"microchip_id": "982000411234567",
"owner": {
"id": 1001,
"name": "John Doe",
"phone": "+1-555-1234"
},
"last_visit": "2024-01-15",
"vaccinations": ["Rabies", "Distemper", "Parvovirus"],
"medical_history": [
{
"date": "2023-06-10",
"condition": "Ear infection",
"treatment": "Antibiotics"
}
],
"dietary_preferences": {
"food_brand": "Hill’s Science Diet",
"meal_frequency": 2,
"allergies": ["Chicken", "Soy"]
}
}
},
{
"id": "order_pet_food",
"method": "POST",
"endpoint": "/stores/123/orders",
"dependsOn": "get_pet",
"condition": "success",
"body": {
"order_type": "pet_food",
"pet_id": "$get_pet.id",
"store_id": 123,
"food_brand": "$get_pet.dietary_preferences.food_brand",
"quantity_kg": 5,
"order_date": "2025-02-10T14:30:00Z",
"status": "Processing",
"delivery_time": "2025-02-11T10:00:00Z",
"special_requests": "Grain-free variant if available"
}
}
]
}
A lookup step allows you to retrieve pet details. In this lookup step, you'll want to configure the request mapping so the data your API consumer sends is properly mapped to your database.
An import step allows you to take the request data provided above and send it to your database, thus adding a pet. In this import step, you'll want to configure the import and mappings so the data your API consumer sends is correctly mapped to your database.
An import step allows you to take the request data provided above and send it to your database, thus creating an order for a pet. In this import step, you'll want to configure the import and mappings so the data your API consumer sends is correctly mapped to your database.
This is one branch ending in a successful response. You'll want to add API response schema mapping here to include the unique ID and any other data you'd like to include in your response.
-
201 Created→ Indicates successful creation. -
Includes a unique ID (
101) for the newly created pet. -
Returns a timestamp (
created_at) to confirm when the record was created.
{
"status": "success",
"transactions": [
{
"id": "get_pet",
"status": "success",
"code": 200,
"message": "Pet found in the system.",
"data": {
"id": 201,
"name": "Buddy",
"age": 3,
"breed": "Labrador Retriever",
"weight_kg": 28.5,
"microchip_id": "982000411234567",
"owner": {
"id": 1001,
"name": "John Doe",
"phone": "+1-555-1234"
},
"dietary_preferences": {
"food_brand": "Hill’s Science Diet",
"meal_frequency": 2,
"allergies": ["Chicken", "Soy"]
}
}
},
{
"id": "create_pet",
"status": "skipped",
"code": 304,
"message": "Pet already exists. No need to create a new record."
},
{
"id": "order_pet_food",
"status": "success",
"code": 201,
"message": "Pet food order placed successfully.",
"data": {
"order_id": 5012,
"pet_id": 201,
"store_id": 123,
"food_brand": "Hill’s Science Diet",
"quantity_kg": 5,
"order_date": "2025-02-10T14:30:00Z",
"status": "Processing",
"delivery_time": "2025-02-11T10:00:00Z",
"special_requests": "Grain-free variant if available"
}
}
]
}
This is one branch ending in a "bad request" response.
{
"status": "error",
"message": "Missing required fields: name, breed"
}
This is one branch ending in an "unauthorized" response.
{
"status": "error",
"message": "Unauthorized. Invalid API token."
}