Catalyst

by Zoho
×
Cancel
  • Tutorials
  • FAQ
  • Developer Tools
    CLI
    SDK
    Java Node.js Python Web Android iOS Flutter
    REST API
    Utilities
    Extensions Tools Integrations
    • Go to console

    Introduction to Catalyst API

    Overview

    Catalyst API offers a wide range of functionalities that enable an application developer to work with the Catalyst components remotely in their application. You can build and manage your Catalyst application using the APIs, as well as perform remote operations on it, similar to working with it using the Catalyst web console.

    For example, you can perform operations such as inserting data in a table in the Data Store, obtaining details of a folder in the File Store, or executing a function using the respective APIs.

    Catalyst implements REST API standards, and supports HTTP requests and responses for accessing its resources. Catalyst resources are exposed through their endpoint URLs, and the HTTP clients can access these endpoints using their specific APIs.

    Catalyst implements the following basic REST API principles:

    • The endpoint URL of each instance of a Catalyst resource is unique.
    • The HTTP method in the request dictates the operation to be performed on the resource.
    • Additional payload information is passed as parameters in the request. They contain the details of the operation to be performed.
    • Each request initiates a response from Catalyst.

    You can refer to the request format and response format sections for details and examples.

    Note:You can implement Catalyst functionalities in your application using the SDK provided for each programming environment. Catalyst SDKs provide better convenience and ease in your application building process, and enable you to perform all Catalyst operations that you can perform while working with the API. Refer to the SDK help documentations of the supported programming environments in Catalyst: Java SDK, NodeJS SDK, Web SDK, Android SDK, iOS SDK, Flutter SDK.

    Prerequisites

    Before you begin working with Catalyst API, you must ensure that the following prerequisites are satisfied:

    • A valid Zoho user account: Ensure that you have a valid Zoho login email address and password. You can sign up for a Zoho account here.
    • An authentication token: You must obtain a valid OAuth access_token to access Catalyst API.

    The help pages in OAuth 2.0 Authentication section will guide you in the process of understanding and obtaining authentication tokens.

    All Catalyst APIs will be accessible to a Catalyst user in the App Administrator role, (Catalyst application developer) after they obtain their access_token. All the collaborators of a particular project will also be able to execute all Catalyst APIs using their access_token.

    However, only certain operations are accessible for the users in the App User role, i.e., the end users of a Catalyst application with a Catalyst user authentication. The end user can only perform operations related to accessing specific application data, and not operations that modify the application. Each API help page will provide you with information on the execution permissions defined for it.


    Note:

    • If you want to execute Catalyst operations without generating any authentication tokens, you can use Catalyst SDK instead

    • Catalyst currently does not support a separate API authentication process for end users of Catalyst applications. If you implement Catalyst SDK in your application code, the authentication is automatically handled as an App Administrator authentication. To use Catalyst API independently, you must follow the steps described in th OAuth 2.0 Authentication section to generate OAuth authentication tokens.

    Multi-DC Support

    Overview

    Catalyst is currently hosted in five data centers. The base API URI to access all Catalyst APIs and the Zoho Accounts Server URI will be different based on the data center you are accessing Catalyst from.

    You must use the appropriate domain based on your location while sending an API request in Catalyst. This prevents conflicts with your browser and enables a smooth integration with your current session.

    The five data centers and their respective base API URIs supported by Catalyst for all APIs are:

    • US (USA): https://api.catalyst.zoho.com
    • EU (Europe): https://api.catalyst.zoho.eu
    • IN (India): https://api.catalyst.zoho.in
    • AU (Australia): https://api.catalyst.zoho.au
    • CA (Canada): https://api.catalyst.zohocloud.ca

    The corresponding Zoho Accounts Server URI for the five data centers that you must use while implementing OAuth 2.0 authentication are:

    • US: https://accounts.zoho.com
    • EU: https://accounts.zoho.eu
    • IN: https://accounts.zoho.in
    • AU: https://accounts.zoho.au
    • CA: https://accounts.zohocloud.ca

    Usage

    You must ensure you perform the following actions to make use of Catalyst’s multi-DC support:

    • You must use the appropriate Zoho Accounts Server URI in all the steps while implementing OAuth 2.0 authentication, such as while making an authorization request to generate the grant token, access token, or refresh token.

      For example, you can make this request to generate the grant token using a redirect method for the EU data center:
        
    
        
    copy
    
        
    
            
    
        
    
    
    
    
    
         
    https://accounts.zoho.eu/oauth/v2/auth?scope=ZohoCatalyst.tables.rows.CREATE,ZohoCatalyst.tables.rows.READ,ZohoCatalyst.tables.rows.UPDATE,ZohoCatalyst.tables.rows.DELETE&client_id=1000.0SRSxxxxxxxxxxxxxxxxxxxxx&state=testing&response_type=code&redirect_uri=https://www.zylker.eu/ShipmentTracking/&access_type=offline


    A response with the grant token will be returned after redirecting to the redirect URI, which will contain a location parameter as shown below:



    This location parameter specifies the domain of your account. In this case, the location is returned as eu.

    • You can enable multi-DC support after you register your client in Zoho’s API console. This lets you provide access to your application to users of a specific domain alone. For example, you can disable access to your application for the IN users and enable it for the other users. Refer to Register a New Client section for details.
    • As mentioned earlier, you must use the appropriate base API URI while sending an API request. For example, to fetch all rows in a table in your Data Store, you must execute the following request URL for the EU data center: https://api.catalyst.zoho.eu/baas/v1/project/{project_id}/table/{tableIdentifier}/row

    Multi-Org Support

    Overview

    Catalyst allows you to create and manage multiple organizations within your Catalyst account. A unique Org ID will be generated for every organization you create. You can create individual projects in each organization and also assign access permissions to people contributing to the project.

    You can only have one organization in your account as the default one. The organization marked as default will be logged in automatically when you sign in to your Catalyst account every time.

    While you execute an API from Catalyst, it will be executed for the default organization automatically. For instance, when you pass the project ID in your API request, Catalyst will automatically look for a project with the same ID in your default organization. However, you can execute an API for other organizations that are not the default by exclusively passing the unique Org ID of those organizations in your requests.

    Usage

    You can pass the Org ID as a header in an API request to access a project in that organization in this format:

        
    
        
    Sample API Header Format
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    -H CATALYST-ORG: 15090237

    You can check a complete sample request from the Request Format section.

    Request Format

    Request Methods

    Catalyst API follows the REST standards and supports the following HTTP methods for client requests for the described purposes:

    • GET : To fetch records from a Catalyst resource
    • POST : To insert new records in a Catalyst resource
    • PUT : To update existing records in a Catalyst resource
    • DELETE : To delete existing records in a Catalyst resource

    You must specify the request method for the operation while executing a Catalyst API request.

    Request URL

    The API requests are sent in the CURL format. A typical request URL is of the format:

    https://api.catalyst.zoho.com/baas/v1/project/{project_id}
    /{resource_name}/{additional_resource_details}


    Note: The base API URL will be the following for the other data centers:

    • EU: https://api.catalyst.zoho.eu
    • IN: https://api.catalyst.zoho.in
    • AU: https://api.catalyst.zoho.au
    • CA: https://api.catalyst.zohocloud.ca

    The common parameters passed in the request URL include the Project ID of the Catalyst project and the resource ID of the specific resource instance that is being accessed.

    Request Headers

    Mandatory header passed in the cURL request includes the following:

    Recommended headers passed in the cURL request can include the following:

    • Content-Type: A REST API standard that indicates the original media type of the resource passed. It is highly recommended to pass this header when the API requests include JSON payload or form data, for example.

    Optional headers passed in the cURL request can include the following:

    • Org ID: The Org ID of an organization that is not the default. You can obtain the Org ID from the multi-org portal in the Catalyst console.
    Note: If you do not pass an Org ID in your request explicitly, the API will be executed for the default organization.
    • Environment: The environmental header to specify the environment the request must be executed for. You can indicate if the API request should be executed for the development or production environment of the project.
    Note: If the project has been deployed to the production environment, then by default the API request will be executed for production, unless you specifically point to development using this header. If the project is not available in production, all API requests will be executed in the development environment automatically.

    Request Body

    Based on the purpose of the request, you can pass additional data in the body of the request in an API call, such as the column name and value for updating the column of a table, or the folder name for creating a folder.


    The particulars of the request to be sent, such as the headers and JSON attributes to be passed in the request, are specified in each API help page for the specific request.

        
    
        
    Sample API Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl “https://api.catalyst.zoho.com/baas/v1/project/4000000006007/segment/4000000006023/cache"
-X POST
-d ‘{“cache_name”:“City”,“cache_value”:“London”}’
-H “CATALYST-ORG: 15090237”
-H “Environment:Development”
-H “Content-Type:application/json”
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57"”

    Response Format

    Overview

    All Catalyst API responses will be in the JSON format. The response is sent after a request is processed by the Catalyst server.

    A typical response contains the status of the request processing, which can be success or failure, and a set of data based on the request made. For example, if the request was made to delete a record in a resource, the data will contain the details of the record that was deleted. The response details of each API are specified in its help page in detail.

    If the request was not processed successfully, the response will contain an appropriate error code to specify the error that occurred. The next section contains the error codes recognized by Catalyst and their descriptions.

        
    
        
    Sample API Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "cache_name": "City",
        "cache_value": "London",
        "project_details": {
            "id": 56000000087108,
            "project_name": "ShipmentTracking"
        },
        "segment_details": {
            "id": 56000000112489,
            "segment_name": "CustomerLocation"
        },
        "expires_in": "Mar 28, 2019 02:03 AM",
        "expiry_in_hours": 7
    }
}

    Error Codes

    When the server encounters an error while processing a client request, it sends an appropriate HTTP Status Code in the response back to the client. The following errors are recognized by Catalyst:


    HTTP Status Code Error Code Description
    403 API_LIMIT_REACHED You have reached the upper limits for API calls in your account. Upgrade your license plan.
    409 CONFLICT Contradicts with the existing value. Try giving another value.
    409 DUPLICATE_ENTRY The email ID you have entered already exists. Please provide a different email ID.
    409 DUPLICATE_ENTRY The domain name already exists. Please provide a different value.
    409 DUPLICATE_OPERATION The requested operation is already under progress. Please wait until it is completed.
    409 DUPLICATE_VALUE The value you have entered already exists. Please provide a different value.
    500 EMAIL_ERROR Email sending process failed. Try again after some time.
    410 EXPIRED The requested resource has expired. Please try creating it again.
    410 EXPIRED_LOG The response log you are trying to download is expired.
    202 FUNCTION_ERROR Encountered an internal server error.
    500 INTERNAL_SERVER_ERROR Encountered an internal server error.
    403 INVALID_CONTENT The given input is not in an acceptable format.
    404 INVALID_ID The resource ID you have provided does not exist.
    400 INVALID_INPUT The table name you have provided does not exist.
    400 INVALID_INPUT The column name you have provided does not exist.
    400 INVALID_INPUT The foreign key you have provided doesn't match with the ROWID of the parent table.
    400 INVALID_INPUT The input you have provided is not valid.
    404 INVALID_NAME The email ID you have provided does not exist.
    404 INVALID_NAME The table name you have provided does not exist.
    403 INVALID_OPERATION The requested operation is invalid.
    405 INVALID_REQUEST_METHOD The requested method is not accepted.
    400 MISMATCH The value provided does not match with the expected one.
    400 MISSING_FUNCTION The function ID you have provided does not exists.
    400 MISSING_VALUE The expected input is missing.
    401 NO_ACCESS You don't have privileges to perform this action
    204 NO_CONTENT_AVAILABLE The request returned an empty response.
    401 UNAUTHORISED You are not authorized to perform this action.
    403 VERIFICATION_NEEDED Your email address needs to be verified.
    400 ZCQL_QUERY_ERROR The format of your query is invalid.
    429 TOO_MANY_REQUESTS Concurrency limits reached for function, web client, or a Catalyst component execution.

    OAuth 2.0 Authentication

    Overview

    OAuth 2.0 is an industry-standard protocol for authentication and authorization. The framework enables a host of third-party client applications to gain secure and delegated access to protected resources in Zoho through APIs.

    Some common characteristics of OAuth 2.0 are:

    • Clients are not required to support password authentication or store user credentials. API calls can be made to access resources without having to provide user credentials for each call.
    • Clients will only have access to resources authenticated by the user.
    • Users can revoke the client’s delegated access at any time.
    • OAuth2.0 access tokens expire after a set time, which provides strong security.

    Terminology

    Before you learn about the steps involved in implementing OAuth 2.0, you must understand the following terms related to OAuth 2.0 in the Catalyst context:


    Key Words Description
    Protected Resource A Catalyst resource such as Cache, Cron, Table, or Folder
    Resource Server The Catalyst server that hosts the Catalyst protected resources
    Client An application that sends requests to the resource server to access the protected resources on behalf of the end-user
    client_id The unique key generated for a registered client
    client_secret The secret value generated for a specific registered client's client_id. When you register your Catalyst application in the Zoho API Console, a client_id and client_secret will be generated for it.
    Authentication Server The Catalyst authorization server that provides the necessary credentials to a client, such as the access_tokenor refresh_token
    Grant Token or code Catalyst authorization server generates a temporary token and sends it to the client via the browser. The client will send this code back to the authorization server to obtain the access and refresh tokens.
    access_token A temporary token that is sent to the resource server to access the protected resources of the user. Clients use the access_token to make requests to the associated application using the APIs. Each access_token will be valid for a set time period and can only be used to perform operations described in the scope.
    refresh_token A token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the end-user.
    Scopes Scopes control the type of resources that the client application can access. Each token is usually created with selected scopes for better security. For example, you can generate an access_token with a scope to only read the data in the Data Store or File Store.The standard format to define a scope is scope=service_name.scope_name.operation_type. The next section lists the scopes available in Catalyst.

    List of Scopes Available in Catalyst


    Scope Name Available Scopes
    projects ZohoCatalyst.projects.READ, ZohoCatalyst.projects.CREATE, ZohoCatalyst.projects.UPDATE, ZohoCatalyst.projects.DELETE, ZohoCatalyst.projects.users.READ, ZohoCatalyst.projects.users.CREATE, ZohoCatalyst.projects.users.DELETE
    tables ZohoCatalyst.tables.READ, ZohoCatalyst.tables.rows.READ, ZohoCatalyst.tables.rows.CREATE, ZohoCatalyst.tables.rows.UPDATE, ZohoCatalyst.tables.rows.DELETE, ZohoCatalyst.tables.columns.READ
    folders ZohoCatalyst.folders.READ, ZohoCatalyst.folders.CREATE, ZohoCatalyst.folders.UPDATE, ZohoCatalyst.folders.DELETE
    files ZohoCatalyst.files.READ, ZohoCatalyst.files.CREATE, ZohoCatalyst.files.DELETE
    cache ZohoCatalyst.cache.READ, ZohoCatalyst.cache.CREATE
    cron ZohoCatalyst.cron.READ, ZohoCatalyst.cron.CREATE, ZohoCatalyst.cron.UPDATE, ZohoCatalyst.cron.DELETE
    zcql ZohoCatalyst.zcql.CREATE
    functions ZohoCatalyst.functions.EXECUTE
    circuits ZohoCatalyst.circuits.EXECUTE
    search ZohoCatalyst.search.READ
    email ZohoCatalyst.email.CREATE
    notifications ZohoCatalyst.notifications.web, ZohoCatalyst.notifications.mobile.register, ZohoCatalyst.notifications.mobile
    mlkit ZohoCatalyst.mlkit.READ
    quickml QuickML.deployment.READ
    smartbrowz ZohoCatalyst.pdfshot.execute, ZohoCatalyst.dataverse.execute

    Step 1: Register a New Client

    Register the Client

    The first step towards obtaining an OAuth authentication token is to register your application with Zoho’s API console and obtain your client_id and client_secret.

    1. To register your application, visit the Zoho API Console and click Get Started.

    2. Select a client type for your application.

      You can refer to Zoho’s OAuth documentation for more details.

    Note: You can choose the Self Client type to test the client-server handling for your application, or if your application does not have a domain. You need not provide any details for this type. You can only create one Self Client client for your user account.

    1. Provide the required details to register your application for the client type you chose.

      • Client Name: The name of your application you want to register with Zoho
      • Homepage URL: The URL of your client’s homepage
      • Authorized Redirect URIs: A valid URL of your application that Zoho Accounts redirects you to with the grant token after a successful authentication

    2. Click Create.

    After the registration is successful, Zoho will provide you a set of OAuth 2.0 credentials: the client_id and client_secret, which are known to both Zoho and your application.


    Note: You must not share the client_id and client_secret anywhere. Ensure that you keep these credentials safe.

    Enable Multi DC for the Client

    As mentioned in the Multi-DC Support section, you can enable multi-DC support for your client from the Settings tab in the API console after you register it. This is available for all client types, except the Self Client type as it is used only for testing.

    This feature lets you provide access to your application to users of a specific domain alone. As mentioned earlier, Catalyst is currently available in the EU, AU, IN, and CA domains. So you can enable or disable access to your application for specific DC users if you need.

    To access the multi-DC configurations for your client:

    1. Open your client from the API console and click Settings.

    2. Enable or disable the client access for the data centers you need. You can only avail the data centers that Catalyst supports.

    When you enable a DC, the console will generate a different client_secret for them by default. You can access it by clicking Show Code for the respective DC. The client_id will remain the same for all DCs.

    You can choose to have the same client_secret for all DCs by checking the Use the same OAuth credentials for all data centers checkbox. You must then click OK in the confirmation pop-up.

    You can again unselect the checkbox to have a different client_secret, and confirm the action similarly.

    Step 2: Generate Grant Token

    After you generate the client_id and client_secret, you must generate a Grant Token or code for your application.

    Note: Generating a Grant Token is a one-time process, provided you generate the access_token and refresh_token within the time the Grant Token is valid for.

    For Self Client Applications

    If you previously selected the Self Client type, you must generate the Grant Token (code) in the following way:

    1. After registering your application, select Self Client from the Applications list in the API console and click Generate Code.

    2. Enter a valid scope. You can check the list of scopes available in Catalyst from this section.

    3. Choose a time duration from the dropdown list. The Grant Token generated in this step will expire after this time period.

    Note: If the Grant Token is about to expire, you must generate a refresh_token before it expires, as described in the next step.
    1. Enter a description for the scope.
    2. Click Generate.

    The API console will display the generated Grant Token or code value for your Self Client application.


    For Other Applications

    If you previously selected client types other than the Self Client type, you must generate the Grant Token using a redirect method:

    1. Send a request to the following URI with the params given below, to generate the Grant Token (code):

    https://accounts.zoho.com/oauth/v2/auth?

    Note: You must access the respective domains for the other data centers:

    • EU: https://accounts.zoho.eu/
    • AU: https://accounts.zoho.au/
    • IN: https://accounts.zoho.in/
    • CA: https://accounts.zohocloud.ca/

    Parameter Description
    scope* The scope the Grant Token is to be generated for. You can provide multiple scopes by separating them using commas. You can check the list of scopes available in Catalyst from [this section](/en/api/oauth2/scopes/#Scopes).
    client_id* The Client ID that was generated during the client registration
    state An opaque string that is round-tripped in the protocol, i.e., whatever value you provide here will be passed back to you
    response_type* code(Provide this literal string as the value)
    redirect_uri* One of the Authorized Redirect URIs you provided while registering the client in the previous step. You must not provide an unregistered redirect URI.
    access_type The allowed values are offline and online. The online access_type only provides the Access Token for your application, which is valid for one hour. The offline access_type provides an Access Token as well as a Refresh Token for your application. The default value is considered to be online.
    prompt Consent (Provide this literal string as the value) Prompts for user consent every time your app tries to access user credentials. If you don't specify this parameter, the user will only be prompted for credentials the first time your app requests access.

    Note:

    • Fields marked with * are mandatory.

    • You can pass the parameters in the body of your request as form-data, for increased security.

    Request Example

        
    
        
    copy
    
        
    
            
    
        
    
    
    
    
    
         https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCatalyst.tables.rows.CREATE,ZohoCatalyst.tables.rows.READ,ZohoCatalyst.tables.rows.UPDATE,ZohoCatalyst.tables.rows.DELETE&client_id=1000.0SRSxxxxxxxxxxxxxxxxx&state=testing&response_type=code&redirect_uri=https://www.zylker.com/ShipmentTracking/&access_type=offline

    1. If you send the prompt parameter in this request, a user consent page will open.
      After you click Accept, Zoho will redirect you to the redirect_uri with the Grant Token in the code parameter. Save the code value for the next steps.

      Based on your login details, the system automatically detects your domain and uses the domain-specific authentication URL to generate the Grant Token. The state parameter is also passed in the URL.
      If you click Reject, the browser redirects to the redirect URI with the parameter error=access_denied.
    Note: This code is only valid for 60 seconds. You must complete the next step within this time.

    Step 3: Generate Access Token and Refresh Token

    Request Execution

    After you obtain the Grant Token, send a POST request to the following URL with the params given below to generate the access_token:

    https://accounts.zoho.com/oauth/v2/token?

    Note: You must access the respective domains for the other data centers:

    • EU: https://accounts.zoho.eu/
    • AU: https://accounts.zoho.au/
    • IN: https://accounts.zoho.in/
    • CA: https://accounts.zohocloud.ca/

    Parameter Description
    code* The Grant Token or the value of code obtained in the previous step.
    client_id* The Client ID that was generated during the client registration
    client_secret* The Client Secret that was generated during the client registration
    grant_type* authorization_code (Provide this literal string as the value)
    redirect_uri One of the Authorized Redirect URIs you provided while registering the client in the previous step. You must not provide an unregistered redirect URI.
    scope The scope the access_token is to be generated for. You can provide multiple scopes by separating them using commas.
    You can check the list of scopes available in Catalyst from [this section](/en/api/oauth2/scopes/).
    state An opaque string that is round-tripped in the protocol. In other words, whatever value you provide here will be passed back to you.

    Note:

    • Fields marked with * are mandatory.
    • You can pass the parameters in the body of your request as form-data, for increased security.
    • The access_token will expire after the time period (in seconds) mentioned in the expires_in parameter.
    • However, the refresh_token is permanent and can be used to regenerate a new access_token if the current one expires.
    • You can use the domain specified in api_domain in your requests to make API calls to Catalyst.
    • The “Bearer” value in the token_type indicates this is an access_token.

    This completes the authentication process. Once you obtain the access_token for your application, you can use it in the authorization header of your HTTP requests to access Catalyst APIs. You can refer to the Request Format section for an example.

    Note: Each time a re-consent page is accepted, a new refresh_token is generated. You can generate a maximum of 20 refresh tokens per user, and 5 refresh tokens in a minute. If this limit is crossed, the first refresh_token is automatically deleted to accommodate the latest one. This is done irrespective of whether the first one is in use or not.
        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "access_token": "{access_token}",
    "refresh_token": "{refresh_token}",
    "api_domain": "https://www.zohoapis.com",
    "token_type": "Bearer",
    "expires_in": 3600
}

    Step 4: Refresh Access Token

    Request Execution

    When an access_token expires, you must use the refresh_token to generate a new access_token for your application.

    To do so, send a POST request to the following URL with the params given below:

    https://accounts.zoho.com/oauth/v2/token?


    Note: You must access the respective domains for the other data centers:

    • EU: https://accounts.zoho.eu/
    • AU: https://accounts.zoho.au/
    • IN: https://accounts.zoho.in/
    • CA: https://accounts.zohocloud.ca/

    Parameter Description
    refresh_token* The refresh_token obtained in the previous step
    client_id* The Client ID that was generated during the client registration
    client_secret* The Client Secret that was generated during the client registration
    grant_type* refresh_token (Provide this literal string as the value)
    redirect_uri* One of the Authorized Redirect URIs you provided while registering the client in the previous step. You must not provide an unregistered redirect URI.
    Note: Fields marked with * are mandatory.
        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "access_token": "{new_access_token}",
    "expires_in": 3600,
    "api_domain": "https://www.zohoapis.com",
    "token_type": "Bearer"
}

    Catalyst Projects

    The Project APIs enable you to create, update, delete, and obtain details of a Catalyst project. You can perform these actions from the Catalyst console as well. Catalyst CLI also enables you to create a project remotely and initialize resources in it.

    Create a New Project

    Description

    This API enables you to create a new Catalyst project in your Catalyst account. You must pass the required project name in the request.

    Note: You can create upto 50 projects in your account in the development environment. You can request Catalyst for an increase in this limit by contacting our support at support@zohocatalyst.com. We will address each request on a case-by-case basis. There are no upper limits for project creation in the production environment.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZOHOCATALYST.projects.CREATE

    Request JSON Properties

    project_name string
    mandatory
    Unique name of the project
    Max Size: 50 characters

    Response Details

    The response will contain the details of the project that was created including the project domain details such as the project_domain_id and project_domain_name, and the details of the user such as their email_id and user_id.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: application/json” 
    
-d ‘{
“project_name”:“BillingDesk”
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "project_name": "BillingDesk",
        "created_by": {
            "zuid": 3000000006001,
            "is_confirmed": true,
            "email_id": "amelia.burrows@zylker.com",
            "first_name": "Amelia",
            "last_name": "Burrows",
            "user_id": 671930455
        },
        "created_time": "Jan 29, 2020 11:59 AM",
        "redirect_url": "",
        "project_domain_details": {
            "project_domain_id": 10018095112,
            "project_domain_name": "billingdesk-697215025.development",
            "project_domain": "billingdesk-697215025.development.zohocatalyst.com",
            "user_auth": {},
            "mobile_auth": {}
        },
        "db_type": "SINGLE_DB",
        "id": 3000000005090,
        "project_type": "Live",
        "timezone": "Asia/Kolkata"
    }
}

    Step 5: Revoke Refresh Token

    Request Execution

    You may choose to manually revoke a refresh_token, when you no longer need access for a particular scope.

    To revoke a refresh_token, send a POST request to the following URL with the refresh_token to be revoked as a parameter.

    https://accounts.zoho.com/oauth/v2/token/revoke?

    Note: You must access the respective domains for the other data centers:

    • EU: https://accounts.zoho.eu/
    • AU: https://accounts.zoho.au/
    • IN: https://accounts.zoho.in/
    • CA: https://accounts.zohocloud.ca/

    Your refresh token now will become invalid.

        
    
        
    Sample Request
    
        
    
            
    copy

    Get the Details of a Specific Project

    Description

    This API enables you to fetch the details of a specific project that the Catalyst user, such as the developer or a collaborator, logged in currently has created from their Catalyst account. The project is referred to by its project_id. The project details fetched are of the same Catalyst account the API is being executed from.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    scope=ZOHOCATALYST.projects.Read

    Response Details

    The response will contain the details of the project including the project domain details such as the project_domain_id and project_domain_name, and the details of the user that created it, such as their email_id and user_id.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "platforms": [],
    "project_name": "BillingDesk",
    "created_by": {
        "zuid": 780776954,
        "is_confirmed": false,
        "email_id": "amelia-burrows@zylker.com",
        "first_name": "Amelia",
        "last_name": "Burrows",
        "user_type": "Admin",
        "user_id": 11811000000003003
    },
    "created_time": "Jun 04, 2023 04:19 PM",
    "redirect_url": "",
    "project_domain_details": {
        "project_domain_id": 10060895541,
        "project_domain_name": "billingdesk-781316834.development",
        "project_domain": "https://billingdesk-781316834.development.catalystserverless.com",
        "user_auth": {
            "userAuth": {},
            "createdTime": null,
            "createdBy": null
        },
        "mobile_auth": {}
    },
    "db_type": "SINGLE_DB",
    "id": 11811000000315013,
    "project_type": "Live",
    "env_details": [
        {
            "id": 11811000000315049,
            "env_name": "Development",
            "env_type": 3,
            "env_status": "Active",
            "project_details": {
                "project_name": "BillingDesk",
                "id": 11811000000315013,
                "project_type": "Live"
            },
            "is_default": true,
            "env_zgid": "781316834",
            "action_required": false
        }
    ],
    "timezone": "Asia/Kolkata"
}

    

    }
    
    
         
    View more

    Get the Details of All Projects

    Description

    This API enables you to fetch the details of all the projects in the remote console of the Catalyst user, such as the developer or a collaborator, logged in currently. The project details fetched are of the same Catalyst account the API is being executed from.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZOHOCATALYST.projects.Read

    Response Details

    The response will contain the details of all the projects the user created in their remote console, including the project domain details such as the project_domain_id and project_domain_name, and the details of the user that created it, such as their email_id and user_id of each project.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": [
    {
        "platforms": [],
        "project_name": "BillingDesk",
        "created_by": {
            "zuid": 780776954,
            "is_confirmed": false,
            "email_id": "amelia.burrows@zylker.com",
            "first_name": "Amelia",
            "last_name": "Burrows",
            "user_type": "Admin",
            "user_id": 11811000000003003
        },
        "created_time": "Jun 04, 2023 04:19 PM",
        "redirect_url": "",
        "project_domain_details": {
            "project_domain_id": 10060895541,
            "project_domain_name": "billingdesk-781316834.development",
            "project_domain": "https://billingdesk-781316834.development.catalystserverless.com",
            "user_auth": {
                "userAuth": {},
                "createdTime": null,
                "createdBy": null
            },
            "mobile_auth": {}
        },
        "db_type": "SINGLE_DB",
        "id": 11811000000315013,
        "project_type": "Live",
        "env_details": [
            {
                "id": 11811000000315049,
                "env_name": "Development",
                "env_type": 3,
                "env_status": "Active",
                "project_details": {
                    "project_name": "BillingDesk",
                    "id": 11811000000315013,
                    "project_type": "Live"
                },
                "is_default": true,
                "env_zgid": "781316834",
                "action_required": false
            }
        ],
        "timezone": "Asia/Kolkata"
    },
    {
        "platforms": [],
        "project_name": "Zia",
        "created_by": {
            "zuid": 780776954,
            "is_confirmed": false,
            "email_id": "amelia.burrows@zylker.com",
            "first_name": "Amelia",
            "last_name": "Burrows",
            "user_type": "Admin",
            "user_id": 11811000000003003
        },
        "created_time": "Jun 02, 2023 11:55 AM",
        "redirect_url": "",
        "project_domain_details": {
            "project_domain_id": 10060816047,
            "project_domain_name": "zia-781316834.development",
            "project_domain": "https://zia-781316834.development.catalystserverless.com",
            "user_auth": {
                "userAuth": {},
                "createdTime": null,
                "createdBy": null
            },
            "mobile_auth": {}
        },
        "db_type": "SINGLE_DB",
        "id": 11811000000314001,
        "project_type": "Live",
        "env_details": [
            {
                "id": 11811000000314037,
                "env_name": "Development",
                "env_type": 3,
                "env_status": "Active",
                "project_details": {
                    "project_name": "Zia",
                    "id": 11811000000314001,
                    "project_type": "Live"
                },
                "is_default": true,
                "env_zgid": "781316834",
                "action_required": false
            }
        ],
        "timezone": "Asia/Kolkata"
    }
    
    
         
    View more

    Delete Project

    Description

    This API enables you to delete a particular project, by referring to its Project ID.

    Request Details

    Request URL

    DELETE

    {api-domain}/baas/v1/project/{project_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZOHOCATALYST.projects.Delete

    Request JSON Properties

    project_name string
    mandatory
    New unique name of the project
    Max Size: 50 characters
        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X DELETE 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: application/json” \
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "id": 4000000006007
    }
}

    Functions

    Catalyst Functions enable you to build custom functionalities in your application, and seamlessly integrate it with other Catalyst components to provide a powerful backend for it. You can automate tasks, perform memory-intensive computations, or integrate with third-party services using functions.

    Catalyst offers support to develop server-side functions in Java, Node.js and Python programming environments.

    Note: You can create six types of functions in Catalyst: Basic I/O, Advanced I/O, Cron, Event, Integration, and Browser Logic functions. However, you can only execute Basic I/O functions using this API.

    Execute a Function

    Description

    This API enables you to execute a Basic I/O function by referring to its unique function ID. Basic I/O functions are used to perform basic input and output operations, computations, and simple HTTP operations.

    Input parameters can passed to the function in the API request either as a query string or in the request body. A query string is preferred over the request body to pass the function parameters in. The response will contain the function output.

    Note: The function must already be available in the remote console. You can create a function in the console directly, or create it in your local system and deploy it to the console.

    Request Details

    Request URL

    MULTIPLE

    {api-domain}/baas/v1/project/{project_id}/function/{function_id}/execute

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    function_id
    Numerical
    The unique ID of the function

    Request Methods

    GET
    POST
    PUT
    DELETE

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.functions.EXECUTE

    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.

    Response Details

    The response contains the output of the processed function. A Basic I/O function returns response in the JSON format. The key output contains the output generated by the function you execute.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/function/4000000045004/execute?name=Raymond%20McGregor 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"output": "Hello Raymond McGregor"
}

    SDK Documentation
    Execute a Function- Java SDK

    Execute a Function- Node.js SDK

    Execute a Function- Python SDK

    Execute a Function- Web SDK

    Circuits

    Catalyst Circuits enable you to systematically define and organize a sequence of tasks to be carried out automatically in Catalyst. You can orchestrate tasks and automate workflows, and additionally include conditions, data, and paths in the workflow, to define a repeatable pattern of activities that achieves a business outcome using Circuits.

    Catalyst offers support for automating the execution of Basic I/O functions of your application using a circuit.

    Note: Circuits is currently not available to Catalyst users accessing from the EU, AU, IN, or CA data centers.

    Execute a Circuit

    Description

    This API enables you to execute a Catalyst circuit configured in the console by referring to its unique Circuit ID. You can pass the input to the circuit in the request JSON as described below.

    Note: You can create, configure, and test a circuit from the Catalyst console.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/circuit/{circuit_id}/execute

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    circuit_id
    Numerical
    The unique ID of the circuit

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.circuits.EXECUTE

    Request JSON Format

    You must send the input to the circuit as key-value pairs in the JSON format like this:

        
    
        
    copy
    
        
    
            
    
        
    
    
    
    
    
         
    {
“key_1”: “value_1”,
“key_2”: “value_2”,
“key_3”: “value_3”,
.
.
}
    Note: The circuit input is not mandatory. You can skip the input or pass it based on your circuit’s purpose and logic.

    Response Details

    The response contains the result and the details of the executed circuit, such as the circuit_name, the start_time and end_time of the execution, the instance_id, along with the details of the input that was passed to the circuit and the output generated from the circuit’s execution.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/circuit/105000000180234/execute 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-d ‘[
{
“email”:“j.parker@zylker.com”,
“count”:“20”,
“traveller_type”:“Single”,
“rating”:“5”,
“location”:“New York”,
“suite”:“Executive”
}
]’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "id": "b3c91799-5c18-4626-9983-a2d6af237e20",
        "name": "Case 1",
        "start_time": "Aug 24, 2020 02:24 PM",
        "end_time": "Aug 24, 2020 02:24 PM",
        "status": "success",
        "status_code": 6,
        "execution_meta": {},
        "circuit_details": {
            "name": "StayFinder",
            "ref_name": "StayFinder",
            "description": "",
            "instance_id": "ef9644a5-123a-438c-94d9-01b1bade8817"
        },
        "input": {
            "email":"j.parker@zylker.com",
            "count":"20",
            "traveller_type":"Single", 
            "rating":"5",
            "location":"New York",
            "suite":"Executive"
        },
        "output": {
            "result": {
                "stay_list":{
                    "message":"Email has been sent successfully to j.parker@zylker.com",
                    "status":"success"
                }
            }    
        }
    }
}

    SDK Documentation
    Execute a Circuit- Java SDK

    Execute a Circuit- Node.js SDK

    Execute a Circuit- Python SDK

    Authentication

    Catalyst Authentication features enable you to add end-users to your Catalyst serverless applications, configure their user accounts and roles, and manage user sign-in and authentication of your application.

    Add a New User

    Description

    This API enables you to add a new end-user to the Catalyst application for a specific platform. When the user has signed up, unique identification values such as ZUID, userID are created for them.

    Note: You will be able to add only 25 users in your application in the development environment. After you deploy your application to production, you can include any number of end-users in it.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/project-user/signup

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.projects.users.CREATE


    Note: Passing the role_id of the role that the user must be assigned to, is optional. If you pass the role_id in the API, authentication becomes mandatory. If you skip passing the role_id, Catalyst does not authenticate the request and you need not specify the scope.

    Request JSON Properties

    platform_type string
    mandatory
    Accepted values: web, android, ios
    redirect_url string
    optional
    The URL to be redirected to, after the user signs up for the application
    Max Size: 200
    user_details json
    mandatory

    The JSON that contains the details of the user

    first_name string
    mandatory
    First name of the user
    Max Size: 100
    last_name string
    optional
    Last name of the user
    Max Size: 100
    email_id string
    mandatory
    Email address of the user
    role_id string
    optional
    Unique identification of the role the user must be assigned to

    Response Details

    The response will contain the details of the user added in the data key, including the metadata and identification values such as zaid, user_id, and org_id that were generated.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/3000000002001/project-user/signup 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: application/json” 
    
-H “PROJECT_ID: 1010309726” 
    
-d ‘{
“user_details”:{
“first_name”:“Rowena”,
“last_name”:“Simmons”,
“email_id”:“r.simmons@zylker.com”,
“role_id”:“1256000000288012”
    
},
“platform_type”:“web”,
“redirect_url”:“https://logistics.zylker.com/app/index.html"
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "zaid": 1010309726,
        "user_details": {
            "user_id": 671930455,
            "user_type": "App Administrator",
            "zuid": 3000000006001,
            "zaaid": 1011520995,
            "status": "ACTIVE",
            "is_confirmed": true,
            "email_id": "r.simmons@zylker.com",
            "first_name": "Rowena",
            "last_name": "Simmons",
            "created_time": "May 13, 2019 09:16 PM",
            "modified_time": "May 13, 2019 09:16 PM",
            "invited_time": "May 13, 2019 09:16 PM",
            "role_details": {
                "role_id": 1256000000288012,
                "role_name": "App Administrator"
            }
        },
        "redirect_url": "https://logistics.zylker.com/app/index.html",
        "platform_type": "web",
        "org_id": 1011520995
        "locale": "us|en_us|America/Los_Angeles"
        "time_zone": "America/Los_Angeles"
    }
}

    SDK Documentation
    Add New User- Java SDK

    Add New User- Node.js SDK

    Add New User- Python SDK

    Add New User- Web SDK

    Add a New User to an Exsiting Organization

    Description

    This API enables you to add a new end-user to an existing organization without creating a new organization for them. This can be done by providing the ZAAID of the organization that the user must be added to. The organization of a user cannot be changed later, once it is associated with their account.

    When the user has signed up, unique identification values such as ZUID and User ID are created for them.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/project-user

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.projects.users.CREATE

    Request JSON Properties

    platform_type string
    mandatory
    Accepted values: web, android, ios
    redirect_url string
    optional
    The URL to be redirected to, after the user signs up for the application
    Max Size: 200
    user_details json
    mandatory

    The JSON that contains the details of the user

    first_name string
    optional
    First name of the user
    Max Size: 100
    last_name string
    mandatory
    Last name of the user
    Max Size: 100
    email_id string
    mandatory
    Email address of the user
    ZAAID string
    mandatory
    Unique identification of the organization that the user belongs to

    Response Details

    The response will contain the details of the user added in the data key, including the metadata and identification values such as zaid, user_id, and org_id that were generated.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/3000000002001/project-user 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: application/json” 
    
-d ‘{
“user_details”:{
“first_name”:“John”,
“last_name”:“Winchester”,
“email_id”:“john.w@zylker.com”,
“zaaid”:4567899
},
“redirect_url”: “https://logistics.zylker.com/app/index.html",
“platform_type”:“web”
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "zaid": 1011481670,
        "user_details": {
            "user_id": 671930400,
            "user_type": "App User",
            "zuid": 3000000006001,
            "zaaid": 1011520995,
            "status": "ACTIVE",
            "is_confirmed": true,
            "email_id": "john.w@zylker.com",
            "first_name": "John",
            "last_name": "Winchester",
            "created_time": "May 13, 2019 09:16 PM",
            "modified_time": "May 13, 2019 09:16 PM",
            "invited_time": "May 13, 2019 09:16 PM",
            "role_id": 3000000005015
        },
        "redirect_url": "https://logistics.zylker.com/app/index.html",
        "platform_type": "web",
        "org_id": 1011520995
        "locale": "us|en_us|America/Los_Angeles"
        "time_zone": "America/Los_Angeles"
    }
}

    SDK Documentation
    Add New User to Existing Org- Java SDK

    Add New User to Existing Org- Node.js SDK

    Add New User to Existing Org- Python SDK

    Get the Details of the Current User

    Description

    This API enables you to fetch the details of the current user logged into the Catalyst application, on whose scope the function is being executed.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/project-user/current

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}


    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.projects.users.READ


    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. However, the user can only obtain their own user details. Refer to the Catalyst API Prerequisites section for details.

    Response Details

    The response will contain the details of the current user including their identification values such as zaid, user_id, email_id, and their role details.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/3000000005007/project-user/current 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************6.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "zuid": 3000000006111,
        "zaaid": 1019540153,
        "status": "ACTIVE",
        "user_id": 671930409,
        "user_type": "App Administrator",
        "is_confirmed": true,
        "email_id": "p.boyle@zylker.com",
        "first_name": "Patricia",
        "last_name": "Boyle",
        "created_time": "Jul 09, 2019 04:11 PM",
        "modified_time": "Jul 09, 2019 04:11 PM",
        "invited_time": "Jul 09, 2019 04:11 PM",
        "role_details": {
            "role_id": 3000000005090,
            "role_name": "App Administrator"
        }
        "org_id":1019540153
        "locale": "us|en_us|America/Los_Angeles"
        "time_zone": "America/Los_Angeles"
    }
}

    SDK Documentation
    Get User Details- Java SDK

    Get User Details- Node.js SDK

    Get User Details- Python SDK

    Get User Details- Web SDK

    Get the Details of a Specific User

    Description

    This API enables you to obtain the details of a specific Catalyst application user, by passing their user_ID in the request.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/project-user/{user_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    user_id
    Numerical
    The unique ID of the user

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.projects.users.READ

    Response Details

    The response will contain the details of the specific user including their identification values such as zuid, user_id, email_id, and their role details.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/3000000005007/project-user/671930409 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "zuid": 3171930400,
        "zaaid": 1019540153,
        "status": "ACTIVE",
        "user_id": 671930409,
        "user_type": "App User",
        "is_confirmed": true,
        "email_id": "john.w@zylker.com",
        "first_name": "John",
        "last_name": "Winchester",
        "created_time": "Jul 09, 2019 04:11 PM",
        "modified_time": "Jul 09, 2019 04:11 PM",
        "invited_time": "Jul 09, 2019 04:11 PM",
        "role_details": {
            "role_id": 3000000005015,
            "role_name": "App User"
        }
        "org_id":1019540153
        "locale": "us|en_us|America/Los_Angeles"
        "time_zone": "America/Los_Angeles"
    }
}

    SDK Documentation
    Get User Details- Java SDK

    Get User Details- Node.js SDK

    Get User Details- Python SDK

    Get User Details- Web SDK

    Get the Details of All Users

    Description

    This API enables you to fetch the details of all Catalyst applications users of a particular application through Pagination. Pagination allows you to retrieve the user list in pages through an iteration of API calls.

    For example, if you require user records to be fetched in batches of 200 as individual pages, you must include a start and an end parameter in your request. You can set the start index as 0 using the start parameter, and specify the maximum number of users to be fetched as 200 using the end parameter. To fetch the next set of user records, you can execute another API call by setting the start index as 200, and specifying the number of user records in that page using the end parameter accordingly.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/project-user?start={start_index}&end={number_of_users}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    start
    Numerical

    The start index to fetch the user records from

    end
    Numerical

    Number of user records to return in a single page through pagination

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.projects.users.READ

    Response Details

    The response will contain the details of all application users including their identification values such as zuid, user_id, email_id, and their role details.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/3000000005007/project-user?start=100&end=3 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": [
        {
            "zuid": 3171930121,
            "zaaid": 1019540153,
            "status": "ACTIVE",
            "user_id": 671930409,
            "user_type": "App User",
            "is_confirmed": true,
            "email_id": "ron.grisham@zylker.com",
            "first_name": "Ronald",
            "last_name": "Grisham",
            "created_time": "Jul 09, 2019 04:11 PM",
            "modified_time": "Jul 09, 2019 04:11 PM",
            "invited_time": "Jul 09, 2019 04:11 PM",
            "role_details": {
                "role_id": 3000000005015,
                "role_name": "App User"
            }
            "org_id":1019540153
            "locale": "us|en_us|America/Los_Angeles"
            "time_zone": "America/Los_Angeles"
        },
        {
            "zuid": 3171930089,
            "zaaid": 1019543293,
            "status": "ACTIVE",
            "user_id": 671930121,
            "user_type": "App User",
            "is_confirmed": true,
            "email_id": "Lucy.p@zylker.com",
            "first_name": "Lucy",
            "last_name": "Pettigrew",
            "created_time": "Jul 09, 2019 04:26 PM",
            "modified_time": "Jul 09, 2019 04:26 PM",
            "invited_time": "Jul 09, 2019 04:26 PM",
            "role_details": {
                "role_id": 3000000005015,
                "role_name": "App User"
            }
            "org_id":1019540153
            "locale": "us|en_us|America/Los_Angeles"
            "time_zone": "America/Los_Angeles"
        },
        {
            "zuid": 3171937685,
            "zaaid": 1019540091,
            "status": "ACTIVE",
            "user_id": 671930888,
            "user_type": "App User",
            "is_confirmed": true,
            "email_id": "zayn.ahmed@zylker.com",
            "first_name": "Zayn",
            "last_name": "Ahmed",
            "created_time": "Jul 09, 2019 04:26 PM",
            "modified_time": "Jul 09, 2019 04:26 PM",
            "invited_time": "Jul 09, 2019 04:26 PM",
            "role_details": {
                "role_id": 3000000005015,
                "role_name": "App User"
            }
            "org_id":1019540153
            "locale": "us|en_us|America/Los_Angeles"
            "time_zone": "America/Los_Angeles"
        }
    ]
}
    
    
         
    View more

    SDK Documentation
    Get User Details- Java SDK

    Get User Details- Node.js SDK

    Get User Details- Python SDK

    Get User Details- Web SDK

    Delete User

    Description

    This API enables you to delete a user and completely remove their access to your Catalyst application.

    Request Details

    Request URL

    DELETE

    {api-domain}/baas/v1/project/{project_id}/project-user/{user_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    user_id
    Numerical
    The unique User ID of the user generated by Catalyst

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}


    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.projects.users.DELETE


    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. However, the user can only obtain their own user details. Refer to the Catalyst API Prerequisites section for details.

    Response Details

    The response will contain the details of the deleted user including their identification values such as zaid, user_id, email_id, and their role details.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X DELETE 
    
https://api.catalyst.zoho.com/baas/v1/project/3000000005007/project-user/671930409 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************6.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "zuid": 3000000006111,
        "zaaid": 1019540153,
        "status": "ACTIVE",
        "user_id": 671930409,
        "user_type": "App Administrator",
        "is_confirmed": true,
        "email_id": "p.boyle@zylker.com",
        "first_name": "Patricia",
        "last_name": "Boyle",
        "created_time": "Jul 09, 2019 04:11 PM",
        "modified_time": "Jul 09, 2019 04:11 PM",
        "invited_time": "Jul 09, 2019 04:11 PM",
        "role_details": {
            "role_id": 3000000005090,
            "role_name": "App Administrator"
        }
        "org_id":1019540153
        "locale": "us|en_us|America/Los_Angeles"
        "time_zone": "America/Los_Angeles"
    }
}

    SDK Documentation
    Delete User - Java SDK

    Delete User - Node.js SDK

    Delete User - Python SDK

    Reset User Password

    Description

    This API enables you to reset the password of a user of your Catalyst application. When this API is called, an email will be sent to the user’s email address with a password reset link. The user can configure a new password for your application and save it, upon clicking the link.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/project-user/forgotpassword

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Content-Type: application/json
    PROJECT_ID: {project_id}


    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Note: Catalyst does not authenticate this API request. Therefore, you need not pass an OAuth token or specify any scopes.

    Request JSON Properties

    platform_type string
    mandatory
    Accepted values: web, android, ios
    Max Size: N/A
    redirect_url string
    optional
    The URL to be redirected to, after the user resets the password
    Max Size: 200
    user_details json
    mandatory

    The JSON that contains the details of the user

    first_name
    String
    First name of the user
    Mandatory: No
    Max Size: 100
    last_name
    String
    Last name of the user
    Mandatory: No
    Max Size: 100
    email_id
    String
    Email address of the user
    Mandatory: Yes
    Max Size: N/A

    Response Details

    The response will contain the status of the reset password action.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/3000000002001/project-user/forgotpassword 
    
-H “Content-Type: application/json” 
    
-H “PROJECT_ID: 1010309726” 
    
-d ‘{
“user_details”:{
“email_id”:“p.boyle@zylker.com”
},
“platform_type”:“web”
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": "Reset link sent to your p.boyle@zylker.com email address. Please check your email :)"
}

    SDK Documentation
    Reset User Password- Java SDK

    Reset User Password- Node.js SDK

    Reset User Password- Python SDK

    Reset User Password- Web SDK

    Sign Out User

    Description

    A Catalyst application user can log out from their current active session in the application using this API request. Catalyst will not send any response back for this API request.

    Request Details

    Request URL

    GET

    {application_domain}/baas/logout?logout=true&PROJECT_ID={project_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    application_domain
    String

    The domain address of the Catalyst application


    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Note: Catalyst does not authenticate this API request. Therefore, you need not pass an OAuth token or specify any scopes.
        
    
        
    Sample Request
    
        
    
            
    copy

    SDK Documentation
    Sign Out User- Web SDK

    Data Store

    Catalyst Data Store is a cloud-based relational database management system which stores the persistent data of your application in the form of tables.

    Data Store APIs enable you to insert and manage records in the tables of your project’s Data Store, obtain table and column details, and even perform bulk read and bulk write actions. However, you can create a table and its schema only from the Catalyst console.

    Insert a New Row In a Table

    Description

    This API enables you to insert a new row of data or a record in a table in the Data Store, by referring to the table’s unique ID or name.

    You must pass the column names and their corresponding values for the record in a JSON array in the request as described below.

    Note:

    • The table and the columns in it must already be created. You can create a table and the columns for it from the console.

    • You will be able to insert upto 5000 records in each table per project in the development environment. You can create upto 25,000 records overall in each project in the development environment. There are no upper limits for record creation in the production environment.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/table/{tableIdentifier}/row

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    tableIdentifier
    Numerical
    The unique ID of the table or table name

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.rows.CREATE

    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.

    Request JSON Array

    You must send the column names and their corresponding values in a JSON array like this:

        
    
        
    copy
    
        
    
            
    
        
    
    
    
    
    
         
    {
    "column1_name": "column1_value",
    "column2_name": "column2_value",
    "column3_name": "column3_value",
    .
    .
}

    where column_name is the name of a unique column in the table, and column_value is its corresponding value in the record.


    Note: You must send at least one column name and value pair to insert in the record.

    Response Details

    The response will contain the metadata of the row that was created such as its ROWID and CREATEDTIME, and the column key names and values that were inserted.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST \
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/table/EmpDetails/row  
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type:application/json” 
    
-d ‘[
{
“Department_ID”:“IT678”,
“Department_Name”:“Marketing”,
“Employee_Name”:“Robert Page”
}
]’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": [
    {
        "CREATORID": "12096000000003003",
        "MODIFIEDTIME": "2023-06-05 11:35:14:332",
        "Department_ID": null,
        "Employee_Name": "Robert Page",
        "Department_Name": "Marketing",
        "CREATEDTIME": "2023-06-05 11:35:14:332",
        "ROWID": 12096000000642928
    }
]

    

    }

    SDK Documentation
    Insert Rows- Java SDK

    Insert Rows- Node.js SDK

    Insert Rows- Python SDK

    Insert Rows- Web SDK

    Get All Rows In a Table

    Description

    This API enables you to fetch all the rows from a particular table in the Data Store. You can refer to the table by its ID or name. The API incorporates pagination for fetching all rows. Pagination allows you to retrieve the records in pages through an iteration of API calls.

    For example, if you require the rows to be fetched in batches of 100 as individual pages, you must include a max_rows parameter in your request, that specifies the maximum rows to be fetched in each page as 100.

    Additionally, every API response will contain a token that you can pass in the next API call, to fetch the next page of rows. This token authorizes the subsequent fetching of data. You must pass the token string obtained in the response of the previous API call through the next_token parameter in the request. You need not pass the next_token parameter for the first API call. You can execute an API call for each iteration in this manner and fetch all rows in pages.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/table/{tableIdentifier}/row?next_token={token_string}&max_rows={number_of_rows}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    tableIdentifier
    Numerical
    The unique ID of the table or table name
    next_token
    Numerical

    (not required for the first API call) The token value obtained from the previous API call to be passed for fetching the next set of rows through pagination

    max_rows
    Numerical

    (optional) The maximum number of rows that must be returned in a single page through pagination. The API will return 200 rows in a single page by default if this value is not specified.

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.rows.READ

    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.

    Response Details

    The response will return the rows that are fetched through the API call in pages based on the max_rows value you specify. If there are rows available more than the requested count or the max_rows count, the response will also contain the token that you must pass to fetch the next set of rows as next_token. If there are no more records to be fetched, the response will not contain a token.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/table/CustomerDetails/row?max_rows=4&next_token=*************  
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response (If more records available)
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": [
    {
            "CREATORID": 56000000002003,
            "MODIFIEDTIME": "2019-03-06 10:16:41",
            "Department_ID": "IT148",
            "Department_Name": "Admin",
            "Employee_Name": "Eric Hyde",
            "CREATEDTIME": "2019-03-06 10:16:41",
            "ROWID": 56000000342025,
            "doubleDataType": null
        },
        {
            "CREATORID": 56000000002003,
            "MODIFIEDTIME": "2019-03-06 10:18:56",
            "Department_ID": "IT170",
            "Department_Name": "Sales",
            "Employee_Name": "Steven Kelso",
            "CREATEDTIME": "2019-03-06 10:18:56",
            "ROWID": 56000000342026,
            "doubleDataType": null
        },
    {
            "CREATORID": 56000000002003,
            "MODIFIEDTIME": "2019-03-06 10:19:00",
            "Department_ID": "IT190",
            "Department_Name": "Marketing",
            "Employee_Name": "Micheal Forman",
            "CREATEDTIME": "2019-03-06 10:18:58",
            "ROWID": 56000000342027,
            "doubleDataType": null
        },
    {
            "CREATORID": 56000000002003,
            "MODIFIEDTIME": "2019-03-06 10:45:11",
            "Department_ID": "IT111",
            "Department_Name": "Support",
            "Employee_Name": "Madeline Burkhart",
            "CREATEDTIME": "2019-03-06 10:18:34",
            "ROWID": 56000000342028,
            "doubleDataType": null
        },
    ],
"more_records" : true,
"next_token" : "{{token}}"
}
    
    
         
    View more
    
    
    

        
    
        
    Sample Response (If no more records available)
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": [
    {
            "CREATORID": 56000000002003,
            "MODIFIEDTIME": "2019-03-06 10:16:41",
            "Department_ID": "IT148",
            "Department_Name": "Admin",
            "Employee_Name": "Eric Hyde",
            "CREATEDTIME": "2019-03-06 10:16:41",
            "ROWID": 56000000342025,
            "doubleDataType": null
        },
        {
            "CREATORID": 56000000002003,
            "MODIFIEDTIME": "2019-03-06 10:18:56",
            "Department_ID": "IT170",
            "Department_Name": "Sales",
            "Employee_Name": "Steven Kelso",
            "CREATEDTIME": "2019-03-06 10:18:56",
            "ROWID": 56000000342026,
            "doubleDataType": null
        },
    {
            "CREATORID": 56000000002003,
            "MODIFIEDTIME": "2019-03-06 10:19:00",
            "Department_ID": "IT190",
            "Department_Name": "Marketing",
            "Employee_Name": "Micheal Forman",
            "CREATEDTIME": "2019-03-06 10:18:58",
            "ROWID": 56000000342027,
            "doubleDataType": null
        },
    {
            "CREATORID": 56000000002003,
            "MODIFIEDTIME": "2019-03-06 10:45:11",
            "Department_ID": "IT111",
            "Department_Name": "Support",
            "Employee_Name": "Madeline Burkhart",
            "CREATEDTIME": "2019-03-06 10:18:34",
            "ROWID": 56000000342028,
            "doubleDataType": null
        },
    ],
"more_records" : false
}
    
    
         
    View more

    SDK Documentation
    Get Rows- Java SDK

    Get Rows- Node.js SDK

    Get Rows- Python SDK

    Get Rows- Web SDK

    Update a Row in a Table

    Description

    This API enables you to update a particular row in a table in the Catalyst Data Store, by referring to its table ID or the table name. You must send the data to be updated in the record in the request JSON as described below.

    Request Details

    Request URL

    PUT

    {api-domain}/baas/v1/project/{project_id}/table/{tableIdentifier}/row

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    tableIdentifier
    Numerical
    The unique ID of the table or table name

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.rows.UPDATE

    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.

    Request JSON Format

    You must send the names of the columns and their corresponding values to be updated in the request, along with the ROWID of the record, as a JSON Array like this:

        
    
        
    copy
    
        
    
            
    
        
    
    
    
    
    
         
    {
“column1_name”: “column1_value”,
“column2_name”: “column2_value”,
“column3_name”: “column3_value”,
.
.
“ROWID”:{row_id of the record}
}

    Request JSON Properties

    column_name string
    mandatory
    Specifies the column name of the specified table
    column_value string
    mandatory
    Specifies the value for the column
    ROWID bigint
    mandatory
    The ROWID of the record to be updated

    Response Details

    The response will contain the metadata of the row that was updated such as its ROWID and CREATEDTIME, and the updated column key names and values.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X PUT 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/table/EmpDetails/row 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type:application/json” 
    
-d ‘[
{
“Department_Name”:“Finance”,
“Employee_Name”:“Morgan Jones”,
“ROWID”:3376000000170191
}
]’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": [
        {
            "CREATORID": 3376000000002099,
            "MODIFIEDTIME": "2019-02-26 11:18:49",
            "Department_ID":"IT245",
            "Department_Name":"Finance",
            "Employee_Name": "Morgan Jones",
            "CREATEDTIME": "2019-02-26 11:18:49",
            "ROWID": 3376000000170191
        }
    ]
}

    SDK Documentation
    Update Rows- Java SDK

    Update Rows- Node.js SDK

    Update Rows- Python SDK

    Update Rows- Web SDK

    Delete a Row in a Table

    Description

    This API enables you to delete a particular record or a row of a table in the Data Store, by referring to the table’s unique ID or name. The row is referred by its ROWID.

    Request Details

    Request URL

    DELETE

    {api-domain}/baas/v1/project/{project_id}/table/{tableIdentifier}/row/{row_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    tableIdentifier
    Numerical
    The unique ID of the table or table name
    row_id
    Numerical
    The unique ID of the row

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.rows.DELETE

    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.

    Response Details

    The response will contain the metadata of the row that was deleted such as its ROWID and CREATEDTIME, and the column key names and values in the row.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X DELETE 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/table/EmpDetails/row/3376000000171021  
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "CREATORID": 56000000002003,
        "MODIFIEDTIME": "2019-02-26 11:18:49",
        "Department_ID": "IT809"
        "Department_Name": "Accounting",
        "Customer_Name": "Jason Pierre",
        "CREATEDTIME": "2019-02-26 11:18:49",
        "ROWID": 3376000000171021,
        "doubleDataType": null
    }
}

    SDK Documentation
    Delete a Row- Java SDK

    Delete a Row- Node.js SDK

    Delete a Row- Python SDK

    Delete a Row- Web SDK

    Get the Metadata of a Specific Table

    Description

    This API enables you to retrieve the metadata of a specific table from the Data Store, by referring to the table’s unique ID or name.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/table/{tableIdentifier}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    tableIdentifier
    Numerical
    The unique ID of the table or table name

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.READ

    Response Details

    The response will return the metadata of the table which will include the table details such as the table_id and table_name, and the metadata of all the columns in it such as the column_id, column_name, and data_type of each column.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/table/EmpDetails  
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
        {
        "status": "success",
        "data": {
            "table_id": 56000000111778,
            "project_id": {
                "id": 4000000006007,
                "project_name": "HRApp"
            },
            "table_name": "EmpDetails",
            "modified_by": {
            "is_confirmed":true,
                "zuid": 1019540152,
                "user_id": 671930455,
                "email_id": "emma@zylker.com",
                "first_name": "Amelia",
                "last_name": "Burrows"
            },
            "modified_time": "2019-02-19T02:45:16+05:30",
            "column_details": [
                {
                    "table_id": 56000000111778,
                    "column_sequence": 1,
                    "column_id": 23400091030,
                    "column_name": "ROWID",
                    "category": 1,
                    "data_type": "bigint",
                    "is_read_only": false,
                    "max_length": 50,
                    "is_mandatory": false,
                    "default_value": "250",
                    "decimal_digits": 2,
                    "is_unique": false,
                    "search_index_enabled": false
                },
                {
                    "table_id": 56000000111778,
                    "column_sequence": 1,
                    "column_id": 23400091031,
                    "column_name": "CREATORID",
                    "category": 1,
                    "data_type": "bigint",
                    "is_read_only": false,
                    "max_length": 50,
                    "is_mandatory": false,
                    "default_value": "250",
                    "decimal_digits": 2,
                    "is_unique": false,
                    "search_index_enabled": true
                },
                {
                    "table_id": 56000000111778,
                    "column_sequence": 1,
                    "column_id": 23400091032,
                    "column_name": "CREATEDTIME",
                    "category": 1,
                    "data_type": "datetime",
                    "is_read_only": false,
                    "max_length": 50,
                    "is_mandatory": false,
                    "default_value": "250",
                    "decimal_digits": 2,
                    "is_unique": false,
                    "search_index_enabled": true
                },
                {
                    "table_id": 56000000111778,
                    "column_sequence": 1,
                    "column_id": 23400091033,
                    "column_name": "MODIFIEDTIME",
                    "category": 1,
                    "data_type": "datetime",
                    "is_read_only": false,
                    "max_length": 50,
                    "is_mandatory": false,
                    "default_value": "250",
                    "decimal_digits": 2,
                    "is_unique": false,
                    "search_index_enabled": true
                }
                {
                    "table_id": 56000000111778,
                    "column_sequence": 1,
                    "column_id": 23400091034,
                    "column_name": "EmpID",
                    "category": 1,
                    "data_type": "varchar",
                    "is_read_only": false,
                    "max_length": 6,
                    "is_mandatory": true,
                    "default_value": "",
                    "decimal_digits": ,
                    "is_unique": true,
                    "search_index_enabled": true
                }
                {
                    "table_id": 56000000111778,
                    "column_sequence": 1,
                    "column_id": 23400091035,
                    "column_name": "EmpName",
                    "category": 1,
                    "data_type": "varchar",
                    "is_read_only": false,
                    "max_length": 30,
                    "is_mandatory": true,
                    "default_value": "",
                    "decimal_digits": ,
                    "is_unique": false,
                    "search_index_enabled": false
                }
                {
                    "table_id": 56000000111778,
                    "column_sequence": 1,
                    "column_id": 23400091036,
                    "column_name": "DeptName",
                    "category": 1,
                    "data_type": "varchar",
                    "is_read_only": false,
                    "max_length": 30,
                    "is_mandatory": true,
                    "default_value": "",
                    "decimal_digits": ,
                    "is_unique": false,
                    "search_index_enabled": false
                }
            ],
            "table_scope": "ORG"
        }
    }
    
    
         
    View more

    SDK Documentation
    Get Table Metadata- Java SDK

    Get Table Metadata- Node.js SDK

    Get Table Metadata- Python SDK

    Get Table Metadata- Web SDK

    Get the Metadata of All Tables

    Description

    This API enables you to retrieve the metadata of all the tables in your project from the Data Store.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/table

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.READ

    Response Details

    The response will return the metadata of all the tables which will include the table details such as the table_id and table_name of each table, and the details of the user that last modified the tables.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/table 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
  "status":"success",
  "data":[
    {
      "project_id":{
        "project_name":"ShipmentTracking",
        "id":4000000006007
      },
      "table_name":"CustomerInfo",
      "modified_by":{
        "zuid":1019540152,
        "is_confirmed":true,
        "email_id":"emma@zylker.com",
        "first_name":"Amelia",
        "last_name":"Burrows",
        "user_id":671930111
      },
      "modified_time":"Apr 11, 2020 10:33 PM",
      "table_id":3376000000081234
    },
    {
      "project_id":{
        "project_name":"ShipmentTracking",
        "id":3376000000061190
      },
      "table_name":"EmpInfo",
      "modified_by":{
        "zuid":1019540232,
        "is_confirmed":true,
        "email_id":"p.boyle@zylker.com",
        "first_name":"Patricia",
        "last_name":"Boyle",
        "user_id":671930455
      },
      "modified_time":"Mar 09, 2020 03:16 AM",
      "table_id":3376000000017896
    }
  ]
}
    
    
         
    View more

    SDK Documentation
    Get Table Metadata- Java SDK

    Get Table Metadata- Node.js SDK

    Get Table Metadata- Python SDK

    Get Table Metadata- Web SDK

    Get the Metadata of a Specific Column

    Description

    This API enables you to retrieve the metadata of a specific column in a table in the Data Store. The table is referred by its unique ID or name, and the column is referred by the column ID.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/table/{tableIdentifier}/column/{column_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    tableIdentifier
    Numerical
    The unique ID of the table or table name
    column_id
    Numerical
    The unique ID of the column

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.columns.READ

    Response Details

    The response will return the metadata of the specific column such as its column_id, column_name, and data_type.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/table/EmpDetails/column/4000000042018  
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "table_id": 56000000118,
        "column_sequence": 3,
        "column_id": 4000000042018,
        "column_name": "Department",
        "category": 2,
        "data_type": "text",
        "is_read_only": false,
        "max_length": 100,
        "is_mandatory": true,
        "default_value": "Admin",
        "is_unique": false,
        "search_index_enabled": false
    }
}

    SDK Documentation
    Get Column Metadata- Java SDK

    Get Column Metadata- Node.js SDK

    Get Column Metadata- Python SDK

    Get Column Metadata- Web SDK

    Get the Metadata of All Columns

    Description

    This API enables you to retrieve the metadata of all the columns in a table in the Data Store, by referring to the table’s unique ID or name.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/table/{tableIdentifier}/column

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    tableIdentifier
    Numerical
    The unique ID of the table or table name

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.columns.READ

    Response Details

    The response will return the metadata of all columns such as the column_id, column_name, and data_type of each column.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/table/EmpDetails/column 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
      {
    "status":"success",
    "data":[
      {
        "table_id":829000000037723,
        "column_sequence":1,
        "column_name":"ROWID",
        "category":1,
        "data_type":"bigint",
        "is_read_only":false,
        "max_length":50,
        "is_mandatory":false,
        "decimal_digits":2,
        "is_unique":false,
        "search_index_enabled":false,
        "column_id":829000000037726
      },
      {
        "table_id":829000000037723,
        "column_sequence":2,
        "column_name":"CREATORID",
        "category":1,
        "data_type":"bigint",
        "is_read_only":false,
        "max_length":50,
        "is_mandatory":false,
        "decimal_digits":2,
        "is_unique":false,
        "search_index_enabled":true,
        "column_id":829000000037728
      },
      {
        "table_id":829000000037723,
        "column_sequence":3,
        "column_name":"CREATEDTIME",
        "category":1,
        "data_type":"datetime",
        "is_read_only":false,
        "max_length":50,
        "is_mandatory":false,
        "decimal_digits":2,
        "is_unique":false,
        "search_index_enabled":true,
        "column_id":829000000037730
      },
      {
        "table_id":829000000037723,
        "column_sequence":4,
        "column_name":"MODIFIEDTIME",
        "category":1,
        "data_type":"datetime",
        "is_read_only":false,
        "max_length":50,
        "is_mandatory":false,
        "decimal_digits":2,
        "is_unique":false,
        "search_index_enabled":true,
        "column_id":829000000037732
      },
      {
        "table_id":829000000037723,
        "column_sequence":5,
        "column_name":"EmpID",
        "category":2,
        "data_type":"bigint",
        "is_read_only":false,
        "max_length":15,
        "is_mandatory":true,
        "decimal_digits":2,
        "is_unique":true,
        "search_index_enabled":false,
        "column_id":829000000038445
      },
      {
        "table_id":829000000037723,
        "column_sequence":6,
        "column_name":"EmpName",
        "category":2,
        "data_type":"text",
        "is_read_only":false,
        "max_length":50,
        "is_mandatory":true,
        "decimal_digits":2,
        "is_unique":false,
        "search_index_enabled":false,
        "column_id":829000000038450
      }
    ]
  }
    
    
         
    View more

    SDK Documentation
    Get Column Metadata- Java SDK

    Get Column Metadata- Node.js SDK

    Get Column Metadata- Python SDK

    Get Column Metadata- Web SDK

    Truncate a Table

    Description

    This API enables you to truncate a specific table in the Data Store, by referring to the table’s unique ID or name.

    The truncate operation deletes all the records in the table, while retaining its schema. The columns of the table and the table’s metadata will still be available, after the operation has ended.

    You will receive notifications in your Catalyst console about the updates of the operation.

    Request Details

    Request URL

    DELETE

    {api-domain}/baas/v1/project/{project_id}/table/{tableIdentifier}/truncate

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    tableIdentifier
    Numerical
    The unique ID of the table or table name

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.rows.DELETE

    Response Details

    The response will return the status of the truncate operation.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X DELETE 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/table/NewsHeadlines/truncate  
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": "The table will be truncated Shortly. Kindly Check Notification bar for updates"
}

    Bulk Read Records

    The Bulk Read operation can read thousands of records from a specific table in the Data Store and generate a CSV file containing the results of the read operation, if the job is successful. This data-intense operation can be performed in a single API execution.

    Catalyst supports three APIs for the bulk read operation: a Create Bulk Read API, a Check Bulk Read Status API to check the status of the job execution manually, and a Download Bulk Read Result API to download the results. You can also configure a callback URL to enable the automatic posting of the job status responses in it.

    Note: You can also perform Bulk Read operation using the Catalyst CLI. Refer to Data Store Import and Export CLI documentation.

    Create a Bulk Read Job

    Description

    This API triggers the bulk read operation to obtain the records from the table in the Data Store, that match the criteria you specify in the input JSON. The table is referred to using its unique table ID or the table name.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{projectId}/bulk/read

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.bulk.READ

    Request JSON Properties

    The input for the Bulk Read API request must be sent in a JSON format. The request parameters are explained below.

    table_identifier string
    mandatory
    The unique ID of the table or the table name. You can obtain the table ID from Data Store or from the URL when the table is opened in the console.
    query json
    optional

    The section where you can define the conditions and criteria for the bulk read job

    page numerical
    optional

    The CSV file generated as the result of the bulk read process contains two hundred thousand/two lakh records in one page.

    Page value ‘1’ indicates that the first two lakh records matching your query will get exported. You can fetch subsequent records by increasing the page value.

    For example, if you want to fetch records from the range 2,00,001 to 4,00,000, then you must specify the page value as ‘2’.

    Default value: 1

    select_columns array
    optional

    Specific columns in the records that need to be fetched from the table. If you do not specify the columns, all columns will be selected and fetched.


    You can include multiple columns in an array. Refer to the sample request code window.

    criteria json
    optional

    A set of conditions based on which the records will be fetched

    group_operator string
    mandatory (if specifying criteria)

    The operator that will bind the criteria groups together.


    Supported Operators: AND, OR


    If you define two or more criteria groups, you can use the AND or the OR operator in your request. For example, you can specify a criteria like “column1 equal value 1 AND column2 contains value 2” in the format specified in the previous section.


    Note: You will not be able to use combinations of both the operators in a single API request. You can either use AND or OR in one request.
    group json
    mandatory (if specifying criteria)

    You can include upto 25 criteria sets in this section. The example shows 3 criteria sets.


    Note: You can include only one overall group with one group operator in a single API request.
    column_name string
    mandatory (if specifying criteria)
    Name of the specific column from the table that the criteria should be defined for
    comparator string
    mandatory (if specifying criteria)

    The comparison operator that matches the column name with the criteria value


    Supported Comparators: equal, not_equal, greater_than, greater_equal, less_than, less_equal, starts_with, ends_with, contains, not_contains, in, not_in, between, not_between


    Note:

    • You can specify multiple values for in and not_in comparators, separated by commas.

    • Catalyst supports only the equal comparator for an encrypted column. You will not be able to use other comparators as the criteria for an encrypted column.

    value string
    mandatory (if specifying criteria)
    The value for the specific column in the record that you require to be defined as a criteria
    callback json
    optional

    The section where you can define the properties of the callback URL, where automatic JSON responses of the job statuses will be sent to

    url string
    mandatory (if specifying callback)

    The URL where the automatic responses will be sent to using the HTTP POST method, each time the job status changes. Information about the job details will be contained in the body of the JSON response.


    If you don’t configure a callback URL, you must manually check the status of the job processing when you need, using the Check Bulk Read Status API.

    headers string
    optional

    Headers that you require to be passed in the JSON response to the callback URL.


    You must specify the headers as:
    {
    "{header_name_1}" : “{header_value_1}”,
    "{header_name_2}" : “{header_value_2}”
    }


    and so on. Refer to the sample request code.

    params string
    optional

    Parameters that you require to be require to be appended to the callback URL


    You must specify the parameters as:
    {
    "{param_name_1}" : “{param_value_1}”,
    "{param_name_2}" : “{param_value_2}”
    }


    and so on. Refer to the sample request code.

    Response Details

    There are three job processing states which will generate three different responses:

    • In-Progress: When you execute the API, Catalyst will immediately and automatically send you a response indicating that the job execution in progress. If you have configured a callback URL in the request, the response will also be posted to the URL in the format defined by you.

      The response will contain a job_id parameter which you can use to check the status of the job execution for subsequent responses, if you have not configured a callback URL.

    • Success: The success state response will contain a download URL, where you can download a CSV file that contains the records matching your query. If you have not configured a callback URL, this response will not be sent by Catalyst automatically.

    • Failed: The failed state response will contain a description of the error occurred and the details. If you have not configured a callback URL, this response will not be sent by Catalyst automatically.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/bulk/read  
    
-H “Authorization: Zoho-oauthtoken 1000.91016.2f*57” 
    
-d ‘{
“table_identifier”: “EmpDetails”,
“query” : {
“page” : “1”,
“select_columns” : [
“EmpID”, “EmpName”, “Department”
],
“criteria”: {
“group_operator”: “or”,
“group”: [
{
“column_name”: “Department”,
“comparator”: “equal”,
“value”: “Marketing”
} ,
{
“column_name”: “EmpID”,
“comparator”: “greater_than”,
“value”: “1000”
} ,
{
“column_name”: “EmpName”,
“comparator”: “starts_with”,
“value”: “S”
}
]
}
},
“callback” : {
“url” : “https://hr.zylker.com/en/EmpRecords/_callback.php",
“headers” : {
“src” : “ZCatalyst”,
“operation” : “bulkreadAPI”
},
“params” : {
“project_name” : “EmployeeDatabase”
}
}
}’
    
    
    
    

        
    
        
    Sample Response: Job in Progress
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "job_id": 2000000118004,
    "status": "In-Progress",
    "operation": "read",
    "project_details": {
         "project_name": "ShipmentTracking",
         "id": 4000000006007
     },
    "query": [
        {
            "table_id": 3376000000165541,
            "details": {
                "page": "1"
            }
        }
    ],
    "callback": {
        "url": "https://hr.zylker.com/en/EmpRecords/_callback.php",
        "headers": {
                  "src" : "ZCatalyst",
                  "operation" : "bulkreadAPI"
                          },
        "params": {
                  "project_name" : "EmployeeDatabase"
                         }
    },
    "created_by": {
        "zuid": 1019540152,
        "is_confirmed": true,
        "email_id": "emma@zylker.com",
        "first_name": "Amelia",
        "last_name": "Burrows",
        "user_id": 671930409
    },
    "created_time": "Oct 06, 2020 07:06 PM"
}

    

    }
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Job Successful
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "job_id": 2000000118004,
    "status": "In-Progress",
    "operation": "read",
    "project_details": {
         "project_name": "ShipmentTracking",
         "id": 4000000006007
     },
    "query": [
        {
            "table_id": 3376000000165541,
            "details": {
                "page": "1"
            }
        }
    ],
    "callback": {
        "url": "https://hr.zylker.com/en/EmpRecords/_callback.php",
        "headers": {
                  "src" : "ZCatalyst",
                  "operation" : "bulkreadAPI"
                          },
        "params": {
                  "project_name" : "EmployeeDatabase"
                         }
    },
    "created_by": {
        "zuid": 1019540152,
        "is_confirmed": true,
        "email_id": "emma@zylker.com",
        "first_name": "Amelia",
        "last_name": "Burrows",
        "user_id": 671930409
    },
    "created_time": "Oct 06, 2020 07:06 PM"
}

    

    }
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Job Failed
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "job_id": 2000000117007,
    "status": "Failed",
    "operation": "read",
    "project_details": {
         "project_name": "ShipmentTracking",
         "id": 4000000006007
     },
    "query": [
        {
            "table_id": 3376000000165541,
            "details": {
                "page": "1"
            }
        }
    ],
    "callback": {
        "url": "https://hr.zylker.com/en/EmpRecords/_callback.php",
         "headers": {
                  "src" : "ZCatalyst",
                  "operation" : "bulkreadAPI"
                          },
        "params": {
                   "project_name" : "EmployeeDatabase"
                         }
    },
    "created_by": {
        "zuid": 1019540152,
        "is_confirmed": true,
        "email_id": "emma@zylker.com",
        "first_name": "Amelia",
        "last_name": "Burrows",
        "user_id": 671930409
    },
    "created_time": "Oct 06, 2020 07:00 PM",
    "results": {
        "description": "The column ID in select_columns is invalid",
    }
}

    

    }
    
    
         
    View more

    Check Bulk Read Status

    Description

    You can execute this API to manually check the status of the bulk read job that you initiated previously.

    If you had not configured a callback URL in your JSON request, you must check the job status yourself by executing this API. You must use the job_id that is sent to you in the automatic in-progress response when you initiate the bulk read operation, to check the job status subsequently.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/bulk/read/{job_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    job_id
    Numerical

    The unique ID of the job that was sent in the initial in-progress status response after the Bulk Read API was executed

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.bulk.READ

    Response Details

    The JSON response for the success state will contain the details of the executed job, along with a download URL where you can download a CSV file that will contain a list of records matching your bulk read job query.

    The JSON response for the failed state will contain the details of the executed job, along with a description of the error the occurred in the job processing, and its details, such as the rows that were skipped from being read and the reasons.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/bulk/read/2000000118004  
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response: Job in Progress
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "job_id": 2000000118004,
    "status": "In-Progress",
    "operation": "read",
    "project_details": {
        "project_name": "EmployeeDatabase",
        "id": 4000000006007
    },
    "query": [
        {
            "table_id": 3376000000165541,
            "details": {
                "page": "1"
            }
        }
    ],
    "callback": {
        "url": "https://hr.zylker.com/en/EmpRecords/_callback.php",
        "headers": {
                  "src" : "ZCatalyst",
                  "operation" : "bulkreadAPI"
                          },
        "params": {
                  "project_name" : "EmployeeDatabase"
                         }
    },
    "created_by": {
        "zuid": 1019540152,
        "is_confirmed": true,
        "email_id": "emma@zylker.com",
        "first_name": "Amelia",
        "last_name": "Burrows",
        "user_id": 671930409
    },
    "created_time": "Oct 06, 2020 07:06 PM"
}

    

    }
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Job Successful
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "job_id": 2000000118004,
    "status": "Completed",
    "operation": "read",
    "project_details": {
        "project_name": "EmployeeDatabase",
        "id": 4000000006007
    },
    "query": [
                    {
            "table_id": 3376000000165541,
            "details": {
                "page": "1"
                            }
                      }
                   ],
    "callback": {
            "url": "https://hr.zylker.com/en/EmpRecords/_callback.php",
            "headers": {
                  "src" : "ZCatalyst",
                  "operation" : "bulkreadAPI"
                          },
              "params": {
                   "project_name" : "EmployeeDatabase"
                         }
                       },
    "created_by": {
            "zuid": 1019540152,
            "is_confirmed": true,
            "email_id": "emma@zylker.com",
            "first_name": "Amelia",
            "last_name": "Burrows",
            "user_id": 671930409
                           },
    "created_time": "Oct 06, 2020 07:06 PM",
"results": {
           "download_url": "https://api.catalyst.zoho.com/baas/v1/bulk/read/2000000117007/download",
           "description": "Bulk READ job 2000000117007 completed.",
            "details": [
                             {
                   "table_id": 3376000000165541,
                   "records_processed": 21,
                   "more_records": false
                             }
                           ]
                    }
           }

    

    }
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Job Failed
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "job_id": 2000000117007,
    "status": "Failed",
    "operation": "read",
    "project_details": {
        "project_name": "EmployeeDatabase",
        "id": 4000000006007
    },
    "query": [
        {
            "table_id": 3376000000165541,
            "details": {
                "page": "1"
            }
        }
    ],
    "callback": {
        "url": "https://hr.zylker.com/en/EmpRecords/_callback.php",
         "headers": {
                  "src" : "ZCatalyst",
                  "operation" : "bulkreadAPI"
                          },
        "params": {
                   "project_name" : "EmployeeDatabase"
                         }
    },
    "created_by": {
        "zuid": 1019540152,
        "is_confirmed": true,
        "email_id": "emma@zylker.com",
        "first_name": "Amelia",
        "last_name": "Burrows",
        "user_id": 671930409
    },
    "created_time": "Oct 06, 2020 07:00 PM",
    "results": {
        "description": "The column ID in select_columns is invalid",
    }
}

    

    }
    
    
         
    View more

    Download Bulk Read Result

    Description

    You can execute this API to download the result of a successful bulk read job that you initiated. This URL will also be sent in JSON response for the success state.

    The downloaded CSV result file will contain a list of all the records matching your bulk read job query.

    Note: The download URL will be valid for 1 day since its generation. The link will expire after that time period, and you will not be able to obtain the CSV result file containing the job details.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/bulk/read/{job_id}/download

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    job_id
    Numerical

    The unique ID of the job that was sent in the initial in-progress status response after the Bulk Read API was executed

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.bulk.READ

    Response Details

    The bulk read result file will be automatically downloaded to the configured directory in your system after you execute this API.

    File format: ZIP file containing the CSV result file

    Sample result file showing the details of a bulk read job:

    bulk_read

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/bulk/read/2000000118004/download  
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”

    Bulk Write Records

    The Bulk Write operation can fetch thousands of records from a CSV file uploaded in the File Store and insert them in a specific table in the Data Store. This data intense operation can be performed in a single API execution.

    After the bulk write operation has executed successfully, a CSV report file containing the details of the job execution will be generated at a download URL.

    Catalyst supports three APIs for the bulk write operation: a Create Bulk Write API, a Check Bulk Write Status API to check the status of the job execution manually, and a Download Bulk Write Result API to download the results. You can also configure a callback URL to enable automatic posting of the job status responses in it.

    Note: You can also perform Bulk Write operation using the Catalyst CLI. Refer to Data Store Import and Export CLI documentation.

    Create a Bulk Write Job

    Description

    This API triggers the bulk write operation to obtain the records from a CSV file in the File Store and export them to a table in the Data Store, based on the criteria you specify in the input JSON. The CSV file is referred to using its File ID in the File Store, and the table is referred to using its unique table ID or the table name.

    Note:

    • You must upload the CSV file containing the data in the File Store, before you begin executing this operation.

    • The CSV file’s first row must be the header row i.e., the column names must be present as the header row.

    • The CSV file must contain data in the format that adheres to CSV file standards. If the file is not in the standard format, the data written to the table might be corrupted.

    • You can insert 5000 records in each table per project in the development environment using this API. If the CSV file contains records more than that, the first 5000 records will be written to the table. The others will be skipped in the development environment. There are no table limits for insertion in the production environment. However, the Bulk Write API can insert upto 100000 records in a single API call from a CSV file even in the production environment. If you require more records to be written, you can do so in batches of 100000 records by sending multiple Bulk Write API requests accordingly.

    There are three operations that can be performed using this API:

    • Insert: Inserts new rows of data into the table from the CSV file
    • Update: Updates existing rows of data in the table. The records are identified either using a unique column in the table, or using their ROWIDs generated in the Data Store.
    • Upsert: Enables both insert and update operations at the same time. If the record already exists, the row is updated. If the record does not exist, a new row with the data is inserted.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{projectId}/bulk/write

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.bulk.CREATE

    Request JSON Properties

    The input for the Bulk Write API request must be sent in a JSON format. The request parameters are explained below.

    table_identifier string
    mandatory
    The unique ID of the table or the table name. You can obtain the table ID from Data Store or from the URL when the table is opened in the console.
    operation string
    optional

    Specifies the operation to be executed using the API.

    Allowed values: insert, update, upsert

    Default operation: insert

    file_id numerical
    mandatory
    The unique ID of the CSV file in the File Store which contains the records to be written.
    find_by string
    mandatory (update, upsert), optional (insert)

    The unique column using which the records are identified.

    For example, if you specify a unique column called ‘EmployeeID’ as the find_by value, Catalyst will search the records in the Data Store table using the EmployeeID value. For the update operation, Catalyst will update the rows that match the EmployeeID from the CSV file. For the upsert operation, Catalyst will update existing rows, and insert new rows if there are no records with matching EmployeeID values.

    Update: This can be a column with unique values as configured in the Data Store, or the ROWID generated by Catalyst for the records.

    Upsert: You can only specify a column with unique values as configured in the Data Store. You will not be able to specify the ROWID as the find_by value. This is because, upsert will insert new rows if matching ones are not found, and the ROWID values will not be available for rows not existing in the Data Store.

    Insert: If you specify a find_by column for an insert operation, any records matching the column values from the CSV file will be skipped and not inserted into the Data Store table. This is because, insert cannot update if a given record already exists.

    fk_mapping json
    optional

    Foreign key mapping for the columns that are primary keys in other tables. This is specified if any columns imported from the CSV file should be configured as foreign keys.

    You must map foreign keys in the following format:
    {
    “local_column” : “local_column_name_1”,
    “reference_column” : “reference_column_name_1”
    }

    where local_column is the name of the column in the table where the bulk write operation is processed, and reference_column is the name of the column in the table in which it is a primary key.

    Refer to the sample request code.

    callback json
    optional

    The section where you can define the properties of the callback URL, where automatic JSON responses of the job statuses will be sent to

    url string
    mandatory (if specifying callback)

    The URL where the automatic responses will be sent to using the HTTP POST method, each time the job status changes. Information about the job details will be contained in the body of the JSON response.

    If you don’t configure a callback URL, you must manually check the status of the job processing when you need, using the Check Bulk Write Status API.

    headers string
    optional

    Headers that you require to be passed in the JSON response to the callback URL

    You must specify the headers as:
    {
    "{header_name_1}" : “{header_value_1}”,
    "{header_name_2}" : “{header_value_2}”
    }

    and so on. Refer to the sample request code.

    params string
    optional

    Parameters that you require to be require to be appended to the callback URL

    You must specify the parameters as:
    {
    "{param_name_1}" : “{param_value_1}”,
    "{param_name_2}" : “{param_value_2}”
    }

    and so on. Refer to the sample request code.

    Response Details

    There are three job processing states which will generate three different responses:

    • In-Progress: When you execute the API, Catalyst will immediately and automatically send you a response indicating that the job execution in progress. If you have configured a callback URL in the request, the response will also be posted to the URL in the format defined by you.

      The response will contain a job_id parameter which you can use to check the status of the job execution for subsequent responses, if you have not configured a callback URL.

    • Success: The success state response will contain a download URL, where you can download a CSV report file that contains the details of the job execution. It will list all the records that were skipped from being written along with the reasons. If you have not configured a callback URL, this response will not be sent by Catalyst automatically.

    • Failed: The failed state response will contain a description of the error occurred and the details. If you have not configured a callback URL, this response will not be sent by Catalyst automatically.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/bulk/write  
    
-H “Authorization: Zoho-oauthtoken 1000.91016.2f*57” 
    
-d ‘{
“table_identifier”: “3376000000165511”,
“operation” : “insert”,
“file_id” : 3376000000363098,
“callback” : {
“url” : “https://hr.zylker.com/en/EmpRecords/_callback.php",
“headers” : {
“src” : “ZCatalyst”,
“operation” : “bulkwriteAPI”
},
“params” : {
“project_name” : “EmployeeDatabase”
}
},
“find_by” : “EmpID”,
“fk_mapping” : [
{
“local_column” : “EmployeeID”,
“reference_column” : “EmpID”
},
{
“local_column” : “DepartmentID”,
“reference_column” : “DeptID”
}
]
}’
    
    
    
    

        
    
        
    Sample Response: Job in Progress
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "job_id": 2000000110044,
    "status": "In-Progress",
    "operation": "insert",
    "project_details": {
         "project_name": "ShipmentTracking",
         "id": 4000000006007
     },
    "query": [
                    {
            "table_id": 3376000000165511,
            "details": {
                "file_id": 3376000000363098
                            }
                      }
                    ],
    "callback": {
    "url": "https://hr.zylker.com/en/EmpRecords/_callback.php",
    "headers": {
        "src": "ZCatalyst",
       "operation": "bulkwriteAPI"
      },
    "params": {
    "project_name": "EmployeeDatabase"
               }
         },
    "created_by": {
             "zuid": 3000000006111,
             "is_confirmed": true,
             "email_id": "emma@zylker.com",
             "first_name": "Amelia",
             "last_name": "Burrows",
             "user_id": 671930409
                             },
    "created_time": "Oct 05, 2020 07:33 PM"
}
}
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Job Successful
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "job_id": 2000000110044,
    "status": "Completed",
    "operation": "insert",
    "project_details": {
        "project_name": "ShipmentTracking",
        "id": 4000000006007
    },
    "query": [
        {
            "table_id": 3376000000165511,
            "details": {
                "file_id": 3376000000363098
            }
        }
    ],
    "callback": {
        "url": "https://hr.zylker.com/en/EmpRecords/_callback.php",
        "headers": {
            "src": "ZCatalyst",
            "operation": "bulkwriteAPI"
        },
        "params": {
            "project_name": "EmployeeDatabase"
        }
    },
        "created_by": {
            "zuid": 3000000006111,
            "is_confirmed": true,
            "email_id": "emma@zylker.com",
            "first_name": "Amelia",
            "last_name": "Burrows",
            "user_id": 671930409
        },
        "created_time": "Oct 05, 2020 07:25 PM",
        "results": {
            "download_url": "https://api.catalyst.zoho.com/baas/v1/bulk/write/2000000110013/download",
            "description": "Bulk WRITE job completed. ",
            "details": [
                {
                    "table_id": 3376000000165511,
                    "records_processed": 176
                }
            ]
        }
    }
}
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Job Failed
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "job_id": 2000000110044,
    "status": "Failed",
    "operation": "insert",
    "project_details": {
         "project_name": "ShipmentTracking",
         "id": 4000000006007
     },
    "query": [
                   {
            "table_id": 3376000000165511,
            "details": {
                "file_id": 3376000000363098
                            }
                    }
                   ],
 "callback": {
      "url": "https://hr.zylker.com/en/EmpRecords/_callback.php",
      "headers": {
           "src": "ZCatalyst",
           "operation": "bulkwriteAPI"
      },
    "params": {
          "project_name": "EmployeeDatabase"
     }
 }
    "created_by": {
        "zuid": 3000000006111,
        "is_confirmed": true,
        "email_id": "emma@zylker.com",
        "first_name": "Amelia",
        "last_name": "Burrows",
        "user_id": 671930409
                            },
    "created_time": "Oct 05, 2020 07:25 PM",
    "results": {
        "description": "The reference_column 'DeptID' in fk_mapping of table 3376000000165511 is not a unique column",
        "details": [ ]
                    }
               }
}
    
    
         
    View more

    Check Bulk Write Status

    Description

    You can execute this API to manually check the status of the bulk write job that you initiated previously.

    If you had not configured a callback URL in your JSON request, you must check the job status yourself by executing this API. You must use the job_id that is sent to you in the automatic in-progress response when you initiated the bulk write operation, to check the job status subsequently.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/bulk/write/{job_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    job_id
    Numerical

    The unique ID of the job that was sent in the initial [in-progress status response](/en/api/introduction/overview-and-prerequisites/#response-details) after the Bulk Write API was executed

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.bulk.CREATE

    Response Details

    The JSON response for the success state will contain the details of the executed job, along with a download URL, where you can download a CSV report file that will contain the details of the job execution. It will list all the records that were skipped from being written along with the reasons.

    The JSON response for the failed state will contain the details of the executed job, along with a description of the error occurred in the job processing, and its details.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/bulk/write/2000000110044  
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response: Job in Progress
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "job_id": 2000000110044,
        "status": "In-Progress",
        "operation": "insert",
        "project_details": {
            "project_name": "EmployeeDatabase",
            "id": 4000000006007
        }
        "query": [
            {
                "table_id": 3376000000165511,
                "details": {
                    "file_id": 3376000000363098
                }
            }
        ],
        "callback": {
            "url": "https://hr.zylker.com/en/EmpRecords/_callback.php",
            "headers": {
                "src": "ZCatalyst",
                "operation": "bulkwriteAPI"
            },
            "params": {
                "project_name": "EmployeeDatabase"
            }
        },
        "created_by": {
                "zuid": 3000000006111,
                "is_confirmed": true,
                "email_id": "emma@zylker.com",
                "first_name": "Amelia",
                "last_name": "Burrows",
                "user_id": 671930409
        },
        "created_time": "Oct 05, 2020 07:33 PM"
    }
}
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Job Successful
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "job_id": 2000000110044,
        "status": "Completed",
        "operation": "insert",
        "project_details": {
            "project_name": "EmployeeDatabase",
            "id": 4000000006007
        }
        "query": [
            {
                "table_id": 3376000000165511,
                "details": {
                    "file_id": 3376000000363098
                }
            }
        ],
        "callback": {
            "url": "https://hr.zylker.com/en/EmpRecords/_callback.php",
            "headers": {
                "src": "ZCatalyst",
                "operation": "bulkwriteAPI"
            },
            "params": {
                "project_name": "EmployeeDatabase"
            }
        },
        "created_by": {
            "zuid": 3000000006111,
            "is_confirmed": true,
            "email_id": "emma@zylker.com",
            "first_name": "Amelia",
            "last_name": "Burrows",
            "user_id": 671930409
        },
        "created_time": "Oct 05, 2020 07:25 PM",
        "results": {
            "download_url": "https://api.catalyst.zoho.com/baas/v1/bulk/write/2000000110013/download",
            "description": "Bulk WRITE job completed. ",
            "details": [
                {
                    "table_id": 3376000000165511,
                    "records_processed": 176
                }
            ]
        }
    }
}
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Job Failed
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "job_id": 2000000110044,
        "status": "Failed",
        "operation": "insert",
        "project_details": {
            "project_name": "EmployeeDatabase",
            "id": 4000000006007
        }
        "query": [
            {
                "table_id": 3376000000165511,
                "details": {
                    "file_id": 3376000000363098
                }
            }
        ],
        "callback": {
            "url": "https://hr.zylker.com/en/EmpRecords/_callback.php",
            "headers": {
                "src": "ZCatalyst",
                "operation": "bulkwriteAPI"
            },
            "params": {
                "project_name": "EmployeeDatabase"
            }
        },
        "created_by": {
            "zuid": 3000000006111,
            "is_confirmed": true,
            "email_id": "emma@zylker.com",
            "first_name": "Amelia",
            "last_name": "Burrows",
            "user_id": 671930409
        },
        "created_time": "Oct 05, 2020 07:25 PM",
        "results": {
            "description": "The reference_column 'DeptID' in fk_mapping of table 3376000000165511 is not a unique column",
            "details": [ ]
        }
    }
}
    
    
         
    View more

    Download Bulk Write Result

    Description

    You can execute this API to download the result of a successful bulk write job that you initiated. This URL will also be sent in JSON response for the success state.

    The downloaded CSV file will contain the details of the job execution. It will list all the records that were skipped from being written along with the reasons.

    Note: The download URL will be valid for 1 day since its generation. The link will expire after that time period, and you will not be able to obtain the CSV result file containing the job details.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/bulk/write/{job_id}/download

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    job_id
    Numerical

    The unique ID of the job that was sent in the initial [in-progress status response](/en/api/introduction/overview-and-prerequisites/#response-details) after the Bulk Write API was executed

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.bulk.CREATE

    Response Details

    The bulk write result file will be automatically downloaded to the configured directory in your system after you execute this API.

    File format: ZIP file containing the CSV result file

    Sample result file showing the details of a bulk write job:

    bulk_write

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/bulk/write/2000000110044/download  
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”

    Bulk Delete Rows in a Table

    Description

    This API enables you to delete records or rows of data in bulk from a specific table in the Data Store. The table is referred by its unique ID or name.

    The bulk delete operation can delete a maximum of 200 rows in a single API call. You can choose the rows to be deleted by passing the unique ROWIDs of those rows as params in the request URL, as shown in the sample request.

    You must include at least one ROWID, and can include upto 200 ROWIDs, in the request.

    Request Details

    Request URL

    DELETE

    {api-domain}/baas/v1/project/{project_id}/table/{tableIdentifier}/row?ids={rowID_1},{rowID_2},{rowID_3}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    tableIdentifier
    Numerical
    The unique ID of the table or table name
    ids
    Numerical
    The Row IDs of the records to be deleted as params. Multiple Row IDs must be separated by commas. The parameter key name must be ids

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.tables.rows.DELETE

    Response Details

    The response contains the data of all the rows that were deleted through the operation, including their metadata like theROWID and CREATEDTIME, and the column key names and values in each row.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X DELETE 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/table/EmpDetails/row?ids=1028000000171815,1028000000171810,1028000000171805,1028000000171617 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": [
    {
        "CREATORID": "1444000000003001",
        "MODIFIEDTIME": "2020-11-19 15:20:21:830",
        "Department_ID":"IT245",
        "Department_Name":"Finance",
        "Employee_Name": "Morgan Jones",
        "CREATEDTIME": "2020-11-19 15:20:21:830",
        "ROWID": "1028000000171815"
    },
    {
        "CREATORID": "1444000000003001",
        "MODIFIEDTIME": "2020-11-19 15:20:34:503",
        "Department_ID":"IT121",
        "Department_Name":"HR",
        "Employee_Name": "Leena Medley",
        "CREATEDTIME": "2020-11-19 15:20:34:503",
        "ROWID": "1028000000171810"
    },
    {
        "CREATORID": "1444000000003001",
        "MODIFIEDTIME": "2020-11-19 15:20:42:314",
        "Department_ID":"IT783",
        "Department_Name":"Marketing",
        "Employee_Name": "Tamira Shah",
        "CREATEDTIME": "2020-11-19 15:20:42:314",
        "ROWID": "1028000000171805"
    },
   {
        "CREATORID": "1444000000003001",
        "MODIFIEDTIME": "2020-11-19 15:20:42:314",
        "Department_ID":"IT098",
        "Department_Name":"Sales",
        "Employee_Name": "Julia McGregor",
        "CREATEDTIME": "2020-11-19 15:20:42:314",
        "ROWID": "1028000000171617"
    }
]

    

    }
    
    
         
    View more

    SDK Documentation
    Bulk Delete Rows- Java SDK

    Bulk Delete Rows- Node.js SDK

    Bulk Delete Rows- Python SDK

    Bulk Delete Rows- Web SDK

    File Store

    Catalyst File Store provides cloud storage solutions to store, manage, and organize your application files and user data files such as images, videos, CSV files, spreadsheets, and more in folders.

    Get the Details of a Specific Folder

    Description

    This API enables you to retrieve the details of a specific folder in the File Store, along with the details of all the files in the folder. The folder is referred by its unique Folder ID.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/folder/{folder_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    folder_id
    Numerical
    The unique ID of the folder

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.folders.READ

    Response Details

    The JSON response returns the metadata of the particular folder such as the folder_name, the details of the user who created and last modified it, along with the metadata of all the files in the folder, such as the file_id, file_name, file_size of each file.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/folder/3376000000427654 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status":"success",
"data":{
  "folder_name":"PricingInfo",
  "created_time":"Apr 01, 2020 11:11 AM",
  "created_by":{
    "zuid":1019540152,
    "is_confirmed":true,
    "email_id":"emma@zylker.com",
    "first_name":"Amelia",
    "last_name":"Burrows",
    "user_id":671930455
  },
  "modified_time":"Apr 11, 2020 10:41 PM",
  "modified_by":{
    "zuid":1019540876,
    "is_confirmed":true,
    "email_id":"p.boyle@zylker.com",
    "first_name":"Patricia",
    "last_name":"Boyle",
    "user_id":671930321
  },
  "project_details":{
    "project_name":"ShipmentTracking",
    "id":4000000006007
  },
  "file_details":[
    {
      "id":337600000030123,
      "file_location":null,
      "file_name":"PO1898908GT.pdf",
      "file_size":10,
      "created_by":{
        "zuid":1019540199,
        "is_confirmed":true,
        "email_id":"jane.simmons@zylker.com",
        "first_name":"Jane",
        "last_name":"Simmons",
        "user_id":671930000
      },
      "created_time":"Feb 21, 2020 01:11 PM",
      "modified_by":{
        "zuid":1019540152,
        "is_confirmed":true,
        "email_id":"p.boyle@zylker.com",
        "first_name":"Patricia",
        "last_name":"Boyle",
        "user_id":671930321
      },
      "modified_time":"Jan 13, 2020 08:00 PM",
      "project_details":{
        "project_name":"ShipmentTracking",
        "id":4000000006007
      },
      "folder_details": 3376000000427654
    },
    {
      "id":337600000030121,
      "file_location":null,
      "file_name":"ST1898190CR.pdf",
      "file_size":9,
      "created_by":{
        "zuid":1019540152,
        "is_confirmed":true,
        "email_id":"p.boyle@zylker.com",
        "first_name":"Patricia",
        "last_name":"Boyle",
        "user_id":671930321
      },
      "created_time":"Jan 01, 2020 09:09 PM",
      "modified_by":{
        "zuid":1019540152,
        "is_confirmed":true,
        "email_id":"p.boyle@zylker.com",
        "first_name":"Patricia",
        "last_name":"Boyle",
        "user_id":671930321
      },
      "modified_time":"Mar 11, 2020 07:09 AM",
      "project_details":{
        "project_name":"ShipmentTracking",
        "id":4000000006007
      },
      "folder_details":3376000000427654
    }
  ],
  "audit_consent": false,
  "id":829000000038455
}

    

    }
    
    
         
    View more

    SDK Documentation
    Retrieve Folder Details- Java SDK

    Retrieve Folder Details- Node.js SDK

    Retrieve Folder Details- Python SDK

    Retrieve Folder Details- Web SDK

    Get the Details of All Folders

    Description

    This API enables you to retrieve the details of all the folders in your project from the File Store.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/folder

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.folders.READ

    Response Details

    The JSON response returns the metadata of all the folders such as the folder_name, the details of the user who created and last modified it, and the project details.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/folder 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status":"success",
"data":[
    {
        "folder_name":"ShipmentOrderForms",
        "created_time":"Oct 22, 2019 11:01 AM",
        "created_by":{
            "zuid":1019540152,
            "is_confirmed":true,
            "email_id":"emma@zylker.com",
            "first_name":"Amelia",
            "last_name":"Burrows",
            "user_type": "Admin",
            "user_id":671930455
        },
        "modified_time": "Jun 05, 2023 12:26 AM",
        "modified_by": {
            "zuid": 671930455,
            "is_confirmed": false,
            "email_id": "emma@zylker.com",
            "first_name": "Amelia",
            "last_name": "Burrows",
            "user_type": "Admin",
            "user_id": 671930455
        },
        "project_details":{
            "project_name":"ShipmentTracking",
            "id":4000000006007
        },
        "audit_consent": false,
        "id":105000000121098
    }
   {
        "folder_name":"PricingInfo",
        "created_time":"Sep 01, 2019 03:33 PM",
        "created_by":{
            "zuid":1019540152,
            "is_confirmed":true,
            "email_id":"p.boyle@zylker.com",
            "first_name":"Patricia",
            "last_name":"Boyle",
            "user_type": "Admin",
            "user_id":671930765
        },
        "modified_time": "Jun 05, 2023 12:26 AM",
        "modified_by": {
            "zuid": 671930455,
            "is_confirmed": false,
            "email_id": "p.boyle@zylker.com",
            "first_name": "Patricia",
            "last_name": "Boyle",
            "user_type": "Admin",
            "user_id": 671930765
        },
        "project_details":{
            "project_name":"ShipmentTracking",
            "id":4000000006007
        },
        "audit_consent": false,
        "id":105000000145678
    }
]

    

    }
    
    
         
    View more

    SDK Documentation
    Retrieve Folder Details- Java SDK

    Retrieve Folder Details- Node.js SDK

    Retrieve Folder Details- Python SDK

    Retrieve Folder Details- Web SDK

    Upload a File In a Folder

    Description

    This API enables you to upload a file from your local system to an existing folder in the File Store, by referring to the folder’s unique ID. You can upload an image, text document, CSV, or any type of file you need. The maximum size of a file that you can upload is 100 MB.

    You must specify the file path and the file name in the API request, as shown in the sample request.

    Note: Catalyst provides 1 GB of File Store space for each project in the development environment. There are no upper limits for storage in the production environment.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/folder/{folder_id}/file

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    folder_id
    Numerical
    The unique ID of the folder

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.files.CREATE

    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.

    Request JSON Properties

    code file
    mandatory

    Path of the file to be uploaded in your computer

    Maximum file size allowed: 100 MB

    file_name string
    mandatory
    Name of the file to be uploaded

    Response Details

    The JSON response returns the metadata of the file that was uploaded, such as the file_name, file_size, and the details of the user who uploaded the file.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/folder/105000000121098/file 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “content-type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F code=@/Desktop/EmployeeInfo.csv 
    
-F file_name=EmployeeInfo
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "id": 56000000368030,
    "file_location": null,
    "file_name": "EmployeeInfo",
    "file_size": 264328,
    "created_by": {
        "zuid": 1019540152,
        "is_confirmed": false,
        "email_id": "emma@zylker.com",
        "first_name": "Amelia",
        "last_name": "Burrows",
        "user_type": "Admin",
        "user_id": 64635102
    },
    "created_time": "Jun 05, 2023 12:40 AM",
    "modified_by": {
        "zuid": 1019540152,
        "is_confirmed": false,
        "email_id": "emma@zylker.com",
        "first_name": "Amelia",
        "last_name": "Burrows",
        "user_type": "Admin",
        "user_id": 64635102
    },
    "modified_time": "Jun 05, 2023 12:40 AM",
    "project_details": {
        "project_name": "EmployeePortal",
        "id": 3376000001796044,
        "project_type": "Live"
    },
    "folder_details": 3376000001925212
}

    

    }

    SDK Documentation
    Upload a File- Java SDK

    Upload a File- Node.js SDK

    Upload a File- Python SDK

    Upload a File- Web SDK

    Download a File From a Folder

    Description

    This API enables you to download a file from an existing folder in the File Store, by referring to the unique IDs of the folder and file.

    The file will be automatically downloaded to the configured directory in your system after you execute this API. Catalyst will not send any response back for this request.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/folder/{folder_id}/file/{file_id}/download

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    folder_id
    Numerical
    The unique ID of the folder
    file_id
    Numerical
    The unique ID of the file

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.files.READ

    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.
        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/folder/105000000121098/file/332000000044009/download 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: application/json”

    SDK Documentation
    Download a File- Java SDK

    Download a File- Node.js SDK

    Download a File- Python SDK

    Download a File- Web SDK

    Get the Details of a Specific File

    Description

    This API enables you to retrieve the details of a specific file in a folder in the File Store. The folder and the file are referred by their unique IDs.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/folder/{folder_id}/file/{file_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    folder_id
    Numerical
    The unique ID of the folder
    file_id
    Numerical
    The unique ID of the file

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.files.READ

    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.

    Response Details

    The response will return the metadata and details of the particular file including its file_name, file_size, and the details of the user who created and last modified the file.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/folder/105000000121098/file/332000000044009
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status":"success",
"data":{
  "id": 332000000044009,
  "file_location":null,
  "file_name":"Sales2019.csv",
  "file_size":264328,
  "created_by":{
    "zuid":1019540152,
    "is_confirmed":true,
    "email_id":"emma@zylker.com",
    "first_name":"Amelia",
    "last_name":"Burrows",
    "user_type": "Admin",
    "user_id":671930111
  },
  "created_time":"Apr 09, 2020 01:10 AM",
  "modified_by":{
    "zuid":1019540009,
    "is_confirmed":true,
    "email_id":"p.boyle@zylker.com",
    "first_name":"Patricia",
    "last_name":"Boyle",
    "user_type": "Admin",
    "user_id":671930989
  },
  "modified_time":"Mar 01, 2020 06:18 PM",
  "project_details":{
    "project_name":"ShipmentTracking",
    "id":4000000006007,
    "project_type": "Live"
  },
  "folder_details":105000000121098
  }
}

    Get the Details of Multiple Files

    Description

    This API enables you to retrieve the details of multiple files in a particular folder in the File Store. The folder is referred by its unique Folder ID.

    This API request can retrieve the details of a maximum number of 200 files in the folder in one call. Therefore, if a folder has 300 files, you can execute a second API call to retrieve the details of files 201 to 300. This can be done by specifying the start and end values in the query params in the request as depicted below. The first 200 files are retrieved by default, if the query params are not specified.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/folder/{folder_id}/file?start={start_index}&end={number_of_files}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    folder_id
    Numerical
    The unique ID of the folder
    start
    Numerical

    Start value of the current bundle

    end
    Numerical

    Number of files to be retrieved. The maximum value allowed is 200.

    For example, to retrieve the details of files 201 to 300, specify the start as ‘201’ and the end as ‘100’.

    Note: The start value must always be greater than 0.

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.files.READ

    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.

    Response Details

    The response will return the metadata and details of all the files that are returned, including their file_name, file_size, and the details of the user who created and last modified the file.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/folder/3376000000301993/file?start=201&end=2 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status":"success",
"data": [
    {
      "id":3376000000301234,
      "file_location":null,
      "file_name":"AuditLog.csv",
      "file_size":1621,
      "created_by": {
        "zuid":10016873924,
        "is_confirmed":true,
        "email_id":"emma@zylker.com",
        "first_name":"Amelia",
        "last_name":"Burrows",
        "user_type": "Admin",
        "user_id":671930400
      },
      "created_time":"Apr 27, 2020 07:37 PM",
      "modified_by": {
        "zuid":10016873924,
        "is_confirmed":true,
        "email_id":"p.boyle@zylker.com",
        "first_name":"Patricia",
        "last_name":"Boyle",
        "user_type": "Admin",
        "user_id":671938657
      },
      "modified_time":"Apr 27, 2020 07:37 PM",
      "project_details": {
        "project_name":"ShipmentTracking",
        "id": 4000000006007,
        "project_type": "Live"
      },
    "folder_details":3376000000301993
    },
    {
      "id":3376000000300987,
      "file_location":null,
      "file_name":"ZohoCatalyst-Pricing.pdf",
      "file_size":346466,
      "created_by": {
        "zuid":10016873924,
        "is_confirmed":true,
        "email_id":"emma@zylker.com",
        "first_name":"Ameila",
        "last_name":"Burrows",
        "user_type": "Admin",
        "user_id":671930400
      },
      "created_time":"Apr 27, 2020 07:36 PM",
      "modified_by": {
        "zuid":10016873924,
        "is_confirmed":true,
        "email_id":"p.boyle@zylker.com",
        "first_name":"Patricia",
        "last_name":"Boyle",
        "user_type": "Admin",
        "user_id":671938657
      },
      "modified_time":"Apr 27, 2020 07:36 PM",
      "project_details": {
        "project_name":"ShipmentTracking",
        "id":3376000000168765,
        "project_type": "Live"
      },
      "folder_details":3376000000301993
    }
  ]
}
    
    
         
    View more

    Delete a File

    Description

    This API is used to delete an existing file from a folder in the File Store, by referring to the Folder ID and File ID.

    Request Details

    Request URL

    DELETE

    {api-domain}/baas/v1/project/{project_id}/folder/{folder_id}/file/{file_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    folder_id
    Numerical
    The unique ID of the folder
    file_id
    Numerical
    The unique ID of the file

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.files.DELETE

    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.

    Response Details

    The response will return the metadata and details of the file that was deleted including its file_name, file_size, and the details of the user who created and last modified the file.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X DELETE 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/folder/105000000121098/file/4000000044001 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: application/json”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "id": 4000000044001,
    "file_location": null,
    "file_name": "bookingsSept2019.pdf",
    "file_size": 458186,
    "created_by": {
        "zuid": 671787990,
        "is_confirmed":true,
        "user_type": "Admin",
        "user_id": 671930400,
        "email_id": "emma@zylker.com",
        "first_name": "Amelia",
        "last_name": "Burrows"
    },
    "created_time": "2019-03-14T12:35:18+05:30",
    "modified_by": {
        "zuid": 671787990,
        "is_confirmed":true,
        "user_type": "Admin",
        "user_id": 671930400,
        "email_id": "emma@zylker.com",
        "first_name": "Amelia",
        "last_name": "Burrows"
    },
    "modified_time": "2019-03-14T12:35:18+05:30",
    "project_details": {
        "id": 4000000006007,
        "project_name": "ShipmentTracking",
        "project_type": "Live"
    },
    "folder_details": 105000000121098
}
}

    SDK Documentation
    Delete a File- Java SDK

    Delete a File- Node.js SDK

    Delete a File- Python SDK

    Delete a File- Web SDK

    Cache

    Catalyst Cache is a small in-memory storage component that enables you to store data that is frequently accessed by your Catalyst application.

    Catalyst cache is divided into partitions or cache units called segments. Each segment stores cache items in the form of key-value pairs.

    Insert a Key-Value Pair In a Cache Segment

    Description

    This API enables you to insert a key-value pair as the cache item in a cache segment. The segment is referred by its unique ID. The key represents the attribute and the value is the data of the cache item.

    You can also optionally specify the expiry time of the cache item. The default and maximum validity of a cache item is two days.

    Note:The cache segment must already be created. You can create a segment from the Catalyst console or use the default segment.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/segment/{segment_id}/cache

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    segment_id
    Numerical
    The unique ID of the cache segment

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.cache.CREATE

    Request JSON Properties

    cache_name string
    mandatory
    Key name of the cache segment
    Max Size: 50 characters
    cache_value string
    mandatory
    Data value the key represents
    Max Size: 16000 characters
    expiry_in_hours long
    optional
    Duration of expiry in hours
    Max Size: 48

    Response Details

    The response will return the details of the cache item such as the cache_name, cache_value and expires_in, along with the details of the segment it was inserted into.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/segment/3376000000425030/cache 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type:application/json” 
    
-d ‘{
“cache_name”:“counter”,
“cache_value”:“125”,
“expiry_in_hours”:24
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "cache_name": "counter",
    "cache_value": "125",
    "project_details": {
        "id": 4000000006007,
        "project_name": "ShipmentTracking",
        "project_type": "Live"
    },
    "segment_details": {
        "id": 3376000000425030,
        "segment_name": "CustomerLocation"
    },
    "expires_in": "Mar 28, 2019 02:03 AM",
    "expiry_in_hours": 24,
    "ttl_in_milliseconds": 86400000
}
}

    SDK Documentation
    Insert Key-Value Pair- Java SDK

    Insert Key-Value Pair- Node.js SDK

    Insert Key-Value Pair- Python SDK


    Get the Value of a Cache Key

    Description

    This API enables you to retrieve the value of a cache item from a segment in the cache. The segment is referred by its unique segment ID, and you must pass the key of the cache item in the request.

    This API enables you to insert a key-value pair as the cache item in a cache segment. The segment is referred by its unique ID. The key represents the attribute and the value is the data of the cache item.

    You can also optionally specify the expiry time of the cache item. The default and maximum validity of a cache item is two days.

    Request Details

    Request URL

    GET

    {api-domain}/baas/v1/project/{project_id}/segment/{segment_id}/cache?cacheKey={cache_key}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    segment_id
    Numerical
    The unique ID of the cache segment
    cache_key
    Numerical
    The unique key in a segment whose value needs to be retrieved

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.cache.READ

    Response Details

    The response will return the details of the cache item such as the cache_name, cache_value and expires_in, along with the details of its segment.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X GET  
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/segment/31000000006023/cache?cacheKey=counter 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "cache_name": "counter",
    "cache_value": "1344",
    "project_details": {
        "id": 4000000006007,
        "project_name": "ShipmentTracking",
        "project_type": "Live"
    },
    "segment_details": {
        "id": 31000000006023,
        "segment_name": "MailCounters"
    },
    "expires_in": "2019-03-13T18:36:02+05:30",
    "expiry_in_hours": 3,
    "ttl_in_milliseconds": 81187000
}

    

    }

    SDK Documentation
    Retrieve Data from Cache- Java SDK

    Retrieve Data from Cache- Node.js SDK

    Retrieve Data from Cache- Python SDK

    Update a Key-Value Pair

    Description

    This API enables you to update a key-value pair in a cache segment. The segment is referred by its unique ID. The key represents the attribute and the value is the data of the cache item.

    You can update the key, value, or the time of expiry of the cache item. The default and maximum validity of a cache item is two days.

    Request Details

    Request URL

    PUT

    {api-domain}/baas/v1/project/{project_id}/segment/{segment_id}/cache

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    segment_id
    Numerical
    The unique ID of the cache segment

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.cache.CREATE

    Request JSON Properties

    cache_name string
    mandatory
    Key name of the cache segment
    Max Size: 50 characters
    cache_value string
    mandatory
    Data value the key represents
    Max Size: 16000 characters
    expiry_in_hours long
    optional
    Duration of expiry in hours
    Max Size: 48

    Response Details

    The response will return the details of the updated cache item such as the cache_name, cache_value and expires_in, along with the details of its segment.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X PUT 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/segment/3376000000425030/cache 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type:application/json” 
    
-d ‘{
“cache_name”:“counter”,
“cache_value”:“1472”
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "cache_name": "counter",
    "cache_value": "1472",
    "project_details": {
        "id": 4000000006007,
        "project_name": "ShipmentTracking",
        "project_type": "Live"
    },
    "segment_details": {
        "id": 3376000000425030,
        "segment_name": "CounterValues"
    },
    "expires_in": "Mar 28, 2019 02:03 AM",
    "expiry_in_hours": 7,
    "ttl_in_milliseconds": 172800000
}

    

    }

    SDK Documentation
    Update Key-Value Pair- Java SDK

    Update Key-Value Pair- Node.js SDK

    Update Key-Value Pair- Python SDK

    ZCQL

    ZCQL is Catalyst’s own query language that enables you to perform data retrieval, insertion, updating, and deletion operations on the tables in the Catalyst Data Store.

    You can execute a variety of DML queries using ZCQL to obtain or manipulate data, and use various clauses and statements such as the SQL Join clauses, Groupby and OrderBy statements, and built-in SQL functions.

    Execute a ZCQL Query

    Description

    This API enables you to execute a ZCQL query to retrieve, insert, update, or delete data from the tables in the Data Store. You can execute this API by passing a ZCQL query in the JSON request, as shown in the sample requests.

    Note: The API request format is the same for all ZCQL query execution operations.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/query

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.zcql.CREATE

    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.

    Request JSON Properties

    query string
    mandatory
    The ZCQL query to be executed

    Response Details

    Data Retrieval Operations: The API returns the records that were fetched as a result of the query execution as the response.

    Data Insertion and Updating Operations: The API returns the records that were inserted or updated through the query as the response.

    Data Deletion Operations: The API returns the deleted row count.

        
    
        
    Sample Request: Data Retrieval
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/query 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: application/json” 
    
-d ‘{
“query”:“SELECT EmpID, EmpName, Department, Address from EmpDetails ORDER BY EmpID ASC LIMIT 1000,5”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Data Retrieval
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": [
    {
        "EmpDetails": {
            "CREATORID": "3376000000002003",
            "MODIFIEDTIME": "2023-06-05 15:09:33:881",
            "CREATEDTIME": "2023-06-05 15:09:33:881",
            "ROWID": "3376000001924975",
            "EmpID": "1001",
            "EmpName": "Allison Powell",
            "Department":"Marketing",
            "Address": "13, Winter Avenue, Philadelphia, PY"
        }
    },
    {
        "EmpDetails": {
            "CREATORID": "3376000000002003",
            "MODIFIEDTIME": "2023-06-05 15:09:33:881",
            "CREATEDTIME": "2023-06-05 15:09:33:881",
            "ROWID": "3376000001927682",
            "EmpID": "1002",
            "EmpName": "James Cortez",
            "Department":"HR",
            "Address": "25, Blossom Street, Austin, TX"
        }
    },
    {
        "EmpDetails": {
            "CREATORID": "3376000000002003",
            "MODIFIEDTIME": "2023-06-02 21:04:11:111",
            "CREATEDTIME": "2023-06-02 15:05:21:001",
            "ROWID": "3376000001224112",
            "EmpID": "1003",
            "EmpName": "Han Chan",
            "Department":"Sales",
            "Address": "112, St.Patrick's Road, Louisville, KY"
        }
    },
    {
        "EmpDetails": {
            "CREATORID": "337600000003111",
            "MODIFIEDTIME": "2023-06-02 21:04:11:111",
            "CREATEDTIME": "2023-06-02 15:05:21:001",
            "ROWID": "3376000001242012",
            "EmpID": "1004",
            "EmpName": "Rubella Miguel",
            "Department":"Accounts",
            "Address": "333, Marine Bay, Salt Lake City, UT"
        }
    },
    {
        "EmpDetails": {
            "CREATORID": "3376000000115254",
            "MODIFIEDTIME": "2023-04-12 21:04:10:521",
            "CREATEDTIME": "2023-06-11 15:05:02:541",
            "ROWID": "3376000001241341",
            "EmpID": "1005",
            "EmpName": "Ronwick Boseman",
            "Department":"Support",
            "Address": "61, Gringott's Avenue, Herfordshire, CO"
        }
    }
]

    

    }
    
    
         
    View more
    
    
    

        
    
        
    Sample Request: Data Insertion
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/query 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57 
    
-H “Content-Type: application/json” 
    
-d ‘{
“query”:“INSERT INTO EmpDetails VALUES (1007,‘Randy Marsh’,‘Sales’,‘42, Tenth Street, Jacksonville, FL’, ‘14 MAR 2017’)”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Data Insertion
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": [
  {
    "EmpDetails": {
      "CREATORID": "3813000000002003",
      "EmpID": "1007",
      "EmpName": "Randy Marsh",
      "Department":"Sales",
      "Address": "42, Tenth Street, Jacksonville, FL",
      "DOJ": "14 MAR 2017",
      "MODIFIEDTIME": "2021-08-04 09:10:14:752",
      "CREATEDTIME": "2021-08-04 09:10:14:752",
      "ROWID": "3813000000214001"
    }
  }
]

    

    }
    
    
         
    View more
    
    
    

        
    
        
    Sample Request: Data Updating
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/query 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57 
    
-H “Content-Type: application/json” 
    
-d ‘{
“query”:“UPDATE EmpDetails SET Department=‘Operations’ WHERE EmpID=1007”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Data Updating
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": [
  {
    "EmpDetails": {
      "CREATORID": "3813000000002003",
      "EmpID": "1007",
      "EmpName": "Randy Marsh",
      "Department":"Operations",
      "Address": "42, Tenth Street, Jacksonville, FL",
      "DOJ": "14 MAR 2017",
      "MODIFIEDTIME": "2021-08-04 09:11:54:318",
      "CREATEDTIME": "2021-08-04 09:10:14:752",
      "ROWID": "3813000000214001"
    }
  }
]

    

    }
    
    
         
    View more
    
    
    

        
    
        
    Sample Request: Data Deletion
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/query 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57 
    
-H “Content-Type: application/json” 
    
-d ‘{
“query”:“DELETE FROM EmpDetails WHERE EmpID=1007”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Data Deletion
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": [
  {
    "EmpDetails": {
      "DELETED_ROWS_COUNT": 1
    }
  }
]

    

    }
    
    
         
    View more

    SDK Documentation
    Execute ZCQL Query- Java SDK

    Execute ZCQL Query- Node.js SDK

    Execute ZCQL Query- Python SDK

    Execute ZCQL Query- Web SDK

    Search

    Catalyst Search enables data searching in the indexed columns of the tables in your Catalyst Data Store. When you integrate Search in your application, the end users will be able to perform powerful searches through volumes of data in your Data Store with a single search query.

    Execute Search Query

    Description

    This API enables you to execute a search operation in the indexed columns of all the tables in the Data Store. You can pass the search parameters in the request JSON. The records that match the search query are fetched as the response.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/search

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.search.READ

    Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.

    Request JSON Properties

    search string
    mandatory

    Search pattern that contains the keywords to search for

    You can provide multiple keywords separated by commas.

    search_table_columns json
    mandatory

    The indexed columns to be searched in a table

    You must provide this in the following format:

    {“table_name_1”: [“column_name_1”, “column_name_2”, “column_name_3”..], “table_name_2”: [“column_name_1”, “column_name_2”, “column_name_3”..]..}

    select_table_columns json
    optional

    The columns to be selected and displayed based on the search

    You must provide this in the following format:

    {“table_name_1”: [“column_name_1”, “column_name_2”, “column_name_3”..], “table_name_2”: [“column_name_1”, “column_name_2”, “column_name_3”..]..}

    order_by json
    optional

    Sorts the records fetched in the search results either in an ascending or descending manner

    Allowed Values: ASC, DESC

    start integer
    optional

    Starting index of a row where the search must begin

    Default value: 0

    end integer
    optional

    The offset value of a row where search must end

    Default value: 500

    Response Details

    The response returns the records that match the search query. The details of the rows including their metadata such as CREATORID and CREATEDTIME, and the column key names and values are returned.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/search 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: application/json” 
    
-d ‘{
“search” : “Mary”,
“search_table_columns” : {
“CustomerInfo”: [
“CustomerName”,
“TrainerName”
]
},
“start”:1000,
“end”:200
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "CustomerInfo": [
        {
            "CREATORID": "56000000002003",
            "MODIFIEDTIME": "2019-02-08 13:13:44",
            "CustomerName": "Mary Johnson",
            "TrainerName": "Helena Stewart",
            "CustomerID":"PL1213234",
            "CREATEDTIME": "2019-02-08 13:13:44"
        },
        {
            "CREATORID": "56000000002003",
            "MODIFIEDTIME": "2019-02-08 20:11:10",
            "CustomerName": "Mary Palmer",
            "TrainerName": "Ronald Wazlib",
            "CustomerID":"SY091834",
            "CREATEDTIME": "2019-02-08 20:11:10"
        },
       {
            "CREATORID": "56000000002003",
            "MODIFIEDTIME": "2019-11-09 10:00:12",
            "CustomerName": "Herbert Spielberg",
            "TrainerName": "Mary Amber Rogers",
            "CustomerID":"AL987627",
            "CREATEDTIME": "2019-11-08 00:12:40"
        }
    ]
}
}

    SDK Documentation
    Search Data- Java SDK

    Search Data- Node.js SDK

    Search Data- Python SDK

    Search Data- Web SDK

    Mail

    Catalyst Mail enables you to add the email addresses of your business that will be used to send emails to the end-users from your Catalyst application. You can configure email addresses of public domains or of your organization’s own domains. You can also use an external email client of your choice and configure its SMTP settings with Catalyst, instead of using the built-in Catalyst email client. You can perform these configurations from the console.

    Send Email

    Description

    This API enables you to send emails from a verified email address to the recipients you specify, from your Catalyst application.

    Catalyst enables you to set multiple email addresses as the receivers, and to CC, BCC, and reply to through a single send mail operation. You can also attach files in your email. The maximum supported limits for email recipients and file attachments in a single send mail operation are specified below:

    • To address: 10
    • CC: 10
    • BCC: 5
    • Reply to: 5
    • Number of file attachments: 5
    • Size of file attachments: 15 MB (through a single file or multiple files upto 5 files)

    You must pass the sender and receiver email addresses, the subject, content, and the attachments of the email as form-data in your API request. The keys to be passed as form-data, along with sample values are specified Form-Data Properties section below.

    Note: You must have configured and verified the sender’s email address in the Catalyst console to be able to send emails. If the sender’s email is hosted on a private domain or if you choose to use a third-party email client, you must configure them before sending emails as well.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/email/send

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.email.CREATE

    Form-Data Properties

    from_email
    mandatory
    The sender’s email address that is configured in Catalyst Mail
    to_email
    atleast one recipient mandatory
    Email addresses of the recipients
    cc
    optional
    Email addresses to carbon copy (cc)
    bcc
    optional
    Email addresses to blind carbon copy (bcc)
    reply_to
    optional
    Email addresses to reply to
    attachments
    optional
    The files to be attached in the email
    subject
    mandatory
    The subject of the email
    content
    optional
    The body of the email. You can pass the content in a HTML format by setting the html_mode as “True”.
    html_mode
    optional
    Specifies if the email content is in a HTML format. You must pass true or false as the value. If the value is false, the email content is in a regular text format.
    display_name
    optional
    The display name of the sender

    Response Details

    The response returns the details of the email that was sent such as the status of the sent email, the project details, from_email, to_email, and content.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/email/send 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” \
    

    -F from_email=emma@zylker.com \
-F to_email=vanessa.hyde@zoho.com,r.owens@zoho.com,chang.lee@zoho.com 
    
-F cc=p.boyle@zylker.com,robert.plant@zylker.com 
    
-F bcc=ham.gunn@zylker.com,rover.jenkins@zylker.com 
    
-F reply_to=peter.d@zoho.com,arnold.h@zoho.com 
    
-F attachments=kycform.pdf 
    
-F subject=“Greetings from Zylker Corp!” 
    
-F content="
    Hello,
    We’re glad to welcome you at Zylker Corp. To begin your journey with us, please download the attached KYC form and fill in your details. You can send us the completed form to this same email address. We cannot wait to get started!
    Cheers!
    Team Zylker
    " 
    
-F html_mode=true 
    
-F display_name=“Amelia Burrows” \
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
  "status": "success",
  "data": {
    "isAsync": false,
    "project_details": {
      "project_name": "Onboarding",
      "id": 2648000000235047,
      "project_type": "Live"
    },
    "display_name": "Amelia Burrows",
    "from_email": "emma@zylker.com",
    "to_email": [
      "vanessa.hyde@zoho.com", 
      "r.owens@zoho.com", 
      "chang.lee@zoho.com"
    ],
    "cc": [
      "p.boyle@zylker.com", 
      "robert.plant@zylker.com"
    ],
    "bcc": [
      "ham.gunn@zylker.com", 
      "rover.jenkins@zylker.com"
    ],
    "html_mode": true,
    "subject": "Greetings from Zylker Corp!",
    "content": "<p>Hello,</p><p>We're glad to welcome you at Zylker Corp. To begin your journey with us, please download thattached KYC form and fill in your details. You can send us the completed form to this same email address. We cannowait to get started!<p>Cheers!</p><p>Team Zylker </p>",
    "reply_to": [
      "peter.d@zoho.com", 
      "arnold.h@zoho.com"
    ]
  }
}

    SDK Documentation
    Send Email- Java SDK

    Send Email- Node.js SDK

    Send Email- Python SDK

    Push Notifications

    Push notifications are remote notifications that an application provider can send to the users of their application, even when the application is not actively running on the user device. Catalyst provides you with an easy way to integrate push notifications into your Catalyst web and iOS applications.

    Note: Catalyst Push Notifications is currently not available to users accessing from the EU, AU, IN, or CA data centers.

    Send Web Push Notifications

    Description

    This API is used to send text push notifications to the users of your web application for testing, after you enable push notifications for it. You can enable push notifications and also register client devices for receiving push notifications by implementing the web script mentioned in this Web SDK help page. You can then use this API to send push notifications.

    You can pass the push notification message and a list of the recipients in your API request as shown in the sample request.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/project-user/notify

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Note: Catalyst does not authenticate this API request. Therefore, you need not pass an OAuth token.

    Scope

    ZohoCatalyst.notifications.web

    Request JSON Properties

    recipients string
    mandatory
    The email address or the user ID of the users that the push notification must be sent to
    message string
    mandatory
    The message content of the push notification in the text format

    Response Details

    The response returns the status of the sent notification as success or failed.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/3000000002001/project-user/notify 
    
-H “Content-Type: application/json” 
    
-d ‘{
“recipients”:[“rhonda.wilkins@zylker.com”,“isabella.j@zylker.com”,“harry.sandman@zylker.com”],
“message”:“Attention, new employees! Update your profile information in Zylker team app”
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": true
}

    SDK Documentation
    Send Push Notifications- Java SDK

    Send Push Notifications- Node.js SDK

    Send Push Notifications- Python SDK

    Register a Client for Push Notifications- Web SDK

    iOS Push Notifications

    Before you send push notifications for your iOS app, you must follow a set of steps to register your app with Apple, enroll for Catalyst push notifications, and register your device. You must implement the first five steps explained in the Push Notifications- iOS Implementation help section. This API request is the sixth step that enables you to register a device to send push notifications.

    After you execute the API request discussed on this page to register your device, you can send push notifications from your registered device for your app.

    Register Device for iOS Push Notifications

    Description

    This API enables you to register a device to send push notifications in your Catalyst iOS app when the user allows your permission request.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/push-notification/{app_id}/register

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    app_id
    Numerical
    The notificationAppID obtained from the AppConfigurationDevelopment.plist/ AppConfigurationProduction.plist file

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.notifications.mobile.register

    Request JSON Properties

    app_bundle_id string
    mandatory
    Denotes the unique ID of the app that you provided when you downloaded Catalyst iOS SDK
    device_token string
    mandatory
    Unique token obtained after registering the device for remote push notifications with APNS
    test_device boolean
    optional

    Specifies if it is a test device. If the value is not provided, it will be considered as a production device by default
    Accepted values: true, false

    os_version string
    mandatory
    Denotes the OS version of the device to be registered
    installation_id string
    mandatory
    Denotes the installation ID of the iOS app

    Response Details

    The response returns the status of the device registration as success or failed, and the data that was passed as JSON in the request.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/push-notification/12345678/register 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type:application/json” 
    
-d ‘[
{
“app_bundle_id”:“com.domain.appname”,
“device_token”:“e5fr218a911sa21”,
“test_device”:“true”
“os_version” : “17.0.1”
“installation_id” : “4FG1HA12-8JL3-J81A-7HAOPR1AF91D”
}
]’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": [
    {
     "app_bundle_id":"com.domain.appname",
     "device_token":"e5fr218a911sa21", 
     "test_device":"true"
     "os_version" : "17.0.1"
     "installation_id" : "4FG1HA12-8JL3-J81A-7HAOPR1AF91D"
    }
]

    

    }

    SDK Documentation
    Register Device for Push Notifications- iOS SDK

    Send iOS Push Notifications

    Description

    This API is used to send text push notifications to the user devices from your iOS app for testing, after you register your app with Apple, enroll for Catalyst push notifications, and register your device. You must implement the first five steps explained in the Push Notifications- iOS Implementation help section and the sixth step from the section above.

    You can pass the push notification message and a list of the recipients to send the push notifications to along with other details in your API request as shown in the sample request.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/push-notification/{app_id}/project-user/notify

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    app_id
    Numerical
    The notificationAppID obtained from the AppConfigurationDevelopment.plist/ AppConfigurationProduction.plist file

    Request Headers

    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Note: Catalyst does not authenticate this API request. Therefore, you need not pass an OAuth token.

    Scope

    ZohoCatalyst.notifications.mobile

    Request JSON Properties

    recipients string
    mandatory
    The email address of the users that the push notification must be sent to
    push_details json
    mandatory

    The JSON that contains the details of the push notification content and metadata

    message string
    mandatory
    The text content of the push notification
    Max Size: 100 characters
    additional_info json
    optional
    Any additional information that you need to send in the form of “sample_key” : “sample_value”
    Max Size: 100 characters
    badge_count integer
    optional
    The count to be displayed over the app’s icon
    reference_id string
    optional
    The ID for reference
    expiry_time integer
    optional
    The time of expiry of the notification in hours

    Response Details

    The response returns the status of the sent notification as success or failed, and the data that was passed including message and expiry_time.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/204000000024010/push-notification/204000000036005/project-user/notify 
    
-H “Content-Type: application/json” 
    
-d ‘{
“recipients”:[“amanda.boyle@zylker.com”,“henry.mj@zylker.com”],
“push_details”:{
“message”:“Welcome to Zylker App!”,
“badge_count”:10,
“expiry_time”:12,
“additional_info”:{
“sample_key” : “sample_value”
}
}
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "recipients": ["amanda.boyle@zylker.com","henry.mj@zylker.com"],
    "push_details": {
        "message": "Welcome to Zylker App!",
        "additional_info": {
            "sample_key": "sample_value"
        },
        "badge_count": 10,
        "reference_id": null,
        "expiry_time": 12
    }
}
}

    SDK Documentation
    Send Push Notifications- Java SDK

    Send Push Notifications- Node.js SDK

    Send Push Notifications- Python SDK

    Register Device for Push Notifications- iOS SDK

    Deregister Device for iOS Push Notifications

    Description

    This API enables you to deregister a device that was registered to send push notifications from your Catalyst iOS app. After the device is deregisterd, you will need to register it again to send push notifications.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/push-notification/{app_id}/unregister

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    app_id
    Numerical
    The notificationAppID obtained from the AppConfigurationDevelopment.plist/ AppConfigurationProduction.plist file

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.notifications.mobile.register

    Request JSON Properties

    app_bundle_id string
    mandatory
    Denotes the unique ID of the app that you provided when you downloaded Catalyst iOS SDK
    device_token string
    mandatory
    Unique token obtained after registering the device for remote push notifications with APNS
    test_device boolean
    optional

    Specifies if it is a test device. If the value is not provided, it will be considered as a production device by default
    Accepted values: true, false

    os_version string
    mandatory
    Denotes the OS version of the device that was registered
    installation_id string
    mandatory
    Denotes the installation ID of the iOS app

    Response Details

    The response returns the status of the device deregistration as success or failed, and the data that was passed as JSON in the request.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/push-notification/12345678/unregister 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type:application/json” 
    
-d ‘[
{
“app_bundle_id”:“com.domain.appname”,
“device_token”:“e5fr218a911sa21”,
“test_device”:“true”
“os_version” : “17.0.1”
“installation_id” : “4FG1HA12-8JL3-J81A-7HAOPR1AF91D”
}
]’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": [
    {
     "app_bundle_id":"com.domain.appname",
     "device_token":"e5fr218a911sa21", 
     "test_device":"true"
     "os_version" : "17.0.1"
     "installation_id" : "4FG1HA12-8JL3-J81A-7HAOPR1AF91D"
    }
]

    

    }

    SDK Documentation
    Deregister Device for Push Notifications- iOS SDK

    Optical Character Recognition

    Zia Optical Character Recognition electronically detects textual characters in images or digital documents, and converts them into machine-encoded text. Zia OCR can recognize text in 10 major languages.

    Note: Catalyst does not store any of the files you upload in its systems. The files you upload are used for one-time processing only. They are not used for ML model training purposes either. Catalyst components are fully compliant with all applicable data protection and privacy laws.

    Execute OCR

    Description

    This API is used to detect textual characters in images and documents, and deliver the recognized text as a JSON response. The response also contains a confidence score, which defines the accuracy of the detection.

    You must specify the path to the image or document file in the API request, as shown in the sample request. You can optionally specify the languages present in the text, for quicker processing. OCR supports 9 international languages and 10 Indian languages, that are mentioned in the tables below. The language is automatically detected and the text is processed, if it is not specified.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/ocr

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    image file
    mandatory

    The input file to be processed. You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png, .bmp, .tiff, .pdf

    File size limit: 20 MB

    language string
    optional
    The language code of the text to be identified. Refer the tables below for the language codes.

    International Languages Supported by OCR

    Language Language Codes
    Arabic ara
    Chinese chi_sim
    French fra
    Italian ita
    Japanese jpn
    Portuguese por
    Romanian ron
    Spanish spa

    Indian Languages Supported by OCR

    Language Language Codes
    English eng
    Hindi hin
    Bengali ben
    Marathi mar
    Telugu tel
    Tamil tam
    Gujarati guj
    Urdu urd
    Kannada kan
    Malayalam mal
    Sanskrit san

    Response Details

    The response returns the data of the OCR processing, which includes the text that was recognized from the input in the text key and the confidence score of the recognition in the confidence key.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/ocr
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F “image=/Desktop/HelplineCard.jpg”  
    
-F “language=eng,spa”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status":"success",
"data": {
	"confidence":79.71514892578125,
	"text":"Whenever you\nneed to talk,\nwe‘re open\n\n[—] text eseses\n[J] KidsHelpPhone.ca\n\n(@, call 1—800—663—6868 Kids Help Phone ©"
}	
}

    SDK Documentation
    Add New User- Java SDK

    Add New User- Node.js SDK

    Add New User- Python SDK

    AutoML

    Zia AutoML enables you to train models and analyze a set of training data to predict the outcome of a subset of that data. You can build and train Binary Classification, Multi-Class Classification, and Regression Models, and obtain insightful evaluation reports.

    Note: AutoML is currently not available to Catalyst users accessing from the EU, AU, IN, or CA data centers.

    Execute AutoML

    Description

    This API is used to pass input for an AutoML model’s prediction as key-value pairs. You must pass the data in a JSON format in the request as described below.

    Note:

    • The AutoML model must already be created. You can create and configure a model from the console.
    • You can specify the target column, or the column in the dataset whose value needs to be predicted, while configuring the model from the console.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/automl/model/{model_id}

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    model_id
    Numerical
    The unique ID of the model

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Format

    You must send the column names and the corresponding column values in a JSON format like this:

        
    
        
    copy
    
        
    
            
    
        
    
    
    
    
    
         
    {
“column1_name”: “column1_value”,
“column2_name”: “column2_value”,
“column3_name”: “column3_value”
}

    where column_name is a key in the dataset required for predicting the target, and column_value is the data you provide for the corresponding column.


    Note:

    • If you enter a value in a format that does not match the data type of the column, such as a numerical value for the date type, the value will not be parsed. Ensure that you provide the data in the right format.

    • You must provide the value for atleast one valid column while testing the prediction.

    • If you don’t enter the value for an input field, a default value will be entered for the column by Zia automatically. However, this will affect the accuracy of the prediction.

    Response Details

    The response returns the data of the OCR processing, which includes the text that was recognized from the input in the text key and the confidence score of the recognition in the confidence key.

        
    
        
    Sample Request: Regression Model
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/automl/model/105000000124001
-H “Authorization: Zoho-oauthtoken 1000.8cb99d**********************9be93.9b8***********************f” 
    
-H “Content-Type: application/json” 
    
-d ‘{
“country”: “Armenia”,
“year”: “2016”,
“sex”: “female”,
“age”: “25-34”,
“population”: “277452”,
“GDP_for_year”: “10,546,135,160”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Regression Model
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status":"success",
"data":{
  "regression_result":3.41
}

    

    }
    
    
         
    View more
    
    
    

        
    
        
    Sample Request: Binary-class classification model
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/automl/model/105000000124001 
    
-H “Authorization: Zoho-oauthtoken 1000.8cb99d********************9be93.9b8********************f” 
    
-H “Content-Type: application/json” 
    
-d ‘{
“year_film”: “2019”,
“year_award”: “2020”,
“ceremony”: “77”,
“category”: “Best Director - Motion Picture”,
“nominee”: “Todd Phillips”,
“film”: “Joker”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Binary-class classification model
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status":"success",
"data":{
  "classification_result": {
    "True":20,
    "False":80
  }
}
}
    
    
         
    View more
    
    
    

        
    
        
    Sample Request: Multi-class classification model
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/automl/model/105000000124001 
    
-H “Authorization: Zoho-oauthtoken 1000.8cb99d******************9be93.9b8******************f” 
    
-H “Content-Type: application/json” 
    
-d ‘{
“Transaction_date”: “1/2/09 4:53”,
“Product”: “RAM”,
“Price”: “120”,
“City”: “Parkville”,
“State”: “MO”,
“Country”: “United States”,
“Account_Created”: “12/4/08 4:42”,
“Last_Login”: “1/2/09 7:49”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Multi-class classification model
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status":"success",
"data":{
  "classification_result": {
    "Amex":10,
    "Diner":20,
    "Mastercard": 30,
    "Visa":40
  }
}

    

    }
    
    
         
    View more

    SDK Documentation
    AutoML- Java SDK

    AutoML- Node.js SDK

    AutoML- Python SDK

    Face Analytics

    Zia Face Analytics performs facial detection in images, and analyzes the facial features to provide information such as the gender, age, and emotion of the detected faces.

    Face Analytics also provides the confidence levels of each attribute prediction that enables you to make informed decisions. It can detect up to 10 faces in an image, and it provides predictions of the attributes for each detected face.

    Execute Face Analytics

    Description

    You can use this API to perform facial detection and analytics in an image file, and specify the path to it in the API request as shown in the sample request.

    You can optionally specify an analysis mode which determines the number of facial landmarks to be detected in a face. You can also enable or disable the attributes to be predicted, such as the emotion, age, and gender.

    This API is used to pass input for Face Analytics prediction. You must pass an input image file and the data in a JSON format in the request as described below.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/faceanalytics

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    image file
    mandatory

    The input file to be processed. You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png
    File size limit: 10 MB

    mode string
    optional

    Denotes the number of facial landmarks to be detected in a face

    Allowed values: basic, moderate, advanced
    Default value: advanced

    • basic: 0-point landmark detector that detects the boundary of the face alone
    • moderate: 5-point landmark detector that detects- Eyes: The center of both eyes, Nose: Nose tip, Lips: The center of both lips
    • advanced: 68-point landmark detector that detects- Jawline: Face boundary, Eyebrows: Left and right eyebrow, Eyes: Left and right eye, Nose bridge, Nostril line, Upper lips: Upper and lower edge, Lower lips: Upper and lower edge
    emotion boolean
    optional

    Allowed values:

    false: Emotion will not be detected
    true: Emotion will be detected

    Default value: true

    age boolean
    optional

    Allowed values:

    false: Age will not be detected
    true: Age will be detected

    Default value: true

    gender boolean
    optional

    Allowed values:

    false: Gender will not be detected
    true: Gender will be detected

    Default value: true

    Response Details

    The response returns the details of the facial landmarks of the detected faces, and the predictions for emotion, age, and gender, based on the parameters and mode set in the API request in the data key.

    The overall probability of the co-ordinates of the facial landmark detection, and the probability of the predictions made for the emotion, age, and gender parameters will be returned as confidence scores.

        
    
        
    Sample Request: Basic
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/faceanalytics 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F “image=/Desktop/SampleImage.jpg” 
    
-d ‘{
“mode”: “basic”,
“emotion”: “true”,
“age”: “true”,
“gender”: “true”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Basic
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "faces": [
        {   
            "confidence": 1.0,
            "id": 0,
            "co_ordinates": [
                267,
                39,
                153,
                227
            ],
            "emotion": {
                "prediction": "not_smiling",
                "confidence": {
                    "smiling": "0.0",
                    "not_smiling": "1.0"
                }
            },
            "age": {
                "prediction": "3-9",
                "confidence": {
                    "0-2": "0.005",
                    "10-19": "0.33",
                    "20-29": "0.12",
                    "3-9": "0.509",
                    "30-39": "0.032",
                    "40-49": "0.003",
                    "50-59": "0.0",
                    "60-69": "0.0",
                    ">70": "0.0"
                }
            },
            "gender": {
                "prediction": "female",
                "confidence": {
                    "female": "0.92",
                    "male": "0.08"
                }
            }
        }
    ]
}

    

    }
    
    
         
    View more
    
    
    

        
    
        
    Sample Request: Moderate
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/faceanalytics 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F “image=/Desktop/SampleImage.jpg” 
    
-d ‘{
“mode”: “moderate”,
“emotion”: “false”,
“age”: “false”,
“gender”: “true”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Moderate
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "faces": [
        {
            "confidence": 1.0,
            "id": 0,
            "co_ordinates": [
                267,
                39,
                153,
                227
            ],
            "landmarks": {
                "left_eye": [337,135],
                "right_eye": [400,130],
                "nose": [
                    400,
                    165
                ],
                "mouth_left": [
                    353,
                    217
                ],
                "mouth_right": [
                    404,
                    211
                ]
            },
            "gender": {
                "prediction": "female",
                "confidence": {
                    "female": "0.92",
                    "male": "0.08"
                }
            }
        }
    ]
}

    

    }
    
    
         
    View more
    
    
    

        
    
        
    Sample Request: Advanced
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/faceanalytics 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F “image=/Desktop/SampleImage.jpg” 
    
-d ‘{
“mode”: “advanced”,
“emotion”: “true”,
“age”: “false”,
“gender”: “false”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Advanced
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "faces": [
        {
            "co_ordinates" : [ 185, 96, 275, 18],
            "confidence" : 0.99
            "landmarks" : {
                'mouth': [
                    [259, 440],
                    [287, 423],
                    [312, 413],
                    [325, 418],
                    [338, 414],
                    [354, 424],
                    [368, 442],
                    [355, 461],
                    [339, 470],
                    [325, 472],
                    [310, 470],
                    [285, 460],
                    [269, 440],
                    [311, 435],
                    [324, 436],
                    [338, 436],
                    [359, 442],
                    [339, 440],
                    [326, 441],
                    [312, 439]
                ],
                'right_eyebrow': [
                    [189, 245], 
                    [216, 230], 
                    [244, 227], 
                    [273, 234], 
                    [301, 248]
                ],
                'left_eyebrow': [
                    [356, 249], 
                    [379, 238], 
                    [401, 232], 
                    [422, 235], 
                    [436, 252]
                ],
                'right_eye': [
                    [225, 288],
                    [245, 281],
                    [265, 282],
                    [280, 295],
                    [263, 297],
                    [244, 297]
                ],
                'left_eye': [
                    [358, 299],
                    [376, 288],
                    [393, 290],
                    [408, 298],
                    [393, 305],
                    [376, 304]
                ],
                'nose': [
                    [329, 287],
                    [331, 311],
                    [334, 336],
                    [337, 360],
                    [301, 385],
                    [315, 389],  
                    [329, 392],
                    [341, 390],
                    [352, 385]
                ],
                'jaw': [
                    [131, 283],
                    [136, 340], 
                    [145, 393],
                    [158, 442],
                    [180, 484],
                    [212, 513],
                    [250, 530],
                    [287, 542],
                    [319, 545],
                    [347, 535],
                    [370, 512],
                    [393, 487],
                    [411, 456],
                    [423, 419],
                    [432, 381],
                    [437, 342],
                    [439, 303]
                ]
            },
            "emotion": {
                "prediction": "not_smiling",
                "confidence": {
                    "smiling": "0.0",
                    "not_smiling": "1.0"
                }
            }
        }
    ]
}

    

    }
    
    
         
    View more

    SDK Documentation
    Face Analytics- Java SDK

    Face Analytics- Node.js SDK

    Face Analytics- Python SDK

    Image Moderation

    Zia Image Moderation detects and recognizes inappropriate and unsafe content in images. The criteria include suggestive or explicit racy content, nudity, violence, gore, bloodshed, and the presence of weapons and drugs.

    Execute Image Moderation

    Description

    This API recognizes the following inappropriate content in images and returns them in the response: racy, weapon, nudity, gore, drug. The response also contains the probability of each criteria with their confidence scores, and the prediction of the image being safe_to_use or unsafe_to_use.

    You must specify the path of the image in the API request, as shown in the sample request. You can also optionally set the moderation mode for the request.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/imagemoderation

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    image file
    mandatory

    The input file to be processed. You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png
    File size limit: 10 MB

    mode string
    optional

    Denotes the moderation mode

    Allowed values: basic, moderate, advanced
    Default value: advanced

    • basic: Detects nudity alone
    • moderate: Detects nudity and racy content
    • advanced: Detects all criteria mentioned in the description

    Response Details

    The response will contain the probability of the parameters detected, based on the mode set in the API request. Based on an aggregate of the detected parameters, it will also include the prediction of the image being safe or unsafe to use, along with a confidence score of the prediction.

        
    
        
    Sample Request: Basic
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/imagemoderation
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F “image=/Desktop/SampleImage.jpg”  
    
-d ‘{
“mode”: “basic”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Basic
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"probability": {
"nudity": "1.0"
},
"confidence": 1,
"prediction": "unsafe_to_use"
}
    
    
         
    View more
    
    
    

        
    
        
    Sample Request: Moderate
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/imagemoderation 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F “image=/Desktop/SampleImage.jpg”  
    
-d ‘{
“mode”: “moderate”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Moderate
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"probability": {
"racy": "0.0",
"nudity": "0.0"
},
"confidence": 0.9,
"prediction": "safe_to_use"
}

    
    
         
    View more
    
    
    

        
    
        
    Sample Request: Advanced
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/imagemoderation 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F “image=/Desktop/SampleImage.jpg”  
    
-d ‘{
“mode”: “advanced”
}’
    
    
         
    View more
    
    
    

        
    
        
    Sample Response: Advanced
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"probability": {
"racy": "0.0",
"weapon": "1.0",
"nudity": "0.0",
"gore": "0.0",
"drug": "0.0"
},
"confidence": 1,
"prediction": "unsafe_to_use"
}
    
    
         
    View more

    SDK Documentation
    Image Moderation- Java SDK

    Image Moderation- Node.js SDK

    Image Moderation-Python SDK

    Object Recognition

    Zia Object Recognition detects, locates, and recognizes individual objects in an image file. It can identify 80 different kinds of common objects from images. Zia can recognize 80 kinds of specific object types, some of which include: person, car, dog, chair, traffic light, knife, umbrella, and cellphone.

    Execute Object Recognition

    Description

    This API is used to detect, locate, and recognize individual objects in an image file. The response returns the coordinates of each detected object in the image, its type, and the confidence score of each recognition.

    You must specify the path to the image file in the API request, as shown in the sample request.

    Request Details

    Request URL

    POST

    http://api.catalyst.zoho.com/baas/v1/project/{project_id}/ml/detect-object

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    image file
    mandatory

    The image file that is to be processed for object recognition. You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png
    File size limit: 10 MB

    Response Details

    The response will contain the details of each individual object detected, which includes its co_ordinates, object_type, and the confidence score of the detection.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/56000000405001/ml/detect-object 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F image=/Desktop/SampleImage.jpg \
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status":"success",
"data":{
    "objects":[
        {
            "co_ordinates":[
                37,
                94,
                704,
                434
            ],
            "object_type":"dog",
            "confidence":"98.92"
        },
       {
            "co_ordinates":[
                20,
                67,
                202,
                120
            ],
            "object_type":"umbrella",
            "confidence":"97.05"
        }
    ]
}

    

    }

    SDK Documentation
    Object Recognition- Java SDK

    Object Recognition- Node.js SDK

    Object Recognition- Python SDK

    Barcode Scanner

    Zia Barcode Scanner enables you to scan the most commonly used linear and 2D barcode formats and decode the encoded data. Barcode Scanner can detect formats like Codabar, EAN-13, ITF, UPC-A, QR Code, and more.

    Execute Barcode Scanner

    Description

    This API is used to decode the data encoded in a barcode from an image file. You must specify the path to the image file in the API request, as shown in the sample request.

    You can optionally specify the barcode format. If you don’t specify it, Catalyst will automatically process the default value all for it. The JSON response returns the decoded data.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/barcode

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    image file
    mandatory

    The input file with the barcode to be scanned. You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png
    File size limit: 10 MB
    Resolution limit: 36000000 pixels

    format string
    optional

    The format of the barcode in the image. The format codes are specified in the table below.

    You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png
    File size limit: 10 MB

    Barcode Format Codes

    Barcode Format Format Code
    Code 39 code39
    Code 128 code128
    Code 93 code93
    Ean 8 ean8
    Ean 13 ean13
    Codabar codabar
    ITF itf
    UPC-A upca
    UPC-E upce
    RSS rss
    QR code qrcode
    Aztec aztec
    PDF417 pdf417
    Data Matrix datamatrix
    If you don't know the format
    or if you don't specify it    		 all

    Response Details

    The response will contain the data detected in the barcode in the content field.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/ocr 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F “image=/Desktop/SampleImage.jpg”  
    
-d ‘{
“format”: “ITF”
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
	"status": "success",
	"data": {
		"content": "40156"
	}
}

    SDK Documentation
    Barcode Scanner- Java SDK

    Barcode Scanner- Node.js SDK

    Barcode Scanner- Python SDK

    Identity Scanner

    Identity Scanner is a Zia AI-driven component that enables you to perform secure identity checks on individuals and documents by scanning and processing various ID proofs or official documents. It is a comprehensive suite that incorporates multiple functionalities divided into two major categories- E-KYC and Document Processing.

    Note: Catalyst does not store any of the files you upload in its systems. The documents you upload are used for one-time processing only. They are not used for ML model training purposes either. Catalyst components are fully compliant with all applicable data protection and privacy laws.

    Facial Comparison

    Facial Comparison, also known as E-KYC, is a part of Identity Scanner that compares two faces in two different images to determine if they are the same individual.

    Note: While the Document Processing feature of Identity Scanner is only relevant to Indian users, the Facial Comparison API and SDK tools are available to a global audience. However, accessing and testing Facial Comparison or E-KYC from the Catalyst console is restricted to the users from IN DC alone.

    Process Facial Comparison

    Description

    This API enables you to perform a face comparison between a source image and a query image. You must specify the paths to both the image files in the API request, as shown in the sample request.

    Note: You can mark either the ID proof image or the individual’s photograph as the source or the query image. This will not affect the results.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/facecomparison

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    source_image file
    mandatory

    The photo ID or an individual’s photograph. You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png
    File size limit: 10 MB

    query_image file
    mandatory

    The photo ID or an individual’s photograph. You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png
    File size limit: 10 MB

    Response Details

    The response returns the result of comparison as true if the faces match, or false if they don’t match.

    The response also contains a confidence score between the range of 0 to 1. Only if the comparison yields a confidence score of above 50% i.e., 0.5, the result will be set to true.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/facecomparison 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F source_image=/Desktop/SourceImage.jpg 
    
-F query_image=/Desktop/QueryImage.jpg
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
    "status": "success",
    "data": {
        "confidence": 1.0,
        "matched": "true"
    }
}

    SDK Documentation
    Facial Comparison- Java SDK

    Facial Comparison- Node.js SDK

    Facial Comparison- Python SDK

    Aadhaar

    The AADHAAR model is a part of the Document Processing feature of Identity Scanner that enables you to process Indian Aadhaar cards as identity proof documents.

    Note:

    • Catalyst does not store any of the files you upload in its systems. The documents you upload are used for one-time processing only. They are not used for ML model training purposes either. Catalyst components are fully compliant with all applicable data protection and privacy laws.

    • Document Processing is only relevant to Indian users and is only available in the IN DC. This feature will not be available to users accessing from the EU, AU, US, or CA data centers. Users outside of India from the other DCs can access the general OCR component to read and process textual content.

    Process Aadhaar

    Description

    This API extracts fields of data from an Indian Aadhaar card using an advanced OCR technology. The JSON response will return the parameters recognized from the Aadhaar card, along with confidence scores for each recognition that determine their accuracy. You must provide the path to the image files of the front and back of the Aadhaar card, and specify the model type as AADHAAR in the API request.

    Note: The option to pass the languages present in an Aadhaar card has now been deprecated. Identity Scanner will now automatically identify the languages in an Aadhaar card and process it. The API will be updated accordingly soon. You can temporarily pass the languages as shown in the sample request.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/ocr

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    aadhaar_front file
    mandatory

    The image of the front side of the Aadhaar card to be processed. You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png, .bmp, .tiff
    File size limit: 15 MB

    aadhaar_back file
    mandatory

    The image of the back side of the Aadhaar card to be processed.You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png, .bmp, .tiff
    File size limit: 15 MB

    model_type string
    mandatory

    The model type of the image

    Value to be passed: AADHAAR

    language string
    optional

    The language code of the language to be identified. The AADHAAR model supports the Indian languages listed in a table below.

    You must pass English and the relevant regional language alone for the AADHAAR type. For example, if you are from Tamil Nadu, you must pass tam and eng in the request.

    Languages Supported by the Aadhaar Model Type

    Language Language Codes
    English eng
    Hindi hin
    Bengali ben
    Marathi mar
    Telugu tel
    Tamil tam
    Gujarati guj
    Urdu urd
    Kannada kan
    Malayalam mal
    Sanskrit san

    Response Details

    The response contains the parameters recognized in the Aadhaar card such as the card holder’s name, address, gender, Aadhaar card number assigned to respective keys. The response also shows a confidence score in the range of 0 to 1 for each of the recognized values.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/ocr
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F aadhaar_front=/Desktop/Aadhaar1.jpg 
    
-F aadhaar_back=/Desktop/Aadhaar2.jpg 
    
-F model_type=AADHAAR 
    
-F “language=eng,tam”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
	"status":"success",
	"data":{
	"text": "{\"address\":{\"prob\":0.5,\"value\":\"S/O Tony, Seer 40, S/O Julie, 40, Dewdrops Street, Cherry Hill       Pondicherry, Pondicherry ureing4Gen, ureing4Gen 605008 \"},\"gender\":{\"prob\":\"0.9\",\"value\":\"male\"},\"dob\":  {\"prob\":\"0.6\", \"value\":\"12/12/2012\"},\"name\":{\"prob\":\"0.8\", \"value\":\"Hari Krishnan\"},\"aadhaar\":{\"prob\":0.8,\"value\":\"1234 5678 0123\"}}"
	}	
}

    SDK Documentation
    Identity Scanner: Aadhaar- Java SDK

    Identity Scanner: Aadhaar- Node.js SDK

    Identity Scanner: Aadhaar- Python SDK

    PAN

    The PAN model is a part of the Document Processing feature of Identity Scanner that enables you to process Indian PAN cards as identity proof documents.

    Note:

    • Catalyst does not store any of the files you upload in its systems. The documents you upload are used for one-time processing only. They are not used for ML model training purposes either. Catalyst components are fully compliant with all applicable data protection and privacy laws.

    • Document Processing is only relevant to Indian users and is only available in the IN DC. This feature will not be available to users accessing from the EU, AU, US, or CA data centers. Users outside of India from the other DCs can access the general OCR component to read and process textual content.

    Process PAN

    Description

    This API extracts fields of data from a PAN card using an advanced OCR technology, and returns the parameters recognized from the PAN card as a JSON response. You must provide the path to the image file of the front side of the PAN card containing personal details in the API request. You must specify the model type in the API request as PAN, to process the PAN card. The PAN model can only process text in English by default.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/ocr

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    image file
    mandatory

    The image of the front side of the PAN card. You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png
    File size limit: 15 MB

    model_type string
    mandatory

    The model type of the image

    Value to be passed: PAN

    Response Details

    The response will contain the parameters extracted from the PAN card such as their first name, last name, date of birth, and their PAN card number assigned to the respective keys.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/ocr 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F image=/Desktop/MyPan.jpg 
    
-F model_type=PAN
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "first_name": "KIRAN",
    "last_name": "RAO",
    "date_of_birth": "03/04/1982",
    "pan": "ANRPM2537J"

    }
}

    SDK Documentation
    Identity Scanner: PAN- Java SDK

    Identity Scanner: PAN- Node.js SDK

    Identity Scanner: PAN- Python SDK

    Passbook

    The PASSBOOK model is a part of the Document Processing feature of Identity Scanner that enables you to process Indian bank passbooks as financial or identity proof documents.

    Note:

    • Catalyst does not store any of the files you upload in its systems. The documents you upload are used for one-time processing only. They are not used for ML model training purposes either. Catalyst components are fully compliant with all applicable data protection and privacy laws.

    • Document Processing is only relevant to Indian users and is only available in the IN DC. This feature will not be available to users accessing from the EU, AU, US, or CA data centers. Users outside of India from the other DCs can access the general OCR component to read and process textual content.

    Process Passbook

    Description

    This API extracts fields of data from a passbook using the OCR technology and returns the parameters recognized from the passbook as a JSON response. You must provide the path to the image file of the front page of the bank passbook, and specify the model type as PASSBOOK in the API request.

    You can also optionally input the languages present in the passbook in the API request. The text recognition and extraction process is faster and more accurate if you specify the languages.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/ocr

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    image file
    mandatory

    The image of the front page of the passbook. You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png, .bmp, .tiff, .pdf
    File size limit: 15 MB

    model_type string
    mandatory

    The model type of the image

    Value to be passed: PASSBOOK

    language string
    optional

    The language code of the languages to be identified. You can pass multiple languages. The PASSBOOK model supports the Indian and international languages specified in the tables below.

    Default value: eng

    International Languages Supported by the Passbook Model Type

    Language Language Codes
    English eng
    Arabic ara
    Chinese chi_sim
    French fra
    Italian ita
    Japanese jpn
    Portuguese por
    Romanian ron
    Spanish spa

    Indian Languages Supported by the Passbook Model Type

    Language Language Codes
    Hindi hin
    Bengali ben
    Marathi mar
    Telugu tel
    Tamil tam
    Gujarati guj
    Urdu urd
    Kannada kan
    Malayalam mal
    Sanskrit san

    Response Details

    The response contains the bank details and account details recognized from the passbook such as the bank name, branch, address, account number. The extracted fields of information are assigned to their respective keys. The response also shows if RTGS, NEFT, and IMPS have been enabled for that account by returning true or false for those keys.

    Note: Identity Scanner will return the response only in English, irrespective of the languages present in the passbook.
        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/ocr 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F image=/Desktop/MyPassbook.pdf 
    
-F model_type=PASSBOOK 
    
-F “language=eng”
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    	{
	"status":"success",
	"data":{
	"text": "{\"address\":\"NO.20 ,SUNSHINE LANE,ANNA NAGAR,CHENNAI\",\"city\":\"CHENNAI\",\"centre\":\"CHENNAI\",\"bankName\":\"ABC BANK LIMITED\",\"accountNumber\":\"000000001111222\",\"branch\":\"ANNA NAGAR\",\"dateOfOpening\":\"30/08/2012\",\"imps\":\"true\",\"neft\":\"true\",\"district\":\"CHENNAI\",\"contact\":\"2891289\",\"micr\":\"0101010\",\"name\":\" 999919\",\"state\":\"TAMIL NADU\",\"rtgs\":\"true\",\"ifsc\":\"ABCB0000111\"}"
	}	
	}

    SDK Documentation
    Identity Scanner: Passbook- Java SDK

    Identity Scanner: Passbook- Node.js SDK

    Identity Scanner: Passbook- Python SDK

    Cheque

    The CHEQUE model is a part of the Document Processing feature of Identity Scanner that enables you to process Indian bank cheque leaves as identity proof documents.

    Note:

    • Catalyst does not store any of the files you upload in its systems. The documents you upload are used for one-time processing only. They are not used for ML model training purposes either. Catalyst components are fully compliant with all applicable data protection and privacy laws.

    • Document Processing is only relevant to Indian users and is only available in the IN DC. This feature will not be available to users accessing from the EU, AU, US, or CA data centers. Users outside of India from the other DCs can access the general OCR component to read and process textual content.

    Process Cheque

    Description

    This API extracts fields of data from a cheque using an advanced OCR technology, and returns the parameters recognized from the cheque as a JSON response. You must provide the path to the image file of a cheque leaf in the API request, and specify the model type as CHEQUE in the API request.

    The CHEQUE model can only process text in English by default. No other languages are supported.

    Note: Zia only processes cheques of the CTS-2010 format.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/ocr

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    image file
    mandatory

    The image of a bank cheque leaf. You must provide the path to it in your local system.

    Allowed formats: .jpg, .jpeg, .png
    File size limit: 15 MB

    model_type string
    mandatory

    The model type of the image

    Value to be passed: CHEQUE

    Response Details

    The response will contain the parameters extracted from the cheque, such as the amount, bank name, branch name, account number, IFSC code, assigned to the respective keys.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/ocr 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW” 
    
-F image=/Desktop/MyCheque.jpg 
    
-F model_type=CHEQUE \
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "amount": "50000",
    "branch_name": "ANNA NAGAR WEST",
    "bank_name": "STATE BANK OF INDIA",
    "account_number": "00001234556001",
    "ifsc": "SBIN0011724",
    "date": "25/09/2012"
}

    

    }

    SDK Documentation
    Identity Scanner: Cheque- Java SDK

    Identity Scanner: Cheque- Node.js SDK

    Identity Scanner: Cheque- Python SDK

    Text Analytics

    Text Analytics as a whole includes a combination of the following three features: Sentiment Analysis, Named Entity Recognition, and Keyword Extraction. You can perform all three actions on a specific block of text, and obtain the tone of the text, the categorizations of the entities recognized from it, and key words and phrases that provide a gist of the text.

    Execute All Text Analytics

    Description

    You can use this API to perform Sentiment Analysis, Named Entity Recognition, and Keyword Extraction on a block of text of upto 1500 characters. You can pass the text in the JSON body of the request, as shown in the sample request.

    You can also pass optional keywords to perform Sentiment Analysis on the sentences containing only those keywords.

    Note: Refer to the respective API pages of these features for detailed information about each of them.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/text-analytics

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    document string array
    mandatory
    The text to be processed for Sentiment Analysis, Named Entity Recognition, and Keyword Extraction
    keywords string array
    optional
    To perform Sentiment Analysis only on the sentences containing these keywords

    Response Details

    The response contains the results of each of the text analytics feature. Refer to the response details section of each feature individually for detailed information.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/text-analytics  
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: application/json” 
    
-d ‘{
“document”:"[Zoho Corporation is an Indian software development company. The focus of Zoho Corporation lies in web-based business tools and information technology.]"
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
      {
  "status":"success",
  "data":[
  {
  "keyword_extractor":{
  "keywords":[
  "focus"
  ],
  "keyphrases":[
  "Indian software development company",
  "Zoho Corporation",
  "web - based business tools",
  "information technology"
  ]
  },
  "sentiment_prediction":[
  {
  "document_sentiment":"Neutral",
  "sentence_analytics":[
  {
  "sentence":"Zoho Corporation is an Indian software development company.",
  "sentiment":"Neutral",
  "confidence_scores":{
  "negative":0.0,
  "neutral":1.0,
  "positive":0.0
  }
  },
  {
  "sentence":"The focus of Zoho Corporation lies in web-based business tools and information technology.",
  "sentiment":"Neutral",
  "confidence_scores":{
  "negative":0.0,
  "neutral":1.0,
  "positive":0.0
  }
  }
  ],
  "overall_score":1.0
  }
  ],
  "ner":{
  "general_entities":[
  {
  "start_index":0,
  "confidence_score":99,
  "end_index":16,
  "ner_tag":"Organization",
  "token":"Zoho Corporation"
  },
  {
  "start_index":23,
  "confidence_score":99,
  "end_index":29,
  "ner_tag":"Miscellaneous",
  "token":"Indian"
  },
  {
  "start_index":73,
  "confidence_score":99,
  "end_index":89,
  "ner_tag":"Organization",
  "token":"Zoho Corporation"
  }
  ]
  }
  }
  ]
  }
    
    
         
    View more

    SDK Documentation
    Text Analytics: All Text Analytics- Java SDK

    Text Analytics: All Text Analytics- Node.js SDK

    Text Analytics: All Text Analytics- Python SDK

    Sentiment Analysis

    Zia Sentiment Analysis is a part of Text Analytics that processes textual content to recognize the tone of the message, and the sentiments conveyed through it. It analyses each sentence in the text to determine if its tone is Positive, Negative, or Neutral. It then determines the tone of the overall text as one of the these three sentiments, based on the sentiments recognized in each sentence.

    The response also returns the confidence scores for each sentence and the overall text, to showcase the accuracy of the analysis.

    Execute Sentiment Analysis

    Description

    You can use this API to perform Sentiment Analysis on a block of text of upto 1500 characters in a single request. You must pass the text in the JSON body of the request, as shown in the sample request.

    You can also pass optional keywords for the text. This will enable Sentiment Analysis to process only those sentences that contain these keywords, and determine their sentiments. Other sentences will be ignored.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/text-analytics/sentiment-analysis

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    document string array
    mandatory
    The text to be processed for Sentiment Analysis
    keywords string array
    optional
    To perform Sentiment Analysis only on the sentences containing these keywords

    Response Details

    The response contains the result of individual sentence analysis and the overall text analysis as Positive, Negative, or Neutral, along with the overall confidence score of each analysis. The confidence score lies in the range of 0 to 1.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/text-analytics/sentiment-analysis
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: application/json” 
    
-d ‘{“document”:"[I love the design of the new model.]",
“keywords”:"[design]"
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
      {
  "status":"success",
  "data":[
  {
  "sentiment_prediction":[
  {
  "document_sentiment":"Positive",
  "sentence_analytics":[
  {
  "sentence":"I love the design of the new model",
  "sentiment":"Positive",
  "confidence_scores":{
  "negative":0.0,
  "neutral":0.0,
  "positive":1.0
  }
  }
  ],
  "keyword":"design",
  "overall_score":1.0
  }
  ]
  }
  ]
  }

    SDK Documentation
    Text Analytics: Sentiment Analysis- Java SDK

    Text Analytics: Sentiment Analysis- Node.js SDK

    Text Analytics: Sentiment Analysis- Python SDK

    Named Entity Recognition

    Zia Named Entity Recognition is a part of Text Analytics that processes textual content to extract key words and group them into various categorizes. For example, it can determine a word in a text to be the name of an organization, the name of a person, or a date, and add it to the appropriate category accordingly. Refer here for a list of all categories recognized by NER.

    The response will return the details of all recognized entities, and a tag indicating the category they belong to. It will also contain the confidence score of each recognition to showcase its accuracy, and the locations of the entity in the text.

    Execute Named Entity Recognition

    Description

    You can use this API to perform named entity recognition on a block of text of upto 1500 characters in a single request. You can pass the text in the JSON body of the request, as shown in the sample request.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/text-analytics/ner

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    document string array
    mandatory
    The text to be processed for Named Entity Recognition

    Response Details

    The response returns an array of all the entities recognized in the text. The details of each entity recognition contains the tag of the entity’s categorization, such as ORG orMISC to indicate the name of an organization or a miscellaneous value respectively.

    The response also returns the location of each entity in the text through start_index and end_index, that indicate the start and end indices of the entity. The confidence score determined for each entity classification is represented in percentage values.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/text-analytics/ner  
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: application/json” 
    
-d ‘{
“document”:"[The biggest reason for me to love and remember this trek is the beautiful valley itself. Right from the entry, you can see a bed of pink alpine orchids, blue Himalayan poppies, yellow marigolds, and a whole variety of flowers spread out around you. The weather was also very pleasant that day, about 24 degree celsius, which made the experience all the more amazing.]"
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
        {
    "status": "success",
    "data": [
    {
    "ner": {
    "general_entities": [
    {
    "start_index": 21,
    "confidence_score": 100,
    "end_index": 25,
    "ner_tag": "Color",
    "token": "pink"
    }
    ]
    }
    },
    {
    "ner": {
    "general_entities": [
    {
    "start_index": 94,
    "confidence_score": 56,
    "end_index": 97,
    "ner_tag": "Duration",
    "token": "day"
    }
    ]
    }
    },
    {
    "ner": {
    "general_entities": []
    }
    },
    {
    "ner": {
    "general_entities": []
    }
    },
    {
    "ner": {
    "general_entities": [
    {
    "start_index": 0,
    "confidence_score": 100,
    "end_index": 6,
    "ner_tag": "Color",
    "token": "yellow"
    }
    ]
    }
    },
    {
    "ner": {
    "general_entities": [
    {
    "start_index": 6,
    "confidence_score": 100,
    "end_index": 15,
    "ner_tag": "Temperature",
    "token": "24 degree",
    "fine_entities": [
        {
            "start_index": 9,
            "end_index": 15,
            "ner_tag": "Fahrenhiet",
            "token": "degree"
        },
        {
            "start_index": 6,
            "end_index": 8,
            "ner_tag": "Value",
            "token": "24"
        }
    ]
    },
    {
    "start_index": 16,
    "confidence_score": 100,
    "end_index": 23,
    "ner_tag": "Unit_temperature",
    "token": "celsius"
    }
    ]
    }
    },
    {
    "ner": {
    "general_entities": [
    {
    "start_index": 5,
    "confidence_score": 61,
    "end_index": 14,
    "ner_tag": "Miscellaneous",
    "token": "Himalayan"
    },
    {
    "start_index": 0,
    "confidence_score": 100,
    "end_index": 4,
    "ner_tag": "Color",
    "token": "blue"
    }
    ]
    }
    }
    ]
    }

    
    
         
    View more

    SDK Documentation
    Text Analytics: Named Entity Recognition- Java SDK

    Text Analytics: Named Entity Recognition- Node.js SDK

    Text Analytics: Named Entity Recognition- Python SDK

    Keyword Extraction

    Zia Keyword Extraction is a part of Text Analytics that processes textual content and extracts the highlights of the text. The extracted terms are grouped into two categories: Keywords and Keyphrases. These highlights deliver a concise summary of the text and provide an abstraction of the whole text.

    Keyword Extraction is a highly useful feature if you want to skim through long textual content and just obtain the essential information and action items from it. You will be able to identify the subject matter and the gist of the text easily from the response, and save valuable time.

    Execute Keyword Extraction

    Description

    You can use this API to perform Keyword Extraction on a block of text of upto 1500 characters in a single request. You can pass the text in the JSON body of the request, as shown in the sample request.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/ml/text-analytics/keyword-extraction

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    content-type: application/json

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.mlkit.READ

    Request JSON Properties

    document string array
    mandatory
    The text to be processed for Keyword Extraction

    Response Details

    The response contains an array of the key words, and another array of the key phrases that are extracted from the text.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/text-analytics/keyword-extraction 
    
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
-H “Content-Type: application/json” 
    
-d ‘{
“document”:
“[Catalyst is a full-stack cloud-based serverless development tool, that provides backend functionalities to build applications and microservices on various platforms.]”
}’
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
        {
    "status": "success",
    "data": [
    {
    "keyword_extractor": {
    "keywords": [
    "microservices",
    "applications"
    ],
    "keyphrases": [
    "backend functionalities",
    "various platforms"
    ]
    }
    },
    {
    "keyword_extractor": {
    "keywords": [
    "Catalyst"
    ],
    "keyphrases": [
    "cloud-based serverless development tool"
    ]
    }
    }
    ]
    }

    SDK Documentation
    Text Analytics: Keyword Extraction- Java SDK

    Text Analytics: Keyword Extraction- Node.js SDK

    Text Analytics: Keyword Extraction- Python SDK

    Automation Testing

    Automation Testing is an API testing tool that automates the testing process of the APIs in your application. You can test the Basic I/O and Advanced I/O functions in your application, or any third-party URL, and obtain responses. You can write test cases based on your requirements, schedule tests to be executed automatically, and manage the entire process of API testing with minimal manual intervention.

    Note: Automation Testing is currently not available to Catalyst users accessing from the EU, AU, IN, or CA data centers.

    Execute a Test Plan

    Description

    A test plan enables the automated execution of one or more test suites in Automation Testing. This API enables you to trigger the execution of a test plan that is already configured in the remote console in your project. This is equivalent to the instant run option available for a test plan in the console.

    Request Details

    Request URL

    POST

    {api-domain}/baas/v1/project/{project_id}/automation-testing/{test_plan_id}/execute

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project
    test_plan_id
    Numerical
    The unique ID created for a test plan.

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Environment: Development

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZohoCatalyst.automationtesting.execute

    Response Details

    The response contains the status of the test plan execution, along with details such as the unique Run ID that will be generated for each automated or instant test plan execution, the Test Plan ID that was passed, and the is_schedule_started parameter that contains the status of the execution initiation as true or false.

        
    
        
    Sample Request
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST 
    
https://api.catalyst.zoho.com/baas/v1/project/3359000000016812/automation-testing/537000000022025/execute 
    
-H “Authorization: Zoho-oauthtoken 1000.25*************************e.3e*************************3” \
    
    
    
    

        
    
        
    Sample Response
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    {
"status": "success",
"data": {
    "id": 537000000034053,
    "test_plan_id": 537000000022025,
    "is_schedule_started": true
}
}

    Catalyst SmartBrowz

    Catalyst SmartBrowz is a Catalyst browser service that enables you to manage and control a remote browser in Catalyst’s cloud environment through a wide range of components. These include Headless components, Browser Logic function, Templates, and more.

    PDF & Screenshot

    PDF & Screenshot is a component of SmartBrowz that lets you generate visual documents of websites and web applications. It is a powerful tool that can be used to convert webpages to PDF, to use during UI debugging, and to understand visual components from end-users’ perspective, while implementing permitted crawling operations, just to name a few.

    You can introduce this functionality in your Catalyst application using the API below.

    Generate PDF Using HTML/URL

    PDF Description

    You can use this API to generate PDF documents of webpages by using HTML code or URL as your input.

    PDF Request Details

    Request URL

    POST

    {api-domain}/browser360/v1/project/{project_id}/convert

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}
    Content-Type: application/json

    Request JSON Properties

    display_header_footer boolean
    optional
    Pass the value as true to show the header and footer of the webpag.
    Default: false.
    footer_template string
    optional
    HTML template for the print footer. Has the same constraints and support for special classes as PDFOptions.headerTemplate.
    format PaperFormat
    optional
    Size of the paper. Example: A4, A3.
    header_template string
    optional

    HTML template for the print header. Should be valid HTML with the following classes to inject values into them:

    date string
    optional
    Formatted print date
    title string
    mandatory
    Title of the document
    url string
    mandatory
    URL of the document
    page_number string
    optional
    Current page number
    total_pages string
    optional
    Total pages in the document
    landscape boolean
    optional
    Pass the value as true to print in a landscape orientation
    margin PDFMargin
    optional
    Set the PDF margins
    omit_background boolean
    optional
    Hides the default white background and allows generating PDFs with a transparent background
    page_ranges string
    optional
    Paper ranges to print. Example: 1-5, 8, 11-13.
    prefer_css_pageSize boolean
    optional
    Pass the value as true to prioritize the CSS @page size declared in the page over what is declared in the width, height, or format option
    print_background boolean
    optional
    Pass the value as true to print the background graphics
    scale number
    optional
    Scales the rendering of the web page. Acceptable Values: Between 0.1 and 2.
    timeout number
    optional
    Timeout in milliseconds. Pass the value as 0 to disable the timeout.
    width string | number
    optional
    Sets the width of paper. You can pass in a number or a string with a unit.
    timeout number
    optional
    Maximum wait time in milliseconds. Pass the value as 0 to disable the timeout.

    The default value can be changed by using the
    page.set_default_timeout() or page.set_default_navigation_timeout() methods.
    wait_until string | number
    optional

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZOHOCATALYST.pdfshot.execute

    PDF Response Details

    The response will return the PDF document generated.



    Generate Screenshot Using HTML/URL

    Screenshot Description

    You can use this API to generate screenshots of webpages using HTML code or URL as your input.

    Screenshot Request Details

    Request URL

    POST

    {api-domain}/browser360/v1/project/{project_id}/convert

    copy
    project_id
    Numerical
    The unique ID of the project

    Request JSON Properties

    capture_beyond_viewport boolean
    mandatory
    Pass the value as true to capture the screenshot beyond the viewport
    clip screenshot_clip
    mandatory
    Object that specifies the clipping region of the page
    encoding 'base64' | 'binary'
    mandatory
    Encoding of the image
    from_surface boolean
    mandatory
    Pass the value as true to capture the screenshot from the surface rather than the view.
    full_page boolean
    mandatory
    Pass the value as true to take a screenshot of the entire page
    omit_background boolean
    mandatory
    Hides the default white background and allows capturing screenshots with a transparent background
    quality number
    optional
    Quality of the image. Not applicable to .png images. Acceptable Values: Between 0 to 100. Maximum wait time in milliseconds. Pass the value as 0 to disable the timeout.
    wait_until string | number
    optional
    password string
    optional
    Will hold the value of the password that protets your PDF document.

    Screenshot Response Details

    The response will return a screenshot that was generated.

    Note: Any Browser action or operation that you code using the Browser Logic function, or any browser automation or web scraping task that you perform using any component of Catalyst SmartBrowz is at your own risk. We strongly recommend you use the SmartBrowz components to perform operations on domains that permit the actions, or with proper approval. Additionally, while Catalyst does provide a secure infrastructure to code your functions, any consequence of the logic you code using Catalyst functions is yours alone.
        
    
        
    CURL Request - PDF from HTML/URL
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST \ ‘https://api.catalyst.zoho.com/browser360/v1/project/10470000000272001/convert'
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
–H ‘Content-Type: application/json’
–d ‘{
“url”: “https://www.example.com”,
“output_options”: {
“output_type”: “pdf”
},
“pdf_options” : {
“scale” : 1,
“display_header_footer” : true,
“header_template” : “<style> #header, #footer { margin: 0 !important; padding: 0 !important; font-size: 9px; -webkit-print-color-adjust: exact;}</style><div style=\width:100%><span class=\date&gt;</span><span class=\title\ style=\float:right&gt;</span</div>”,
“footer_template” : “<style> #header, #footer { margin: 0 !important; padding: 0 !important; font-size: 9px; -webkit-print-color-adjust: exact;}</style><div style=\width:100%&gt;<span class=\url&gt;</span><div style=\float:right&gt;<span class=\pageNumber&gt;</span> / <span class=\totalPages&gt;</span></div></div>”,
“print_background” : false,
“landscape” : false,
“page_ranges” : “1”,
“format” : “A4”,
“width” : “100”,
“height” : “100”,
“margin” :
{
“top” : “1cm”,
“bottom” : “1cm”,
“left” : “1cm”,
“right”: “1cm”
},  
    
“omit_background” :  false
},
“page_options”:{
“css” : {
“content” : “body{background: lightgrey}”
},
“viewport” : {
“width”: 1440,
“height”: 900
},
“javascript_enabled” : true
},
“navigation_options”:{
“timeout” : 5000,
“wait_until” : “networkidle0”
}
}’
    
    
         
    View more
    
    
    

        
    
        
    CURL Request - Screenshot from HTML/URL
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST \ ‘https://api.catalyst.zoho.com/browser360/v1/project/10470000000272001/convert'
-H “Authorization: Zoho-oauthtoken 1000.910*************************16.2f*************************57” 
    
–H ‘Content-Type: application/json’
–d’{
“url”: “https://www.example.com”,
“output_options”: {
“output_type”: “screenshot”
},
“screenshot_options”: {
“type”: “jpeg”,
“quality”: 100,
“full_page”: false,
“omit_background”: false,
“capture_beyond_viewport”: true,
“clip”: {
“x”: 50,
“y”: 100,
“width”: 1000,
“height”: 100
}
},
“page_options”: {
“css”: {
“content”: “body{background: lightgrey}”
},
“viewport”: {
“width”: 1440,
“height”: 900
},
“javascript_enabled”: true
},
“navigation_options”: {
“timeout”: 5000,
“wait_until”: “networkidle0”
}
}’
    
    
         
    View more

    SDK Documentation
    Generate PDF & Screenshot- Java SDK

    Generate PDF & Screenshot- Node.js SDK

    Generate PDF & Screenshot- Python SDK

    Generate PDF Using Templates

    Note: You need to create a template in the console to use this API.

    PDF Description

    You can use this API to generate PDF documents of webpages using Templates as your input.

    PDF Request Details

    Request URL

    POST

    {api-domain}/browser360/v1/project/{project_id}/convert

    copy
    api-domain
    URL
    The DC-specific domain to access Catalyst API
    project_id
    Numerical
    The unique ID of the project

    Request JSON Properties

    display_header_footer boolean
    optional
    Pass the value as true to show the header and footer.
    Default: false.
    format PaperFormat
    optional
    Size of the paper. Example: A4, A3.
    landscape boolean
    optional
    Pass the value as true to print in landscape orientation.
    password string
    optional
    Pass the password value of the PDF document.
    omit_background boolean
    optional
    Hides the default white background and allows generating PDFs with a transparent background.
    page_ranges string
    optional
    Paper ranges to print. Example: 1-5, 8, 11-13.
    prefer_css_pageSize boolean
    optional
    Pass the value as true to prioritize the CSS @page size declared in the page over what is declared in the width, height, or format option
    print_background boolean
    optional
    Pass the value as true to print the background graphics
    scale number
    optional
    Scales the rendering of the web page. Acceptable Values: Between 0.1 and 2.
    timeout number
    optional
    Timeout in milliseconds. Pass the value as 0 to disable the timeout.
    width string | number
    optional
    Sets the width of paper. You can pass in a number or a string with a unit.
    timeout number
    optional
    Maximum wait time in milliseconds. Pass the value as 0 to disable the timeout.

    The default value can be changed by using the
    page.set_default_timeout() or page.set_default_navigation_timeout() methods.
    wait_until string | number
    optional
    password string
    optional
    Will hold the value of the password that protets your PDF document.

    Request Headers

    Authorization: Zoho-oauthtoken {oauth_token}

    Optional Headers

    CATALYST-ORG: {org_id}

    Environment: Development

    Scope

    ZOHOCATALYST.pdfshot.execute

    PDF Response Details

    The response will be a PDF that was generated.

    Note:

    • You need to create a template in the console to use this API.

    • SmartBrowz Templates offers you the option to set a password for the PDF document you generate using a template. If you employ the Set Password Manually option, then you can use this API. This API cannot be used if you employ the Set Password Dynamically option.

    Generate Screenshot Using Templates

    Screenshot Description

    You can use this API to generate screenshot of webpages, by using Templates as your input.

    Screenshot Request Details

    Request URL

    POST

    {api-domain}/browser360/v1/project/{project_id}/convert

    copy
    project_id
    Numerical
    The unique ID of the project

    Request JSON Properties

    capture_beyond_viewport boolean
    mandatory
    Pass the value as true to capture the screenshot beyond the viewport
    clip screenshot_clip
    mandatory
    Object that specifies the clipping region of the page
    encoding 'base64' | 'binary'
    mandatory
    Encoding of the image
    from_surface boolean
    mandatory
    Pass the value as true to capture the screenshot from the surface, rather than the view
    full_page boolean
    mandatory
    Pass the value as true to take a screenshot of the entire page
    omit_background boolean
    mandatory
    Hides the default white background and allows capturing screenshots with a transparent background
    quality number
    optional
    Maximum wait time in milliseconds. Pass the value as 0 to disable the timeout.

    The default value can be changed by using the
    page.set_default_timeout() or page.set_default_navigation_timeout() methods.
    wait_until string | number
    optional

    Screenshot Response Details

    The response will be a Screenshot that was generated.

    Note: Any Browser action or operation that you code using the Browser Logic function, or any browser automation or web scraping task that you perform using any component of Catalyst SmartBrowz is at your own risk. We strongly recommend you use the SmartBrowz components to perform operations on domains that permit the actions, or with proper approval. Additionally, while Catalyst does provide a secure infrastructure to code your functions, any consequence of the logic you code using Catalyst functions is yours alone.
        
    
        
    CURL Request - PDF from Templates
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST ‘https://api.catalyst.zoho.com/browser360/v1/project/10470000000272001/convert' 
    
-H “Authorization: Zoho-oauthtoken 1000.91016.2f57” 
    
-H ‘Content-Type: application/json’ 
    
-d ‘{
“url”: “https://www.example.com”,
“output_options”: {
“output_type”: “pdf”
},
“pdf_options”: {
“scale”: 1,
“display_header_footer”: true,
“header_template”: “<style> #header, #footer { margin: 0 !important; padding: 0 !important; font-size: 9px; -webkit-print-color-adjust: exact;}</style><div style="width:100%"><span class="date"></span><span class="title" style="float:right"></span></div>”,
“footer_template”: “<style> #header, #footer { margin: 0 !important; padding: 0 !important; font-size: 9px; -webkit-print-color-adjust: exact;}</style><div style="width:100%"><span class="url"></span><div style="float:right"><span class="pageNumber"></span> / <span class="totalPages"></span></div></div>”,
“print_background”: false,
“landscape”: false,
“page_ranges”: “1”,
“format”: “A4”,
“width”: “100”,
“height”: “100”,
“margin”: {
“top”: “1cm”,
“bottom”: “1cm”,
“left”: “1cm”,
“right”: “1cm”
},
“omit_background”: false
},
“page_options”: {
“css”: {
“content”: “body{background: lightgrey}”
},
“viewport”: {
“width”: 1440,
“height”: 900
},
“javascript_enabled”: true
},
“navigation_options”: {
“timeout”: 5000,
“wait_until”: “networkidle0”
}
}’
    
    
         
    View more
    
    
    

        
    
        
    CURL Request - Screenshot from Templates
    
        
    
            
    copy
    
            
    
                
    
            
    
        
    
    
    
    
    
    
    
         
    curl -X POST ‘https://api.catalyst.zoho.com/browser360/v1/project/10470000000272001/convert' 
    
-H “Authorization: Zoho-oauthtoken 1000.91016.2f57” 
    
-H ‘Content-Type: application/json’ 
    
-d ‘{
“url”: “https://www.example.com”,
“output_options”: {
“output_type”: “screenshot”
},
“screenshot_options”: {
“type”: “jpeg”,
“quality”: 100,
“full_page”: false,
“omit_background”: false,
“capture_beyond_viewport”: true,
“clip”: {
“x”: 50,
“y”: 100,
“width”: 1000,
“height”: 100
}
},
“page_options”: {
“css”: {
“content”: “body{background: lightgrey}”
},
“viewport”: {
“width”: 1440,
“height”: 900
},
“javascript_enabled”: true
},
“navigation_options”: {
“timeout”: 5000,
“wait_until”: “networkidle0”
}
}’
    
    
         
    View more

    SDK Documentation
    Generate PDF & Screenshot- Java SDK

    Generate PDF & Screenshot- Node.js SDK

    Generate PDF & Screenshot- Python SDK