You want to build an integration where your users need to search for records (for example, contacts, deals, etc.) in a Zapier-like interface where the user picks an object type and then enters search criteria. Using the Engine Awesome API, you can get a list of Object Types and indexed fields. With that list in hand, you can dynamically render a search form so that your app can perform the search as your user builds a query.
Please note—this is an overview tutorial with no code included. It’s all about understanding the process: leveraging the Engine Awesome API to dynamically create a search interface where your app performs searches as users build their queries.
This tutorial references our API Documentation.
1. Pick Your Object Type
Before users can search, they must decide what Object Type they want. Rather than hardcoding a specific type, let your users choose from a list. You can achieve this by providing a form where users can select an Object Type. To populate that form, pull the available object types from our “Get All Object Types” endpoint:
GET https://{{team_slug}}.engineawesome.app/api/v1/object-types
Example: https://dundermifflin.engineawesome.app/api/v1/object-types
This endpoint returns a list of available Object Types—like contacts, leads, orders, etc.—that your application supports. By doing this, you let users choose the object they’re interested in right from the start, setting the stage for a more targeted search experience. This flexibility improves user engagement and reduces the need for manual updates when new object types are added.
2. Get the Indexed (Searchable) Field Info
Once the user selects an Object Type, the next step is to find out which fields are available for searching. This is essential because it lets your application check if a record already exists—helping you decide whether to add a new record or update an existing one. To retrieve this metadata, use the “Get Searchable Fields for Object Type” endpoint:
GET https://{{team_slug}}.engineawesome.app/api/v1/zapier/fields/{{objectType}}
Example: https://dundermifflin.engineawesome.app/api/v1/zapier/fields/aef3b3cc-31c1-40f5-8ab6-bdb3d8bb47f5
Replace {{objectType}} with the type ID selected by the user. When you make this call, you’ll get back a list of fields that can be searched. This list includes:
- Field Keys & Labels: The technical name (key) and a user-friendly display name (label) for each field.
- Data Types: Information on whether a field contains text, numbers, dates, etc.—which helps determine the proper input control for that field.
This metadata is your blueprint for building a dynamic search form that’s both precise and adaptable.
3. Build a Dynamic Search Form
Now that you have all the field information, it’s time to craft your search form. The goal here is to create a flexible and super user-friendly interface. Here are some key points to consider:
- Show Friendly Labels: Use the labels provided by the API to clearly indicate what each field represents. This way, users aren’t left guessing what “first_name” or “order_id” might mean.
- Match Input Types to Data: Choose the right kind of input for every field. For instance, if a field is a date, a date picker makes sense; if it’s text, a simple text box will do the trick. This ensures data is entered correctly and consistently.
- Dynamic Adaptability: Building your form this way ensures that if the backend ever updates which fields are searchable or adds new operators, your search form automatically stays current without manual intervention.
By generating the search form dynamically, you create a system that evolves with your backend, making it more resilient to changes over time.
4. Run the Search Query
After users have entered their search criteria into the dynamic form, the next step is to run the search query. Use our “Object: search by field” API call to check if a record already exists:
GET https://{{team_slug}}.engineawesome.app/api/v1/objects/{{objectType}}?{{field_slug}}={{field_value}}
Example: https://dundermifflin.engineawesome.app/api/v1/objects/aef3b3cc-31c1-40f5-8ab6-bdb3d8bb47f5?last_name=bruner
This call allows your application to determine whether the user’s search criteria match an existing record. By substituting the appropriate {{objectType}}, {{field_slug}}, and {{field_value}}, your application can dynamically build the query. The results of this search inform whether you need to add a new record or update an existing one, helping to avoid duplication and maintain data integrity.
5. Add Additional Steps
Once you have these core steps in place—where users specify what they need, the system finds it, and the results are displayed clearly—you can consider extending the process further. For example:
- Multi-Step Workflows: A user might search for and add/update a contact and then need to add/update the associated company. This would require the user to go through the search process multiple times in your UI.
- Chained Integrations: You could allow users to continue their workflow seamlessly by linking multiple records together.
These additional steps enable you to build more comprehensive and user-friendly integrations that accommodate complex data relationships and workflows.
Wrapping It All Up
Recap of the Process:
- Choose the Object Type:
Let users select the type of record they want to search for by pulling a list of object types from the “Get All Object Types” endpoint:GET https://{{team_slug}}.engineawesome.app/api/v1/object-types - Retrieve Searchable Fields:
Once an object type is selected, fetch the indexed (searchable) fields using:GET https://{{team_slug}}.engineawesome.app/api/v1/zapier/fields/{{objectType}}This provides the metadata needed to construct the search form. - Build a Dynamic Search Form:
Create a form using the field metadata that displays friendly labels and uses the appropriate input types. This ensures your search interface is both clear and adaptive. - Execute the Search Query:
When the user inputs their search criteria, build and run a query with:https://{{team_slug}}.engineawesome.app/api/v1/objects/{{objectType}}?{{field_slug}}={{field_value}}Use the results to decide whether to add a new record or update an existing one. - Extend the Workflow:
Consider additional steps for complex integrations, such as linking related records or supporting multi-step search processes, to further enhance the user experience.
By following these steps, you create a search interface that’s both smart and adaptable. It adjusts automatically when changes occur in the backend, saving you from updating your UI manually. This dynamic, user-friendly design makes building integrations—much like those on platforms such as Zapier—a breeze.
Please make sure to let us know when you build an integration for Engine Awesome, so we can let our customers know!
Happy building!