For developers

Creating an application

Keruj has its own integration catalog for popular Ukrainian and international services. Adding your own application to the catalog helps to integrate Keruj with third-party services and automate your workflow.

You can find the application catalog in the Settings - Automation - Integrations menu

In the Integrations section, clicking "Add" opens the catalog of available applications

The catalog is constantly being improved and updated

What is an integration application?

It is any external backend service capable of receiving and executing HTTP requests. To submit your application to the catalog, please contact us at volo@keruj.com.

What is required from you

  1. The address of the access point where Keruj will send all requests (endpoint)

  2. The address of the access point to check the "live status" of your application (healthcheck)

  3. Logo for the catalog

  4. A brief description of the integration and what the user receives

What you receive from us

  1. A special secret token for your application to ensure that it is indeed Keruj sending you the data

  2. Endless gratitude for helping in the development of the Ukrainian product 🇺🇦 ❤️

Integration lifecycle

Integration of Keruj with an external service is carried out by exchanging messages in application/json format. There are two types of messages

  • System - sent at the moment of installation/update/uninstallation of the integration

  • User - you can specify what and how you want to receive from Keruj yourself

All interaction happens block by block, following the event + response principle

Installation

A third-party service that provides its API key, and the user must provide it by installing the application.

At the moment of installing the application in the catalog, you receive a POST request

{
  "event":"application_install", 
  "company_id":"9b6116b7-20fc-438e-bbbc-96502f8e5a8d",
  "account_id":"df2ee18d-8beb-436b-9663-2f449ebd23a8",
  "account_api_key":"dDZRdjBoNTlqd2NIbnFWODFDNWJ0dz09"
}
{
  "event":"application_install", 
  "company_id":"9b6116b7-20fc-438e-bbbc-96502f8e5a8d",
  "account_id":"df2ee18d-8beb-436b-9663-2f449ebd23a8",
  "account_api_key":"dDZRdjBoNTlqd2NIbnFWODFDNWJ0dz09"
}
{
  "event":"application_install", 
  "company_id":"9b6116b7-20fc-438e-bbbc-96502f8e5a8d",
  "account_id":"df2ee18d-8beb-436b-9663-2f449ebd23a8",
  "account_api_key":"dDZRdjBoNTlqd2NIbnFWODFDNWJ0dz09"
}

  • event - the name of the event

  • company_id - the unique identifier of the company in Keruj

  • account_id - the unique identifier of the integration in Keruj

  • account_api_key - the access key to API on behalf of the integration application

We strongly recommend saving this information in your secure database and storing the account_api_key value only in encoded form

After a successful response 2xx, the user will be redirected to the configuration page

Configuration

At the moment the user is redirected to the configuration page, you will receive a POST request

{
  "event": "application_setup",
  "company_id": "9b6116b7-20fc-438e-bbbc-96502f8e5a8d",
  "account_id": "df2ee18d-8beb-436b-9663-2f449ebd23a8"    
}
{
  "event": "application_setup",
  "company_id": "9b6116b7-20fc-438e-bbbc-96502f8e5a8d",
  "account_id": "df2ee18d-8beb-436b-9663-2f449ebd23a8"    
}
{
  "event": "application_setup",
  "company_id": "9b6116b7-20fc-438e-bbbc-96502f8e5a8d",
  "account_id": "df2ee18d-8beb-436b-9663-2f449ebd23a8"    
}

Depending on your response, 2 actions are possible

  • status 2xx and an empty body - successful completion of installation

  • status 2xx following JSON schema - ask Keruj to perform some action

For example, you want to suggest that the user fills out a form with an API key and other fields from your service.

In this case, you should respond with a 2xx status and the JSON schema

{
   "reply": "provide_api_key",
   "render": {
      "elements": [{
         "type": "paragraph",
         "format": "markdown",
         "content": "Read details at..."
      }, {
         "type": "form",
         "id": "config",
         "fields": [{
            "name": "api_key",
            "type": "text",
            "label": "API Key",
            "required": true
         }, {
            "name": "topic",
            "type": "select",
            "label": "Theme",
            "required": true,
            "options": [{
               "label": "Technical support",
               "value": "tech_support"
            }, {
               "label": "Feedback",
               "value": "feedback"
            }, {
               "label": "Question",
               "value": "question"
            }, {
               "label": "Other",
               "value": "other"
            }]
         }, {
            "name": "newsletter",
            "type": "checkbox",
            "label": "Subscribe to newsletter"
         }],
         "submit": {
            "text": "Connect",
            "icon": "check"
         }
      }]
   }
}
{
   "reply": "provide_api_key",
   "render": {
      "elements": [{
         "type": "paragraph",
         "format": "markdown",
         "content": "Read details at..."
      }, {
         "type": "form",
         "id": "config",
         "fields": [{
            "name": "api_key",
            "type": "text",
            "label": "API Key",
            "required": true
         }, {
            "name": "topic",
            "type": "select",
            "label": "Theme",
            "required": true,
            "options": [{
               "label": "Technical support",
               "value": "tech_support"
            }, {
               "label": "Feedback",
               "value": "feedback"
            }, {
               "label": "Question",
               "value": "question"
            }, {
               "label": "Other",
               "value": "other"
            }]
         }, {
            "name": "newsletter",
            "type": "checkbox",
            "label": "Subscribe to newsletter"
         }],
         "submit": {
            "text": "Connect",
            "icon": "check"
         }
      }]
   }
}
{
   "reply": "provide_api_key",
   "render": {
      "elements": [{
         "type": "paragraph",
         "format": "markdown",
         "content": "Read details at..."
      }, {
         "type": "form",
         "id": "config",
         "fields": [{
            "name": "api_key",
            "type": "text",
            "label": "API Key",
            "required": true
         }, {
            "name": "topic",
            "type": "select",
            "label": "Theme",
            "required": true,
            "options": [{
               "label": "Technical support",
               "value": "tech_support"
            }, {
               "label": "Feedback",
               "value": "feedback"
            }, {
               "label": "Question",
               "value": "question"
            }, {
               "label": "Other",
               "value": "other"
            }]
         }, {
            "name": "newsletter",
            "type": "checkbox",
            "label": "Subscribe to newsletter"
         }],
         "submit": {
            "text": "Connect",
            "icon": "check"
         }
      }]
   }
}

The user will see the configuration form with the corresponding elements

When the user fills out the data and clicks "Submit", you will receive a POST request message

{
  "event": "provide_api_key",
  "company_id": "9b6116b7-20fc-438e-bbbc-96502f8e5a8d",
  "account_id": "df2ee18d-8beb-436b-9663-2f449ebd23a8",
  "data": {
    "config": {
      "api_key": "my apu key",
      "topic": "tech_support",
      "newsletter": true
    }
  }
}
{
  "event": "provide_api_key",
  "company_id": "9b6116b7-20fc-438e-bbbc-96502f8e5a8d",
  "account_id": "df2ee18d-8beb-436b-9663-2f449ebd23a8",
  "data": {
    "config": {
      "api_key": "my apu key",
      "topic": "tech_support",
      "newsletter": true
    }
  }
}
{
  "event": "provide_api_key",
  "company_id": "9b6116b7-20fc-438e-bbbc-96502f8e5a8d",
  "account_id": "df2ee18d-8beb-436b-9663-2f449ebd23a8",
  "data": {
    "config": {
      "api_key": "my apu key",
      "topic": "tech_support",
      "newsletter": true
    }
  }
}

  • event - the name of the event you specified in reply

  • company_id - the unique identifier of the company in Keruj

  • account_id - the unique identifier of the integration in Keruj

  • data - data from user-filled elements

After that, you have 2 response options again:

  • status 2xx and an empty body - successful completion of installation

  • status 2xx following JSON schema - ask Keruj to perform another action, and this way you can build a step-by-step dialogue with the user until you have all the necessary data and are ready to finish the installation by responding with 2xx and an empty body

A successful completion will notify the user that the integration is complete and the magic will begin soon

Uninstallation

When a user wishes to delete the integration, you will be notified of this by a POST request

{
  "event": "application_uninstall",
  "company_id": "69ff6d01-92ca-4015-84cb-a91b7c1d7386",
  "account_id": "df2ee18d-8beb-436b-9663-2f449ebd23a8"
}
{
  "event": "application_uninstall",
  "company_id": "69ff6d01-92ca-4015-84cb-a91b7c1d7386",
  "account_id": "df2ee18d-8beb-436b-9663-2f449ebd23a8"
}
{
  "event": "application_uninstall",
  "company_id": "69ff6d01-92ca-4015-84cb-a91b7c1d7386",
  "account_id": "df2ee18d-8beb-436b-9663-2f449ebd23a8"
}

A response with status 2xx is expected, and that you will delete all information regarding this company.

Authorization

All requests from Keruj contain the HTTP header x-keruj-app-token. It is mandatory to check whether it matches your secret token

Healthcheck

Your application will be added to our status page https://status.keruj.app/

In case of prolonged unavailability of your access points, the application will be disabled.

Related articles

All articles

Public API

Data exchange via webhooks

Data synchronization