Understand Custom APIs | Zoho Creator Help

Understand Custom APIs

This help page is for users in Creator 6. Find your Creator version.

1. What Does This Page Cover?

Learn about custom APIs and how to define their actions using Deluge functions, which can then be exposed as an API and called from an external platform. This will help maximize operational efficiency between multiple platforms, including Zoho Creator, and lower the difficulty in programming complex operations across external systems.

2. Availability

Custom APIs:
  1. Are available for creation only in the paid plans of Creator, whereas users in the trial plans can invoke them
  2. Can only be created, authorized, and managed by the super admin and admins , while other users can access them
  3. Are available in the United States (.com), Europe (.eu), India (.in), and Australia (.au) data centers

3. Overview

Custom APIs (Custom Application Programming Interfaces) are interfaces that enable developers to create their own APIs and define the functionality they want to expose to external systems, applications, and/or services from their services. These APIs enable different software systems to communicate and share data seamlessly. Unlike standard APIs that are provided by third-party services or platforms, custom APIs can be developed and tailored specifically for your application's requirements. They can also enhance user experience by enabling features like real-time updates, personalized content retrieval from various sources, and so on.

4. Custom APIs in Creator

In Creator, custom APIs enable developers to achieve specific functionalities tailored to their requirements by utilizing the existing functions in their applications. While Developer APIs (REST APIs) execute a fixed (predefined) action when invoked, custom APIs can be scripted to execute user-defined actions from external platforms. This means users can perform actions other than the pre-defined ones, on their Creator application's data from third-party applications by invoking their functions as a custom API. This customization ensures that the customized API aligns precisely with the needs of your organization, thereby optimizing performance and efficiency. 

Custom APIs also enable you to integrate your applications with third-party services, thereby allowing you to extend your application's capabilities by leveraging external resources. Furthermore, these APIs encapsulate your business logic, making it easier to maintain and update in one place. This means that any changes to business processes can be implemented within the API itself, without requiring modifications to the entire application. 

In Creator, the custom API can be created and managed in the Custom API builder. This builder lets you define the actions to be exposed as an API using an existing Deluge function (that has the action defined) and invoke the API from an external platform using the automatically-generated endpoint URL. 
Only super admin and admins can access the Custom API builder to create and manage custom APIs.
After invoking your custom API, you can view the status of your API hits (success/failure) and their error logs in the API Summary page.
Note:
  1. The number of API hits will be counted separately from the REST API hits in terms of pricing
  2. Currently, you can only use the already configured  Deluge functions as custom APIs. This means you cannot invoke cloud functions written using Java and NodeJS scripts as a custom API. 
  3. You cannot test your custom APIs in development environment since only the Deluge functions available in production environment can be exposed as a custom API. 

4.1 Functionalities of custom APIs in Creator

  1. Custom APIs can help invoke operations that are otherwise possible only in Creator. For example, sending push notifications , fetching results from AI form fields and performing other data related actions, and so on.
  2. Users can invoke Creator's own Deluge functions in your custom API instead of re-scripting a Deluge function or creating another custom API.
  3. Create secure custom APIs by implementing authentication mechanisms to ensure that data access is controlled and secure, thereby reducing the risk of unauthorized access or data breaches.
  4. Execute multiple logical operations through a single function execution.
  5. Analyze and manage custom API logs as a single operation in one place when executing a huge operation through multiple API calls or external scripts.

4.2 How are custom APIs built in Creator?

  1. Custom API Builder : A secure and easy-to-build interface that helps build a ready-to-use custom API which facilitates data exchange between Creator and external systems. 
  2. Deluge functions : Your existing Deluge functions can be invoked in custom APIs.

4.3 Components of a custom API in Creator

  1. Basic inputs
  2. Endpoint URL
  3. User scope
  4. Request
  5. Function
  6. Response

Basic inputs


The Basic Inputs tab lets you define your custom API. You can specify a name for your custom API, add a link name that will be used in the endpoint URL, and describe the purpose of your custom API. 
While naming your custom API, it is essential to choose names for your custom APIs that are descriptive, memorable, and reflective of their functionality. 

Endpoint URL

API endpoint URL refers to a specific URL that the custom API exposes to enable communication with external systems. This URL defines the path that users can use to access particular functionalities provided by the API. In Creator, the custom API endpoint URL will be automatically generated based on the specified API link name in the below format. This URL lets you and your users identify the specific goal of your API. You can copy and use the URL from the places mentioned in the next section as required.
https://www.zohoapis.com/creator/custom/<appadmin_name>/<customAPIname>
Endpoint URL functionalities

How to get the endpoint URL? 
You can copy the endpoint URL from the following places:
  1. Summary tab
  2. Respective Custom API card
  3. Detailed view 
The following video shows the places from where you can copy the endpoint URL.

Who can access the endpoint URL? 
The access is based on the user scope defined in the Request tab. If you've chosen the Admin Only option, only the application's super admin and admins can access and invoke the custom API. If you've chosen the Selective Users option, only the users specified (along with the super admin and admins) can access and invoke the custom API.
Note: If an unauthorized user tries to invoke the custom API using the endpoint URL, a System Response (i.e. Creator's Response) will be displayed. 
Where can the endpoint URL be invoked in?  
You can use it in any third-party services to invoke the custom API.

Note
  1. The endpoint URL must be copied and pasted in the required external platform to invoke the custom API.
  2. When you edit the link name of your custom API, change its scope or authentication method, the endpoint URL preview will be automatically updated in the Custom API builder. However, you need to manually update the endpoint URL wherever it has been invoked. If you invoke the custom API without updating the endpoint URL, a system response (error) will be shown. 

Request


In the Request tab, you can specify the method, authentication, and content type used in the body of the request.
  1. Request Methods
  2. Authentication
  3. User Scope
  4. Content Type

Request Methods for Custom API

These methods let you define the type of action you want to perform when triggering an API request. The custom API builder enables you to choose from four methods: GETPOST, PUT and DELETE.
  1. GET: This method lets you request and retrieve data from the specified endpoint URL. In a GET request, data is typically sent as query parameters appended to the end of the URL.
  2. POST: This method lets you submit data to be processed to the specified endpoint URL. In a POST request, data is typically sent in the request body, often in formats like JSON or form data. Here, the data is not appended to the URL. 
  3. PUT: This method is used to update or replace an existing resource or to create a new resource at the specified URL. 
  4. DELETE : This method is used to remove or delete a specific resource from the server at a given URL.

Authentication

In Creator, you can select the authentication type as either OAuth2 or Public Key. By default, OAuth, which stands for “Open Authorization” allows to authorize and authenticate API calls. It provides secure access for your Creator applications to access external resources thereby reducing the hassle of asking for a username and password every time a user logs in. If this option is chosen, only the users specified in the user scope can access and invoke the custom API.
If you choose the Public Key option, anyone can access and invoke the custom API.

User Scope

As a super admin or admin, you can define the level of access control granted to your admins and selective users using User Scope i.e., you can allow specific users to access the endpoint URL and invoke the API. You can either choose to give access control to only the admins in your Creator applications or to certain users by specifying their respective email addresses.

Content Type

Note: You can select the content type only for POST and PUT methods.
The content type is used to specify the format and structure of data being sent or received in a request or response to and from your Creator applications and external services. This helps the external service to understand how the request payload should be interpreted. Creator allows you to select a content type from the two formats: 
  1. Application/JSON: This content type can be chosen to indicate that the data in the API request is in JSON (JavaScript Object Notation) format. This tells the external service that the data in the request body is in JSON format, and it should be processed accordingly.
JSON is a widely used data-interchange format that is often used to represent data objects, arrays, and key-value pairs, and is both human-readable and machine-readable. It is commonly used for transmitting structured data between a client and a server, making it an ideal choice for API communication. 
  1. Multipart/form-data: This content type is used in API requests to send binary or textual data, such as files, to an external service. In a multipart/form-data request, the data is split into multiple parts, with each part having its own content type and headers. This allows for the inclusion of not only the data itself, but also additional information like filenames, field names, and content types for each part. A boundary string is used to separate the parts within the request. This string is unique and is specified in the request headers to indicate where each part starts and ends.
Multipart/form-data is commonly used when creating API endpoints that allow users to upload files or when working with forms that include file upload fields. When a user submits your form that contains a file input field, the custom API when invoked generates a "multipart/form-data" request to send the data to the external server.

Note: 
  1. Multipart/form-data can't have nested data like JSON, which means that it just contains separate "key value" pairs.
  2. It can have multiple entries on one key, unlike JSON.
If the Application/JSON content type is chosen, you can select the argument type as either of the two options as follows.
  1. Key and Value: This type lets you pass input parameters to your API endpoint as a key-value pair, and can be used when you need to pass a small number of distinct, named parameters in your API request.
Sample Request:
  1. {
  2. "name":"John",
  3. "age":30,
  4. "email":"john@zylker.com"
  5. }
In the above example:
  1. "name", "age", and "email" are keys.
  2. "John", 30, and "john@zylker.com" are their corresponding values.
  1. Entire JSON: This type lets you pass a complete and unstructured JSON object, including all necessary key-value pairs as a single argument. You can use this approach when handling webhook calls .
Sample Request:
  1. {
  2. "user":{
  3. "id":12345,
  4. "name":"Alisa",
  5. "email":"alisa@zylker.com",
  6. "age":28,
  7. "address":{
  8. "street":"123 Main St",
  9. "city":"Anytown",
  10. "country":"Zylkerland"
  11. },
  12. "orders":[
  13. {
  14. "order_id":1001,
  15. "total_amount":75.50,
  16. "status":"delivered"
  17. },
  18. {
  19. "order_id":1002,
  20. "total_amount":102.20,
  21. "status":"pending"
  22. }
  23. ]
  24. },
  25. "status":"success",
  26. "message":"User data retrieved successfully"
  27. }
In the above example:
  1. The JSON response contains various nested elements.
  2. "user" contains information about a user, including their ID, name, email, age, address, and a list of orders.
  3. "address" is a nested object within the user details, containing address-related information.
  4. "orders" is an array containing multiple objects representing different orders made by the user, each with its own attributes like order ID, total amount, and status.
  5. "status" and "message" provide additional information about the overall status of the API request/response.
When you choose Entire JSON for this custom API, ensure that you specify only one argument of string datatype here each key is associated with a specific value. 

Response

In this tab, you can choose a corresponding response type: Standard or Custom response.
  1. Standard response: This response will return standard status codes currently followed by Creator's REST APIs. When this option is chosen, a sample response will be displayed below.

  2. Custom response: This response lets you define and specify a custom status code and respective response codes as per your requirements. 

  1. You can specify up to 50 response codes for each status code.
  2. When you specify custom codes, the return type of the chosen Deluge function to be invoked must be Map.
  3. You must map the specified response codes to their descriptive messages in the Deluge function. 

Function


In the Actions tab, you can select the Creator application and the namespace that contains the Deluge function to be executed when the custom API is invoked. 

  1. When you create a Deluge function, it is recommended that you specify an appropriate namespace and function. This'll make it easier to define the actions of your custom API.
  2. It is recommended to exercise caution while including sensitive operation in your Deluge functions and ultimately giving access to specific users to invoke your custom API.

Summary


This tab lets you review your custom API details before completing its creation. After adding the required details in the previous tabs, you can review the API details displayed in the Overview, Request Parameters, and Response Body sections. If you need to make any modifications, you can go back and do so. Otherwise, you can proceed to save the custom API. 
When you create a custom API and exit the page before saving it, the custom API will be saved as a draft.

API logs


After successfully creating your custom API, you can view the essential details of the custom API, the application in which it is used, along with its creation and updation details. You can also view the number of API hits by the users who invoked the API, log date and time, status code, and status of the API (success or failure). Additionally, you can also view the API logs at different time periods: daily, weekly, and monthly.
  1. The API logs will display the logs of the last 30 days by default and maximum up to the previous 60 days.
  2. Only super admin and admins can view API hits i.e., users cannot view API hits.

Scopes to invoke custom API

Method
Scope
GET, POST, PUT, DELETE
Zohocreator.customapi.EXECUTE

5. See How It Works

Let's assume that you've built a School Management application that has separate modules for students, teachers, parents, and non-teaching staff. As an application admin, you need to process data from the bus-tracking iOT device installed in your school buses and is accessible to the bus drivers in your school. Let's assume you have the below two requirements.
  1. To fetch the pickup addresses of staff, students, and non-teaching staff in all the areas covered before a strip starts.
  2. To submit the students' attendance and average trip speed at the end of each trip.
To accomplish the above, you would usually require at least five APIs to be invoked.
  1. Three Get Records API to fetch the addresses from three separate reports.
  2. Two Add Records API to add details about the trip and mark that day's attendance as records.
Additionally, you need to fetch the records of absent students and notify the respective parents via SMS notifications.
To reduce the number of APIs created and achieve the same functionality, you can create a custom API and use an existing Deluge function that has the combined login to be invoked when the custom API is called.
Below video shows the execution of custom API to fetch the addresses from three separate reports.

6. Use Cases

  1. Hospital management: Let's assume you own a clinic and created a Hospital Management application using Creator. You want to fetch vital information from medical devices (fitted with sensors) worn by your patients, so that doctors will be immediately notified, monitor their vitals, and provide medical assistance as required. You can configure a custom API that is invoked whenever an abnormal reading occurs (considering various vitals such as heart rate, blood pressure, oxygen levels, and so on), The device sends these details via API request as a mobile notification to the respective doctor based on their availability. The assigned doctor can be prompted with a pop-up form in Creator (for smaller emergencies) to send medical advice to the treating medical staff. The doctor can also choose if an appointment is required immediately and book the earliest one. The patient receives the prescribed medical advice along with the appointment details (if applicable), via the API response. This data can also be added to the Appointment Booking and Patient Details forms respectively.
  2. Approval management: Let's assume that you have created a Project Management application using Creator. Your employees create proposal document in an external service, which need to be approved by you (admin). Additionally, you need to add a record in your Creator application every time a document is approved and maintain records of rejected documents. You can create a custom API which is invoked when a document is submitted from the external service for approval. This will trigger the approval workflow in Creator, which will initiate the process of approving the documents and change the status of the doc as "Approved". A record will be added in the Project Details report and Quote Details reports respectively. If a document is rejected, then the status of the document will be marked as "rejected" and a record will be subsequently added in the Project Details report and Document Feedback reports respectively.

7. Navigation Guide for Creation of Custom APIs

In the home page of your Creator account, navigate to the Microservices section and select the Custom API tab. Next, click + Create Custom API. The Custom API builder will appear. Check out how you can create custom APIs and use their functionality to your business's advantage.

8. Points to Note

  1. The link name of your custom API cannot contain special characters such as  !@#$%^&*.>.
  2. The status codes in custom response can range from 100 to 599.
  3. The response codes in custom response must be in the range from 1 to 9999 and cannot contain special characters such as  !@#$%^&*.>.
  4. When you change the user scope of your custom API to Admins Only from Selective Users, all the users you've previously added will be removed. 
  5. If you close the Custom API builder without saving, your changes will still be saved as a draft and you can continue editing them anytime from Microservices > Custom API > required custom API card.
  6. When you invoke a disabled API, an empty response will be returned i.e., invoking a disabled API will produce a record in API logs but will not be registered as an API hit. 
  7. Before you can delete a function used in your Custom API, you will have to remove the associated Custom API before deleting the respective function.

9. Limitations

  1. In the Response tab, you can add upto 50 status codes.
  2. Your custom response codes can contain only upto 4 digits.
  1. Create and manage custom APIs
  2. Rest APIs in Creator

    Zoho CRM Training Programs

    Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.

    Zoho CRM Training
      Redefine the way you work
      with Zoho Workplace

        Zoho DataPrep Personalized Demo

        If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.

        Zoho CRM Training

          Create, share, and deliver

          beautiful slides from anywhere.

          Get Started Now


            Zoho Sign now offers specialized one-on-one training for both administrators and developers.

            BOOK A SESSION








                                    You are currently viewing the help pages of Qntrl’s earlier version. Click here to view our latest version—Qntrl 3.0's help articles.




                                        Manage your brands on social media

                                          Zoho Desk Resources

                                          • Desk Community Learning Series


                                          • Digest


                                          • Functions


                                          • Meetups


                                          • Kbase


                                          • Resources


                                          • Glossary


                                          • Desk Marketplace


                                          • MVP Corner


                                          • Word of the Day


                                            Zoho Marketing Automation

                                              Zoho Sheet Resources

                                               

                                                  Zoho Forms Resources


                                                    Secure your business
                                                    communication with Zoho Mail


                                                    Mail on the move with
                                                    Zoho Mail mobile application

                                                      Stay on top of your schedule
                                                      at all times


                                                      Carry your calendar with you
                                                      Anytime, anywhere




                                                            Zoho Sign Resources

                                                              Sign, Paperless!

                                                              Sign and send business documents on the go!

                                                              Get Started Now




                                                                      Zoho TeamInbox Resources



                                                                              Zoho DataPrep Resources



                                                                                Zoho DataPrep Demo

                                                                                Get a personalized demo or POC

                                                                                REGISTER NOW


                                                                                  Design. Discuss. Deliver.

                                                                                  Create visually engaging stories with Zoho Show.

                                                                                  Get Started Now









                                                                                                      • Related Articles

                                                                                                      • Create and Manage Custom APIs

                                                                                                        This help page is for users in Creator 6. Find your Creator version. 1. What Does This Page Cover? Learn how to create a custom API and authenticate it to integrate with in Zoho Creator. Before moving ahead, click here to learn more about custom ...
                                                                                                      • Understand microservices

                                                                                                        Microservices are small, independent services or components of app that can easily be deployed to work in tandem with your application. You can build a robust application for your business. However, as your business grows, you will find that the ...
                                                                                                      • Understand Predefined Custom Filters

                                                                                                        This page is applicable to all report types except pivot chart and pivot table. Filtering is the act of drilling down to specific records, while omitting irrelevant records that are not required at the time of viewing. Quick filters already serve ...
                                                                                                      • Understand Connectors

                                                                                                        Overview Connectors allow Zoho Creator applications to communicate with third-party services. It contains the properties required to connect to a particular service and reduces the complexity, thereby, establishing a secure connection. Let us ...
                                                                                                      • Understand Permissions

                                                                                                        What Does This Page Cover? Learn how you can define unique permission sets such as Read, Write, or customized ones that decide on how different users can access the records. Availability Permissions can be accessed in all plans of Creator. Addition ...
                                                                                                        Wherever you are is as good as
                                                                                                        your workplace

                                                                                                          Resources

                                                                                                          Videos

                                                                                                          Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.



                                                                                                          eBooks

                                                                                                          Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.



                                                                                                          Webinars

                                                                                                          Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                                                                                                          CRM Tips

                                                                                                          Make the most of Zoho CRM with these useful tips.



                                                                                                            Zoho Show Resources