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 plans of Creator, where as the invoke limit varies according to the subscribed plan.
2. can only be created and managed by the super admin and admins, while other types of users can invoke them based on the configured user scope.

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

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  !@#$%^&*.>

The scope required to perform these methods is Zohocreator.customapi.EXECUTE.

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

3. Select the Argument Type as either Key and Value or Entire JSON. Learn More

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

4. Select the authentication type from OAuth2 or Public Key. By default, OAuth2 will be selected.

1. Admin only - Super admin and admins
2. Selective users - Super admin, admins, and users specified using their email addresses in the input field when this option is chosen
3. Portal users - Approved portal users who have been added in the portal of the application selected in the Actions tab

Note: If Portal users is selected, the custom API can be invoked only from within a widget. Learn more

1. All - Every active user from the Users module in the Creator account

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.

The applications will be listed with a mention of the environment (Development or Stage) they are currently in.

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 under User Scope to add more users if you'd selected the Selective Users option in the user scope configuration.
5. Add the email addresses of admins and users in the Manage Users popup that appears, and 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 from Selective users to Admin only, Portal users, or All, all the users you'd have 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