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 APIs.

2. Availability

Custom APIs:

1. Can be created and managed in all pricing plans of Creator. However, the number of times a custom API can be invoked is limited in the free plans
2. Can only be created, authorized, and managed by the  super admin and admins , while other  users  can access them
3. Are available in all data centers

3. Creating custom APIs

3.1 Custom API Creation Flow

3.2 See How To Configure

3.3 Steps to Create and Manage a Custom API

1. Create a Custom API
2. View Custom API details
3. Manage Custom API
4. Delete and Disable Custom API
5. Call a custom API

Create a Custom API

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. 

1. Navigate to the Microservices page in your Creator account.

You can also select the Custom API tab and click + Create Custom API if you're creating a custom API for the first time. The Custom API builder will appear, which can only be accessed by the super admin and admins.

It is essential to choose names for your custom APIs that are descriptive, memorable, and reflective of their functionality. 

The link name of your custom API cannot contain special characters such as  !@#$%^&*.>

Refer to this section to know about the API scopes for different methods.

1. If you choose Admin Only, the API will work on Admin's scope. 
   
   
2. If you choose Specific users, the API will only be accessible by the specified users i.e., you can specify the email addresses of the respective users.
   
   

5. Select the Content Type as either application/json or multipart/form-data. This is used to specify how the request payload should be interpreted by the server.

When you choose the argument type as entire JSON for your custom API, ensure that you specify only one argument of string datatype.

Custom response lets you specify the status code and respective response codes.

1. If you've chosen the Standard response type, the response will return status codes.
   
   
2. If you've chosen the Custom option, the Add Custom Response slider opens below.
   
1. Enter a suitable Status Code. For example, you can enter status codes like 200, 202, 401, and so on.
   
2. Enter corresponding Response Codes for the status codes you've entered. For example, the response codes could be 2002, 3400, 4434, and so on.
   
   

Step 4: Specify the details of function execution

In the Actions tab, specify the details of the function to be executed when called.

1. Choose the required application from the Application dropdown.

2. Select the respective Name Space that groups the function you want to be called.

Note: If no namespace is specified for your created function, then that function will be added to the Default namespace. 

3. Select the required Deluge function that needs to be executed when called from the dropdown.

1. View the Endpoint URL from the URL preview card.
2. Check the details displayed in the Overview, Request Body, and Response Body tabs.
3. Click Back to make changes to previous tabs. Your custom API will be saved as a draft.
4. Click Save after reviewing the changes. Your custom API will be created successfully and you'll be taken to the Detail View page of the created custom API.

Only super admin and admins can view API hits i.e., users cannot view API hits.

1. Navigate to the Microservices page in your Creator account.
2. Click the Custom API tab at the top-right corner.
3. Click the required custom API card. The Detail View page will appear.
   
   

1. Click the dropdown arrow beside Last 60 days to view the API logs at different time periods. The API logs will display the logs of last 30 days by default.
   
   
2. Click the Filter icon to view the API hits based on either Status Codes or API Status (success or failure), then click Apply.
   
1. If you've chosen the Status Code, enter the required value and click Apply.
   
2. If you've chosen the API Status, choose either Success or Failure and view the respective logs.
   
   

You can also click the Failure status to view additional error details. 

1. Click the Prev or Next buttons at the bottom the page to view more logs of API hits.
   
2. Click the ellipsis icon (triple dots) at the top-right to edit, delete or disable the custom API.
   
   

4. Manage Custom API

1. Manage Users
2. Edit custom API
3. Filter based on custom API state
   

Manage Users

1. Navigate to the Microservices page in your Creator account.
2. Click the Custom API tab at the top-right corner.
   
3. Select the required custom API card.
   
4. Click (n) Users  beside User Scope to add more users if you've selected the Selective Users option in the User scope.
5. Add the email addresses of admins and users in the Manage Users popup that appears.
   
   
6. Click Save.

Note: You cannot edit the User Scope inside the API Detail View page.

Edit custom API

1. Navigate to the Microservices page in your Creator account.
2. Click the Custom API tab at the top-right corner.
3. Click the ellipsis icon (triple dots) in the required custom API card.
4. Click Edit API to edit your custom API. The Custom API builder will appear.
   
   
5. Make the required changes in the respective sections and click Save after previewing the changes.

Filter based on custom API state

1. Navigate to the Microservices page in your Creator account.
2. Click the Custom API tab at the top-right corner.
3. Click the filter icon at the right corner of the Custom API tab.
   
   
4. Select the status - enabled, disabled or draft to view the custom APIs created in the respective stages.

Delete and Disable Custom API

1. Navigate to the Microservices page in your Creator account.

2. Click the Custom API tab at the top-right corner.

3. Click the ellipsis icon (triple dots) in the required custom API card.

4. Select the Disable option to disable the custom API. 

When you invoke a disabled API, an empty response will be returned. Invoking a disabled API will produce a record in API logs, but will not be registered as an API hit. 

5. Click Disable in the Disable Custom API popup that appears. The respective API will be disabled in the Microservices section. 

You can click Enable to enable it.

6. Click Delete to delete the required custom API. 

Note: When a custom API is deleted, it is removed from Microservices but the function associated with that custom API is retained in it's respective Creator application.

1. 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.
   
2. When you update a function that is currently being used in any of your custom APIs, you will be notified that the API will be configured to the latest version of the updated function.

5. Calling A Custom API

Before invoking a custom API, you need to perform the steps mentioned under each of the below headings. To invoke the custom API you've created, you can use the endpoint URL copied from the the detailed view of your Custom API in the external service from which you to perform the defined actions.

1. Register the client application
2. Request the authorization code
3. Generate the access and refresh tokens
4. Refresh the access token
5. Revoke the refresh token

1. If you've chosen the authentication type as OAuth2, the specified users or admins will be authenticated and they can directly invoke the endpoint URL in any external platform.
   
2. If you've chosen the authentication type as Public Key, the public key will be displayed in the API Detail View page. This needs to be appended as a parameter to the Endpoint URL.
   
3. Any user in your Creator application can invoke the custom API using this public key.
   

6. 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.
   
8. If you’ve chosen the authentication type as Public Key, you need to append the same as a parameter in the Endpoint URL before invoking your custom API. For example, the Endpoint URL with the public key appended will look like:

1. https://www.zohoapis.com/creator/custom/<account_name>/<app_name>?publickey=<value>

7. Limitations

1. In the Response tab, you can add upto 50 status codes.
2. Your custom response codes can contain only upto 4 digits.

8. Related Topics

1. Understand custom APIs
   
2. Custom API Status Codes
3. Rest APIs in Creator