This article describes the types of mappings available but primarily focuses on API response mapping and the minor differences between using the Flow Builder Mapper and the API Builder Mapper.
Tip
Configure your API response schema before you start mapping. This way, you can use the Auto-map feature without encountering response mismatches.
You can structure your API response data to conform to the OpenAPI definition structure required for your business purpose. Even in cases where your API consumer has the OpenAPI specs that the Celigo platform provides, they may make a mistake or not follow the schema properly. Additionally, your lookups or imports may change the data's format, leading to irregularities between your consumer's data and the final output. Mapping allows you to ensure the data matches your final output.
For example, let's say you create a new pet. The pet data sent can include name, birthday, vaccination records, food brand, etc. Once the API consumer sends the data, it passes to an import step to add the new pet to your pet store's database. Here, you can map your import and response data.
After you've mapped the import data, it will be sent downstream to the API response. However, at this point, the data is in the format your database outputs, which might not suit your API response needs. After creating your API response, you can easily map the data from the database structure into the format required by your response schema. For example, the database output may include a petId. You want to send the petId back to the consumer in the response, but your schema may call it a petNumber instead of a petId. Using the API response mapper, you can map the petId from the database to the petNumber in your response schema and send it in the Success response.
There are four types of mapping: import, response, results, and API response. Mapping data defines how your records are compared, merged, or transformed between lookups, imports, and your final API response schema. Click the icon to open the mapper. Lookup caches are available to use throughout API builder.
-
Import mapping (import): Import mapping defines how the provided data relates to your import destination record data. You can use Mapper 1.0 or Mapper 2.0 to configure import mappings.
-
Response mapping (import): You can add response mappings to capture data returned from an import within your API. Response mappings allow you to insert the response data of an import back into your source record so that you can reference that data in subsequent steps of your API.
For example, suppose an application automatically assigns pet IDs to newly imported pets and includes them in the response. In that case, you can add those field values to the source record for future use, like sending the pet ID to the API consumer after it's created.
-
Results mapping (lookup): Results mapping is similar to response mapping, but instead of returning the response after an import, results mapping allows you to merge the resulting records returned by a lookup in your API back into the provided data. The returned lookup records can be used later in the API.
-
API response mapping (API response): Map your source records to the API response schema records.
For example, to create a new pet, you must map the source record you sent (e.g., name, birthday, vaccinations) to the response you'll send after the pet is created. The response schema in this mapper is automatically generated based on the API response body schema in the API response.
Tip
You can change the schema in the Mapper and sync the changes to the API response schema for an accurate OpenAPI spec.
In the API response step, click → Mapping () to open the Mapper.
The schema can include arrays, objects, nested fields, etc., and the supported media type is JSON. You can use handlebars to supplement your mappings in cases where you have complex data requirements.
Click Auto preview or Preview to view the HTTP response body and other details you've added to your API response.
For more on utilizing Mapper 2.0, see:
Response schema mismatch
If you add, update, or delete fields in the API response step after completing your mappings, the HTTP response body schemas will not sync. In this case, you'll receive a warning to open the Mapper and click Auto-populate response fields or manually make changes to generate an accurate OpenAPI spec.
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."
}