Apps REST API

The Slingr API provides a versatile means of interacting with your app’s data, executing actions, checking job statuses, reviewing logs, and more, all via a straightforward REST interface. Essentially, anything that can be accomplished through the app’s user interface can also be achieved using these web services.

The Slingr API adheres to REST principles, although there may be some variations. Our primary data format is JSON.

To access the Slingr API, you can make requests to the following endpoint:

https://<appName>.slingrs.io/<env>/runtime/api

Where:

• <appName> is the name of your app.
• <env> is the name of the environment, such as dev or prod.

Please note that HTTPS must always be used. Attempting to access our API via HTTP will result in an error.

All API requests should include the following headers:

    - Content-Type: application/json
    - Accept: application/json
    - token: <token_received_after_login>

General error codes #

Here is a list of common HTTP status codes used in the Slingr API along with their descriptions:

For specific details on errors related to each API method, please refer to the documentation for that specific method.

Authentication #

Before you can make requests to the Slingr API, you must log in and obtain a valid token. Follow the steps below to acquire and utilize the token.

To obtain a token, make a POST request to the following URL:

POST /auth/login

This method has no additional parameters, and the request body should have the following structure:

{
  "email": "user@test.com",
  "password": "abcdefgh"
}

The response will resemble the following:

{
  "app": "appname",
  "adminUserEmail": null,
  "ip": "::ffff:10.240.0.38",
  "userEmail": "user@test.com",
  "userName": "User Test",
  "userId": "57fce0c3e4b0ce322b0c06b2",
  "token": "eLJjYSjLUPLlIEe8lfJUOmzsVNvSRpOv"
}

It will include the following fields:

Once you have acquired the token, include it in the header of every API request as follows:

GET /data/companies
> Accept: application/json
> token: eLJjYSjLUPLlIEe8lfJUOmzsVNvSRpOv

Be aware that tokens have a limited lifespan, typically expiring after 8 hours of inactivity. However, they may expire sooner due to maintenance or other internal tasks. If your token expires, you will receive a 401 error, indicating that you need to log in again.

Please ensure the security and confidentiality of your access token, as it provides authentication to your Slingr account.

Impersonating other users #

Developer users or users with the appropriate permissions, such as the “manage groups” flag, have the capability to impersonate other users for various purposes. To perform user impersonation when logging in, you should include the following structure in the request body:

{
  "email": "manager@test.com",
  "password": "manager_password",
  "emailImpersonatedUser": "employee@test.com"
}

• username: Your own username for authentication.
• password: Your own password for authentication.
• emailImpersonatedUser: The email address of the user you wish to impersonate.

When you provide the emailImpersonatedUser field in the request body, you will log in as the specified user with their permissions and privileges. This feature is particularly valuable for testing and administrative purposes, allowing authorized users to perform actions on behalf of different users.

Ensure that user impersonation is used responsibly and only by users with the necessary permissions to prevent any unauthorized actions within the system.

The token response will include fields that reflect the impersonation scenario. Here’s an example of what the response might look like:

{
  "app": "appname",
  "adminUserEmail": "manager@test.com",
  "ip": "::ffff:10.240.0.39",
  "userEmail": "employee@test.com",
  "userName": "Employee Test",
  "userId": "57fe52ade4b0ce322b0cea32",
  "token": "NE8lUuA2Yi9K6gL9EaQaTLIQLvYIhIyv"
}

Possible errors #

When making login requests to the API, you may encounter the following error codes and their corresponding HTTP status codes along with their descriptions:

These error codes provide specific information about the issues encountered during the login process and can help troubleshoot any authentication problems effectively.

App data #

For each entity within the app, a set of methods is automatically generated. For instance, if there is an entity named companies, the following methods will be available:

GET /data/companies
GET /data/companies/{id}
PUT /data/companies/{id}
POST /data/companies
DELETE /data/companies/{ids}

These fundamental operations are available for every entity and enable you to perform common CRUD (Create, Read, Update, Delete) operations on your app’s data.

The structure of the data returned or manipulated by these methods is determined by the fields defined within each entity. For example, when fetching a company record, the response will resemble the following:

{
  "id": "57fd2d65e4b0ce322b0c8665",
  "version": 379,
  "label": "Browsezoom",
  "name": "Browsezoom",
  "state": "pending",
  "type": "a",
  "numberOfEmployees": 95,
  "isCustomer": false,
  "contactInformation": {
    "phoneNumber": "1-702-845-9380",
    "email": "jwoodsrq@spotify.com",
    "id": "58837fdd3b063a0007603547",
    "label": "Contact Information"
  },
  "addresses": [
    {
      "addressLine": "4 Magdeline Place",
      "zipCode": "89145",
      "city": "Las Vegas",
      "state": "NV",
      "id": "57fd45aee4b0ce322b0c86aa",
      "label": "NV - 89145"
    }
  ],
  "homepage": "http://www.browsezoom.com",
  "taxId": "350-KWM",
  "rating": "2.8",
  "notes": "modified notes",
  "lastMeeting": 1429623180000,
  "lastUpdate": 1485012900000
}

There are basically two types of fields:

• Record fields: Record fields are fields defined within each entity of your app. The format and characteristics of these fields depend on the data type assigned to them during entity creation. The types can include text, numbers, dates, and more. For specific details about the types and their format, please refer to the types documentation.

• System fields: System fields are inherent to every record in your app and are automatically included. They provide essential information about the record and are crucial for various functionalities. The system fields include:

• id: This is the unique identifier for each record. It is used to distinguish one record from another.

• label: The label field contains the record’s label, which is generated based on the instance label expression defined within the entity. This label is often used for display purposes and makes it easier to identify records.

• version: The version field represents the record’s version and is primarily used for optimistic locking. Optimistic locking ensures that record updates are synchronized and avoids conflicts when multiple users attempt to modify the same record simultaneously.

Understanding both record fields and system fields is essential for effectively working with your app’s data and ensuring the integrity and consistency of your records. You can incorporate this revised information into your documentation to provide a clear distinction between record fields and system fields and their respective roles in your app’s data.

Basic operations #

Read one record #

GET /data/{entityName}/{id}

Reads one record by ID

Request #

GET /data/{entityName}/{id}
> Accept: application/json
> token: token

_fields=name,type.

_relationshipsToFetch=company,region. 

Response #

The JSON representation of the record is returned. More info about the format can be found here.

GET /data/{entityName}/{id}
< Content-Type: application/json
{
  "id": "57fd2d65e4b0ce322b0c8665",
  "version": 1,
  "label": "label",
  "fieldA": "value",
  "fieldB": "value"
  "fieldC": "value"
}

Posible errors #

Samples #

fetches one company record

GET /data/companies/57fd2d65e4b0ce322b0c8665
> Accept: application/json
> token: token



GET /data/companies/57fd2d65e4b0ce322b0c8665
< Content-Type: application/json

{
  "id": "57fd2d65e4b0ce322b0c8665",
  "version": 379,
  "label": "Browsezoom",
  "name": "Browsezoom",
  "state": "pending",
  "type": "a",
  "numberOfEmployees": 95,
  "isCustomer": false,
  "contactInformation": {
    "phoneNumber": "1-702-845-9380",
    "email": "jwoodsrq@spotify.com",
    "id": "58837fdd3b063a0007603547",
    "label": "Contact Information"
  },
  "addresses": [
    {
      "addressLine": "4 Magdeline Place",
      "zipCode": "89145",
      "city": "Las Vegas",
      "state": "NV",
      "id": "57fd45aee4b0ce322b0c86aa",
      "label": "NV - 89145"
    }
  ],
  "homepage": "http://www.browsezoom.com",
  "taxId": "350-KWM",
  "rating": "2.8",
  "notes": "modified notes",
  "lastMeeting": 1429623180000,
  "lastUpdate": 1485012900000
}

List records #

GET /data/{entityName}

Reads many records from one entity. You can specify filters and other options in the URL.

More information about queries can be found in Query language.

Request #

GET /data/{entityName}
> Accept: application/json
> token: token

Response #

A list of records in JSON representation will be returned.

GET /data/{entityName}
< Content-Type: application/json

{
  "total": 10,
  "offset": "57fd2d65e4b0ce322b0c8565",
  "items": [
    {
      "id": "57fd2d65e4b0ce322b0c8665",
      "version": 1,
      "label": "label",
      "fieldA": "value",
      "fieldB": "value"
    },
    {
      "id": "57fd2d65e4b0ce322b0c8565",
      "version": 1,
      "label": "label",
      "fieldA": "value",
      "fieldB": "value"
    }
  ]
}

Posible errors #

Samples #

// fetches fields name and type of two companies in pending status

GET /data/companies?state=pending&_fields=name,type&_size=2
> Accept: application/json
> token: token



GET /data/companies?state=pending&_fields=name,type&_size=2
< Content-Type: application/json

{
  "total": 135,
  "offset": "57fd2d65e4b0ce322b0c8565",
  "items": [
    {
      "id": "57fd2d65e4b0ce322b0c8665",
      "version": 379,
      "label": "Browsezoom",
      "name": "Browsezoom",
      "type": "a"
    },
    {
      "id": "57fd2d65e4b0ce322b0c8565",
      "version": 375,
      "label": "Blogpad",
      "name": "Blogpad",
      "type": "b"
    }
  ]
}

Create record #

POST /data/{entityName}

Creates a new record for the given entity.

Data is sent in the body and should be valid according to the entity structure and fields rules.

Request #

The body of this request should be a record in JSON format based on the entity structure.

All fields you are sending have to be present in the entity definition and values have to match the format required by the type. Also, there might be validation rules you have to take into account.

POST /data/{entityName}
> Content-Type: application/json
> Accept: application/json
> token: token

{
  "fieldA": "value",
  "fieldB": "value"
  "fieldC": 10,
  "nestedFields": [
    {
      "innerA": "value",
      "innerB": "value"
    },
    {
      "innerA": "value",
      "innerB": "value"
    }
  ]
}

Response #

The response is the same as if you do a GET /data/companies/{id}, which means that you will be able to get the ID and label of the created record, as well as other calculated/default fields the entity might have.

POST /data/{entityName}
< Content-Type: application/json

{
  "id": "588775f63b063a0007604f4c",
  "version": 0,
  "label": "label",
  "fieldA": "value",
  "fieldB": "value"
  "fieldC": 10,
  "nestedFields": [
    {
      "id": "588775f63b063a0007604f4c",
      "label": "label",
      "innerA": "value",
      "innerB": "value"
    },
    {
      "id": "588775f63b063a0007604f8a",
      "label": "label",
      "innerA": "value",
      "innerB": "value"
    }
  ],
  "calculatedField": "value"
}

Posible errors #

{ 
 “code”: “validationErrors”,
 “message”: “There are validation errors”, 
 “errors”: [ 
 { 
     “field”: “name”, 
     “fieldLabel”: “Name”, 
     “code”: “required”, 
     “message”: “This field is required”, 
     “additionalInfo”: null 
 }, 
 { 
      “field”: “state”, 
      “fieldLabel”: “State”, 
      “code”: “invalid”, 
      “message”: “Not a valid choice”, 
      “additionalInfo”: { 
           “rejectedValue”: “sdfsdfsd” 
      } 
 }]
}

Samples #

// creates a new company

POST /data/companies
> Content-Type: application/json
> Accept: application/json
> token: token

{
  "name": "Test 1",
  "state": "pending",
  "type": "a",
  "numberOfEmployees": 95,
  "isCustomer": false,
  "contactInformation": {
    "phoneNumber": "1-702-845-9380",
    "email": "jwoodsrq@spotify.com"
  },
  "addresses": [
    {
      "addressLine": "4 Magdeline Place",
      "zipCode": "89145",
      "city": "Las Vegas",
      "state": "NV"
    }
  ],
  "homepage": "http://www.browsezoom.com",
  "taxId": "350-KWM",
  "rating": "2.8",
  "notes": "test notes",
  "lastMeeting": 1429623180000
}


POST /data/companies
< Content-Type: application/json

{
  "id": "588775f63b063a0007604f4c",
  "version": 0,
  "label": "Test 1",
  "name": "Test 1",
  "state": "pending",
  "type": "a",
  "numberOfEmployees": 95,
  "isCustomer": false,
  "contactInformation": {
    "phoneNumber": "1-702-845-9380",
    "email": "jwoodsrq@spotify.com",
    "id": "588775f63b063a0007604f4a",
    "label": "Contact Information"
  },
  "addresses": [
    {
      "addressLine": "4 Magdeline Place",
      "zipCode": "89145",
      "city": "Las Vegas",
      "state": "NV",
      "id": "588775f63b063a0007604f4b",
      "label": "NV - 89145"
    }
  ],
  "homepage": "http://www.browsezoom.com",
  "taxId": "350-KWM",
  "rating": "2.8",
  "notes": "test notes",
  "lastMeeting": 1429623180000,
  "lastUpdate": 1485272566096
}

Update record #

PUT /data/{entityName}/{id}

Updates a record data.

Data is sent in the body and should be valid according to the entity structure and fields rules.

Request #

To update a record via the API, you should provide a JSON-formatted record in the request body. The fields you include in this JSON body must align with the structure defined in the entity. Additionally, the values must conform to the format required by the data type assigned to each field. Be aware that there might be validation rules enforced by the entity that you need to adhere to.

Key points to consider when sending an update request:

• You can specify only the fields you wish to update. Fields that are not included in the JSON request body won’t be modified. If you want to clear a field’s value, set it to null explicitly.

• An essential field to mention is version, which signifies the version of the record you are updating. This field is crucial for managing concurrency issues, especially when two users attempt to update the same record simultaneously. (Refer to the optimistic locking section below for further details.) If you do not provide the version field, your update will always overwrite existing data, regardless of other user modifications.

Please make sure to structure your update requests accordingly, taking into account the entity’s schema, data type requirements, and any validation rules in place.

PUT /data/{entityName}/{id}
> Content-Type: application/json
> Accept: application/json
> token: token

{
  "version": 1,
  "fieldA": "newValue",
  "fieldB": "newValue",
  "nestedFields": [
    {
      "id": "588775f63b063a0007604f4c",
      "innerA": "newValue"
    },
    {
      "id": "588775f63b063a0007604f8a",
      "innerB": "newValue"
    }
  ]
}

Response #

The response is the same as if you do a GET /data/companies/{id}, which means that you will be able to get the ID and label of the created record, as well as other calculated/default fields the entity might have.

PUT /data/{entityName}/{id}
< Content-Type: application/json

{
  "id": "588775f63b063a0007604ab2",
  "version": 0,
  "label": "label",
  "fieldA": "newValue",
  "fieldB": "newValue"
  "fieldC": 10,
  "nestedFields": [
    {
      "id": "588775f63b063a0007604f4c",
      "label": "label",
      "innerA": "newValue",
      "innerB": "value"
    },
    {
      "id": "588775f63b063a0007604f8a",
      "label": "label",
      "innerA": "value",
      "innerB": "newValue"
    }
  ],
  "calculatedField": "value"
}

Posible errors #

{ 
 “code”: “validationErrors”,
 “message”: “There are validation errors”, 
 “errors”: [ 
 { 
     “field”: “name”, 
     “fieldLabel”: “Name”, 
     “code”: “required”, 
     “message”: “This field is required”, 
     “additionalInfo”: null 
 }, 
 { 
      “field”: “state”, 
      “fieldLabel”: “State”, 
      “code”: “invalid”, 
      “message”: “Not a valid choice”, 
      “additionalInfo”: { 
           “rejectedValue”: “sdfsdfsd” 
      } 
 }]
}

Samples #

// updates a few fields in a company record

PUT /data/companies/588775f63b063a0007604f4c
> Content-Type: application/json
> Accept: application/json
> token: token

{
  "version": 1,
  "state": "active",
  "type": "b",
  "numberOfEmployees": 100
}


PUT /data/companies/588775f63b063a0007604f4c
< Content-Type: application/json

{
  "id": "588775f63b063a0007604f4c",
  "version": 2,
  "label": "Test 1",
  "name": "Test 1",
  "state": "active",
  "type": "b",
  "numberOfEmployees": 100,
  "isCustomer": false,
  "contactInformation": {
    "phoneNumber": "1-702-845-9380",
    "email": "jwoodsrq@spotify.com",
    "id": "588775f63b063a0007604f4a",
    "label": "Contact Information"
  },
  "addresses": [
    {
      "addressLine": "4 Magdeline Place",
      "zipCode": "89145",
      "city": "Las Vegas",
      "state": "NV",
      "id": "588775f63b063a0007604f4b",
      "label": "NV - 89145"
    }
  ],
  "homepage": "http://www.browsezoom.com",
  "taxId": "350-KWM",
  "rating": "2.8",
  "notes": "test notes",
  "lastMeeting": 1429623180000,
  "lastUpdate": 1485288240000
}

Delete one record #

DELETE /data/{entityName}/{id}

Deletes a record from the database. You won’t be able to recover the deleted record (except that you have enabled audit logs for that entity).

Request #

DELETE /data/{entityName}/{id}
> Accept: application/json
> token: token

Response #

The response will vary based on the async parameter. There are two possible responses:

• Record: If the async parameter is set to false, this method will return the deleted record.

• Job Reference: If the async parameter is set to true, the method will return a reference to the job responsible for executing the deletion process. Once the job is completed, you can retrieve the process’s response from the job’s results.

Posible errors #

Samples #

// deletes one company

DELETE /data/companies/588775f63b063a0007604f4c
> Accept: application/json
> token: token



DELETE /data/companies/588775f63b063a0007604f4c
< Content-Type: application/json

{
  "id": "588775f63b063a0007604f4c",
  "version": 10,
  "label": "Test 1",
  "name": "Test 1",
  "state": "active",
  "type": "b",
  "numberOfEmployees": 100,
  "isCustomer": false,
  "contactInformation": {
    "phoneNumber": "1-702-845-9380",
    "email": "jwoodsrq@spotify.com",
    "id": "588775f63b063a0007604f4a",
    "label": "Contact Information"
  },
  "addresses": [
    {
      "addressLine": "4 Magdeline Place",
      "zipCode": "89145",
      "city": "Las Vegas",
      "state": "NV",
      "id": "588775f63b063a0007604f4b",
      "label": "NV - 89145"
    }
  ],
  "homepage": "http://www.browsezoom.com",
  "taxId": "350-KWM",
  "rating": "2.8",
  "notes": "test notes",
  "lastMeeting": 1429623180000,
  "lastUpdate": 1485288240000
}

// deletes one company in the background

DELETE /data/companies/588775f63b063a0007604f4c?_async=true
> Accept: application/json
> token: token


DELETE /data/companies/588775f63b063a0007604f4c?_async=true
< Content-Type: application/json

{
  "jobLink": "/api/status/jobs/5887b6f23b063a0007604fa8",
  "jobId": "5887b6f23b063a0007604fa8"
}

Delete many records #

DELETE /data/{entityName}/{ids}

This method allows you to delete multiple records from the database. It’s important to note that once records are deleted, they cannot be recovered unless you have enabled audit logs tracking for the respective entity.

Upon initiating this method, a job will be created to handle the record deletions in the background. While the method itself returns immediately, you can monitor the status of the job to determine when it completes.

Request #

DELETE /data/{entityName}/{ids}
> Accept: application/json
> token: token

Response #

The response varies depending on the value of the _async parameter. There are two possible responses:

1. Map with Records (if _async is false): If the _async parameter is set to false, the result will be a map. Each record’s ID will serve as the key, and the corresponding value will be a map containing fields for the status and response (which represents the deleted record in JSON format). In case of an error, the value will contain an errorMessage.

2. Job Reference (if _async is true): When the _async parameter is set to true, the method returns a reference to the job responsible for executing the deletion process. Once the job is completed, you can find the response of the process within the job’s results.

Posible errors #

Samples #

// deletes two companies

DELETE /data/companies/57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565
> Accept: application/json
> token: token



DELETE /data/companies/57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565
< Content-Type: application/json

{
  "57fd2d65e4b0ce322b0c8665": {
    "status": "ok",
    "response": {
      "id": "57fd2d65e4b0ce322b0c8665",
      "version": 381,
      "label": "Browsezoom",
      "entity": {
        "id": "57fce228e4b0f6600fdfb836",
        "name": "Companies"
      },
      "name": "Browsezoom",
      "state": "pending",
      "type": "a",
      "numberOfEmployees": 95,
      "isCustomer": false,
      "contactInformation": {
        "id": "58837fdd3b063a0007603547",
        "label": "Contact Information"
        "phoneNumber": "1-702-845-9380",
        "email": "jwoodsrq@spotify.com"
      },
      "addresses": [
        {
          "id": "57fd45aee4b0ce322b0c86aa",
          "label": "NV - 89145",
          "addressLine": "4 Magdeline Place",
          "zipCode": "89145",
          "city": "Las Vegas",
          "state": "NV"
        }
      ],
      "homepage": "http://www.browsezoom.com",
      "taxId": "350-KWM",
      "rating": "2.8",
      "notes": "modified notes",
      "lastMeeting": 1429623180000,
      "lastUpdate": 1485292080000
    }
  },
  "57fd2d65e4b0ce322b0c8565": {
    "status": "ok",
    "response": {
      "id": "57fd2d65e4b0ce322b0c8565",
      "version": 377,
      "label": "Blogpad",
      "name": "Blogpad",
      "state": "pending",
      "type": "b",
      "numberOfEmployees": 534,
      "isCustomer": false,
      "contactInformation": {
        "id": "581224c8e4b0285870237cc5",
        "label": "Contact Information",
        "phoneNumber": "1-405-298-5885",
        "email": "molsonre@rakuten.co.jp"
      },
      "addresses": [
        {
          "id": "57fd45aee4b0ce322b0c86ac",
          "label": "OK - 73157",
          "addressLine": "4 Crownhardt Plaza",
          "zipCode": "73157",
          "city": "Oklahoma City",
          "state": "OK"
        }
      ],
      "homepage": "http://www.blogpad.com",
      "taxId": "123-ABC",
      "rating": "3.3",
      "notes": "Aenean fermentum. Donec ut mauris eget massa tempor convallis. Nulla neque libero, convallis eget, eleifend luctus, ultricies eu, nibh.",
      "lastMeeting": 1422111300000,
      "lastUpdate": 1485292500000
    }
  }
}

// deletes two companies in the background

DELETE /data/companies/588775f63b063a0007604f4c,588775f63b063a0007604f8b?_async=true
> Accept: application/json
> token: token



DELETE /data/companies/588775f63b063a0007604f4c,588775f63b063a0007604f8b?_async=true
< Content-Type: application/json

{
  "jobLink": "/api/status/jobs/5887b6f23b063a0007604fa8",
  "jobId": "5887b6f23b063a0007604fa8"
}

Delete records over query #

DELETE /data/{entityName}

This method is used to delete all records that match a specified query. It’s important to note that once records are deleted, they cannot be recovered unless you have enabled audit logs tracking for the corresponding entity.

Upon initiating this method, a job will be generated to handle the deletion of the records in the background. While the method itself returns promptly, you have the option to monitor the job’s status to determine when the deletion process is complete.

Request #

DELETE /data/{entityName}
> Accept: application/json
> token: token

Response #

The response varies depending on the value of the _async parameter. There are two possible responses:

1. Map with Records (if _async is false): If the _async parameter is set to false, the result will be a map. Each record’s ID will serve as the key, and the corresponding value will be a map containing fields for the status and response (which represents the deleted record in JSON format). In case of an error, the value will contain an errorMessage.

2. Job Reference (if _async is true): When the _async parameter is set to true, the method returns a reference to the job responsible for executing the deletion process. Once the job is completed, you can find the response of the process within the job’s results.

Posible errors #

Samples #

// deletes companies with type 'a'

DELETE /data/companies?type=a
> Accept: application/json
> token: token



DELETE /data/companies?type=a
< Content-Type: application/json

{
  "57fd2d65e4b0ce322b0c8665": {
    "status": "ok",
    "response": {
      "id": "57fd2d65e4b0ce322b0c8665",
      "version": 381,
      "label": "Browsezoom",
      "entity": {
        "id": "57fce228e4b0f6600fdfb836",
        "name": "Companies"
      },
      "name": "Browsezoom",
      "state": "pending",
      "type": "a",
      "numberOfEmployees": 95,
      "isCustomer": false,
      "contactInformation": {
        "id": "58837fdd3b063a0007603547",
        "label": "Contact Information"
        "phoneNumber": "1-702-845-9380",
        "email": "jwoodsrq@spotify.com"
      },
      "addresses": [
        {
          "id": "57fd45aee4b0ce322b0c86aa",
          "label": "NV - 89145",
          "addressLine": "4 Magdeline Place",
          "zipCode": "89145",
          "city": "Las Vegas",
          "state": "NV"
        }
      ],
      "homepage": "http://www.browsezoom.com",
      "taxId": "350-KWM",
      "rating": "2.8",
      "notes": "modified notes",
      "lastMeeting": 1429623180000,
      "lastUpdate": 1485292080000
    }
  }
}

deletes companies with type 'a' in the background

DELETE /data/companies?_async=true&type=a
> Accept: application/json
> token: token

DELETE /data/companies?_async=true&type=a
< Content-Type: application/json

{
  "jobLink": "/api/status/jobs/5887b6f23b063a0007604fa8",
  "jobId": "5887b6f23b063a0007604fa8"
}

Optimistic locking #

Optimistic locking is a feature designed to prevent inadvertent overwriting of changes made by other users to a record. It accomplishes this by utilizing a record version, represented as a numerical value that increments each time a record undergoes modification.

When updating a record, if you include the version field within the request body and this version does not match the record’s current version on the server, the operation will result in a 409 error. This mechanism effectively safeguards against unintentional overwrites of changes made by other users.

If the version field is omitted from the request, no version control will be applied, potentially leading to the unintentional overwriting of changes made by others. Consequently, it is strongly recommended to always include the version field when updating records.

Aggregate queries #

PUT /data/{entityName}/aggregate

You can perform aggregation operations like count, sum or average.

For detailed documentation please check Aggregate queries.

Request #

The request’s body contains the chain of operations to execute over the entity records. For more information please check documentation for Aggregate queries.

PUT /data/{entityName}/aggregate
> Content-Type: application/json
> Accept: application/json
> token: token

[
  {"operation1": "settings"},
  {"operation2": "settings"},
  {"operationN": "settings"}
]

Response #

The result of the aggregation is returned. The format is specific to the aggregation done, so please check the documentation for Aggregate queries.

Posible errors #

Samples #

// counts the number of skills per company

PUT /data/contacts/aggregate
> Content-Type: application/json
> Accept: application/json
> token: token

[
  {"project": "company,numberOfSkills"},
  {"group": {"by": "company", "totalSkills": "sum(numberOfSkills)"}}
]


PUT /data/contacts/aggregate
< Content-Type: application/json

{
  "total": 6,
  "items": [
    {
      "company": "Trudoo",
      "totalSkills": 1
    },
    {
      "company": "Riffwire",
      "totalSkills": 3
    },
    {
      "company": "Snaptags",
      "totalSkills": 2
    },
    {
      "company": "Edgeify",
      "totalSkills": 0
    },
    {
      "company": "Flipopia",
      "totalSkills": 3
    },
    {
      "company": "Rooxo",
      "totalSkills": 4
    }
  }
]

Actions #

Execute action over one record #

PUT /data/{entityName}/{id}/{actionName}

Execute an action over one record.

Request #

When the action includes parameters, you can send these parameters within the request body. The format should follow the same structure as when creating or updating records. However, in this context, instead of fields, you should provide the parameters relevant to the action.

In cases where the action does not require any parameters, you can simply leave the request body empty.

PUT /data/{entityName}/{id}/{actionName}
> Content-Type: application/json
> Accept: application/json
> token: token

{
  "param1": "value",
  "param2": value
}

Response #

The response varies based on the action type and the _async parameter. There are three possible response scenarios:

1. Record Response (if _async is false and the action type is ‘One record’): When _async is set to false and the action does not return a custom response, this method will return the updated record. This scenario is applicable only to actions of type ‘One record.’

2. Custom Action’s Response (if _async is false and the action returns a custom response): When _async is false, and the action returns a custom response, that specific response will be returned. Note that actions of type ‘Many records’ should always provide a custom response. If they do not return anything, an empty response will be generated.

3. Job Reference (if _async is true): In cases where _async is set to true, the method will return a reference to the job responsible for executing the action. Once the action is completed, you can locate the response of the action within the job’s results.

Below, you can find examples illustrating each of these response types.

Posible errors #

Samples #

// executes a simple action over a company record, no custom response

PUT /data/companies/57fd2d65e4b0ce322b0c8665/logSomething
> Content-Type: application/json
> Accept: application/json
> token: token

{
    "param1": "a",
    "param2": "b"
}


PUT /data/companies/57fd2d65e4b0ce322b0c8665/logSomething
< Content-Type: application/json

{
  "id": "57fd2d65e4b0ce322b0c8665",
  "version": 381,
  "label": "Browsezoom",
  "name": "Browsezoom",
  "state": "pending",
  "type": "a",
  "numberOfEmployees": 95,
  "isCustomer": false,
  "contactInformation": {
    "id": "58837fdd3b063a0007603547",
    "label": "Contact Information",
    "phoneNumber": "1-702-845-9380",
    "email": "jwoodsrq@spotify.com",
  },
  "addresses": [
    {
      "id": "57fd45aee4b0ce322b0c86aa",
      "label": "NV - 89145",
      "addressLine": "4 Magdeline Place",
      "zipCode": "89145",
      "city": "Las Vegas",
      "state": "NV"
    }
  ],
  "homepage": "http://www.browsezoom.com",
  "taxId": "350-KWM",
  "rating": "2.8",
  "notes": "modified notes",
  "lastMeeting": 1429623180000,
  "lastUpdate": 1485292080000
}

// executes a simple action over a company record in the background, no custom response

PUT /data/companies/57fd2d65e4b0ce322b0c8665/logSomething?_async=true
> Content-Type: application/json
> Accept: application/json
> token: token

{
    "param1": "a",
    "param2": "b"
}


PUT /data/companies/57fd2d65e4b0ce322b0c8665/logSomething?_async=true
< Content-Type: application/json

{
  "jobLink": "/api/status/jobs/588f3e65b45fc9000bc1baa7",
  "jobId": "588f3e65b45fc9000bc1baa7"
}

// executes an action that works with many records and returns a custom response

PUT /data/companies/57fd2d65e4b0ce322b0c8665/countEmployees
> Content-Type: application/json
> Accept: application/json
> token: token



PUT /data/companies/57fd2d65e4b0ce322b0c8665/countEmployees
< Content-Type: application/json

{
    "numberOfEmployees": 95
}

Execute action over many records #

PUT /data/{entityName}/{ids}/{actionName}

Execute an action over many records. The action will be executed in each record one by one if the action is of type One record.

Request #

When the action includes parameters, you can send these parameters within the request body. The format should follow the same structure as when creating or updating records. However, in this context, instead of fields, you should provide the parameters relevant to the action.

In cases where the action does not require any parameters, you can simply leave the request body empty.

PUT /data/{entityName}/{ids}/{actionName}
> Content-Type: application/json
> Accept: application/json
> token: token

{
  "param1": "value",
  "param2": value
}

Response #

The response varies based on the action type and the _async parameter. There are three possible response scenarios:

1. Map with Records (if _async is false and the action type is ‘One record’): When _async is set to false, and the action does not return a custom response, the result will be a map. Each record’s ID serves as the key, and the corresponding value includes fields for the status and response (representing the record as JSON) or an errorMessage in case of an error. This applies specifically to actions of type ‘One record.’

2. Custom Action’s Responses (if _async is false and the action returns a custom response): When _async is false, and the action returns a custom response, a map is returned with each record’s ID (for each record) serving as a key. Each key is associated with a map containing the status (“ok” or “error”) and a response field containing the custom response. Note that actions of type ‘Many records’ should always provide a custom response. If they do not return anything, an empty response will be generated.

3. Job Reference (if _async is true): In cases where _async is set to true, the method will return a reference to the job responsible for executing the action. Once the action is completed, you can find the response of the action within the results of the job.

Below, you can find examples illustrating each of these response types.

Posible errors #

Samples #

// executes a simple action over two company records, no custom response

PUT /data/companies/57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565/logSomething
> Content-Type: application/json
> Accept: application/json
> token: token

{
    "param1": "a",
    "param2": "b"
}


PUT /data/companies/57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565/logSomething
< Content-Type: application/json

{
  "57fd2d65e4b0ce322b0c8665": {
    "status": "ok",
    "response": {
      "id": "57fd2d65e4b0ce322b0c8665",
      "version": 381,
      "label": "Browsezoom",
      "entity": {
        "id": "57fce228e4b0f6600fdfb836",
        "name": "Companies"
      },
      "name": "Browsezoom",
      "state": "pending",
      "type": "a",
      "numberOfEmployees": 95,
      "isCustomer": false,
      "contactInformation": {
        "id": "58837fdd3b063a0007603547",
        "label": "Contact Information"
        "phoneNumber": "1-702-845-9380",
        "email": "jwoodsrq@spotify.com"
      },
      "addresses": [
        {
          "id": "57fd45aee4b0ce322b0c86aa",
          "label": "NV - 89145",
          "addressLine": "4 Magdeline Place",
          "zipCode": "89145",
          "city": "Las Vegas",
          "state": "NV"
        }
      ],
      "homepage": "http://www.browsezoom.com",
      "taxId": "350-KWM",
      "rating": "2.8",
      "notes": "modified notes",
      "lastMeeting": 1429623180000,
      "lastUpdate": 1485292080000
    }
  },
  "57fd2d65e4b0ce322b0c8565": {
    "status": "ok",
    "response": {
      "id": "57fd2d65e4b0ce322b0c8565",
      "version": 377,
      "label": "Blogpad",
      "name": "Blogpad",
      "state": "pending",
      "type": "b",
      "numberOfEmployees": 534,
      "isCustomer": false,
      "contactInformation": {
        "id": "581224c8e4b0285870237cc5",
        "label": "Contact Information",
        "phoneNumber": "1-405-298-5885",
        "email": "molsonre@rakuten.co.jp"
      },
      "addresses": [
        {
          "id": "57fd45aee4b0ce322b0c86ac",
          "label": "OK - 73157",
          "addressLine": "4 Crownhardt Plaza",
          "zipCode": "73157",
          "city": "Oklahoma City",
          "state": "OK"
        }
      ],
      "homepage": "http://www.blogpad.com",
      "taxId": "123-ABC",
      "rating": "3.3",
      "notes": "Aenean fermentum. Donec ut mauris eget massa tempor convallis. Nulla neque libero, convallis eget, eleifend luctus, ultricies eu, nibh.",
      "lastMeeting": 1422111300000,
      "lastUpdate": 1485292500000
    }
  }
}

// executes a simple action over two company records with custom response

PUT /data/companies/57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565/customResponse
> Content-Type: application/json
> Accept: application/json
> token: token



PUT /data/companies/57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565/customResponse
< Content-Type: application/json

{
  "57fd2d65e4b0ce322b0c8665": {
      "status": "ok",
      "response": "This is a custom response"
  },
  "57fd2d65e4b0ce322b0c8565": {
      "status": "ok",
      "response": "This is a custom response"
  }
}

// executes a simple action over two company records in the background

PUT /data/companies/57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565/logSomething?_async=true
> Content-Type: application/json
> Accept: application/json
> token: token

{
    "param1": "a",
    "param2": "b"
}


PUT /data/companies/57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565/logSomething?_async=true
< Content-Type: application/json

{
  "jobLink": "/api/status/jobs/588f45e2b45fc9000bc1bd1f",
  "jobId": "588f45e2b45fc9000bc1bd1f"
}

// executes an action that works with many records over two records and returns a custom response

PUT /data/companies/57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565/countEmployees
> Content-Type: application/json
> Accept: application/json
> token: token

PUT /data/companies/57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565/countEmployees
< Content-Type: application/json

{
    "numberOfEmployees": 629
}

Execute action over query #

PUT /data/{entityName}/{actionName}

Execute an action over records matched by a query.

Request #

When the action includes parameters, you can send these parameters within the request body. The format should follow the same structure as when creating or updating records. However, in this context, instead of fields, you should provide the parameters relevant to the action.

In cases where the action does not require any parameters, you can simply leave the request body empty.

PUT /data/{entityName}/{actionName}
> Content-Type: application/json
> Accept: application/json
> token: token

{
  "param1": "value",
  "param2": value
}

Response #

The response varies based on the action type and the _async parameter. There are three possible response scenarios:

1. Map with Records (if _async is false and the action type is ‘One record’): When _async is set to false, and the action does not return a custom response, the result will be a map. Each record’s ID serves as the key, and the corresponding value includes fields for the status and response (representing the record as JSON) or an errorMessage in case of an error. This applies specifically to actions of type ‘One record.’

2. Custom Action’s Responses (if _async is false and the action returns a custom response): When _async is false, and the action returns a custom response, a map is returned with each record’s ID (for each record) serving as a key. Each key is associated with a map containing the status (“ok” or “error”) and a response field containing the custom response. Note that actions of type ‘Many records’ should always provide a custom response. If they do not return anything, an empty response will be generated.

3. Job Reference (if _async is true): In cases where _async is set to true, the method will return a reference to the job responsible for executing the action. Once the action is completed, you can find the response of the action within the results of the job.

Below, you can find examples illustrating each of these response types.

Posible errors #

Samples #

// executes a simple action over two company records, no custom response

PUT /data/companies/logSomething?id=57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565
> Content-Type: application/json
> Accept: application/json
> token: token

{
    "param1": "a",
    "param2": "b"
}


PUT /data/companies/logSomething?id=57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565
< Content-Type: application/json

{
  "57fd2d65e4b0ce322b0c8665": {
    "status": "ok",
    "response": {
      "id": "57fd2d65e4b0ce322b0c8665",
      "version": 381,
      "label": "Browsezoom",
      "entity": {
        "id": "57fce228e4b0f6600fdfb836",
        "name": "Companies"
      },
      "name": "Browsezoom",
      "state": "pending",
      "type": "a",
      "numberOfEmployees": 95,
      "isCustomer": false,
      "contactInformation": {
        "phoneNumber": "1-702-845-9380",
        "email": "jwoodsrq@spotify.com",
        "id": "58837fdd3b063a0007603547",
        "label": "Contact Information"
      },
      "addresses": [
        {
          "addressLine": "4 Magdeline Place",
          "zipCode": "89145",
          "city": "Las Vegas",
          "state": "NV",
          "id": "57fd45aee4b0ce322b0c86aa",
          "label": "NV - 89145"
        }
      ],
      "homepage": "http://www.browsezoom.com",
      "taxId": "350-KWM",
      "rating": "2.8",
      "notes": "modified notes",
      "lastMeeting": 1429623180000,
      "lastUpdate": 1485292080000
    }
  },
  "57fd2d65e4b0ce322b0c8565": {
    "status": "ok",
    "response": {
      "id": "57fd2d65e4b0ce322b0c8565",
      "version": 377,
      "label": "Blogpad",
      "name": "Blogpad",
      "state": "pending",
      "type": "b",
      "numberOfEmployees": 534,
      "isCustomer": false,
      "contactInformation": {
        "phoneNumber": "1-405-298-5885",
        "email": "molsonre@rakuten.co.jp",
        "id": "581224c8e4b0285870237cc5",
        "label": "Contact Information"
      },
      "addresses": [
        {
          "addressLine": "4 Crownhardt Plaza",
          "zipCode": "73157",
          "city": "Oklahoma City",
          "state": "OK",
          "id": "57fd45aee4b0ce322b0c86ac",
          "label": "OK - 73157"
        }
      ],
      "homepage": "http://www.blogpad.com",
      "taxId": "123-ABC",
      "rating": "3.3",
      "notes": "Aenean fermentum. Donec ut mauris eget massa tempor convallis. Nulla neque libero, convallis eget, eleifend luctus, ultricies eu, nibh.",
      "lastMeeting": 1422111300000,
      "lastUpdate": 1485292500000
    }
  }
}

// executes a simple action over two company records with custom response

PUT /data/companies/customResponse?id=57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565
> Content-Type: application/json
> Accept: application/json
> token: token

PUT /data/companies/customResponse?id=57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565
< Content-Type: application/json

{
  "57fd2d65e4b0ce322b0c8665": {
      "status": "ok",
      "response": "This is a custom response"
  },
  "57fd2d65e4b0ce322b0c8565": {
      "status": "ok",
      "response": "This is a custom response"
  }
}

// executes a simple action over two company records in the background

PUT /data/companies/logSomething?_async=true&id=57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565
> Content-Type: application/json
> Accept: application/json
> token: token

{
    "param1": "a",
    "param2": "b"
}


PUT /data/companies/logSomething?_async=true&id=57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565
< Content-Type: application/json

{
  "jobLink": "/api/status/jobs/588f45e2b45fc9000bc1bd1f",
  "jobId": "588f45e2b45fc9000bc1bd1f"
}

// executes an action that works with many records over two records and returns a custom response

PUT /data/companies/countEmployees?id=57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565
> Content-Type: application/json
> Accept: application/json
> token: token

PUT /data/companies/countEmployees?id=57fd2d65e4b0ce322b0c8665,57fd2d65e4b0ce322b0c8565
< Content-Type: application/json

{
    "numberOfEmployees": 629
}

Import records #

POST /data/{entityName}/import

Imports records from a CSV file.

Request #

This feature allows you to import records from a CSV file into your system. When preparing the CSV file, please adhere to the following rules:

Headers: Headers in the CSV file should correspond to the field paths you wish to import. For instance, a field named “name” located at the root of the entity should have “name” as its header. For nested fields, use the full path, such as “address.state.” When dealing with multi-valued fields, specify the index, like “phoneNumbers[0]” or “phoneNumbers[1].”

Data Format: The data format in the CSV file should match the type of each field being imported. Refer to the documentation for each field type to ensure you are using the correct format.

Template Creation: To create a CSV file template, you can often export existing records using field names instead of labels as a starting point.

Record Handling:

• Records will be created if they do not already exist in the system.
• If records already exist, they will be updated. To determine if a record exists, a unique field must be included in the CSV file’s headers. If multiple unique fields are present, the first one encountered will be used.

Importing into Related Entities: It is also possible to import records into related entities. For example, if you have a “contacts” entity with a relationship called “company” pointing to the “companies” entity, your CSV file headers can reflect this relationship structure:

company.name,company.type,firstName,lastName,email

Your CSV file includes headers like “company.name” and “company.type” referring to fields within the “companies” entity. In this scenario:

• The import process will attempt to match an existing company based on the “name” field (assuming “name” is a unique field) and update its “type” field if a match is found.

• If no match is found, a new record will be created in the “companies” entity, and it will be associated with the record in the “contacts” entity. This enables you to create records in multiple entities with just a single import.

The entire import process occurs within the context of a background job, ensuring efficient handling of the data.

POST /data/{entityName}/import
> Content-Type: multipart/form-data
> Accept: application/json
> token: token

Response #

A reference to the job in charge of perform the import.

POST /data/{entityName}/import
< Content-Type: application/json

{
  "jobLink": "/api/status/jobs/588f8357b45fc9000bc1bd2a",
  "jobId": "588f8357b45fc9000bc1bd2a"
}

Posible errors #

Samples #

// imports a few companies from a CSV file

POST /data/companies/import
> Content-Type: multipart/form-data
> Accept: application/json
> token: token

name,type
test1,a
test2,b
test3,c


POST /data/companies/import
< Content-Type: application/json

{
  "jobLink": "/api/status/jobs/588f3e65b45fc9000bc1baa7",
  "jobId": "588f3e65b45fc9000bc1baa7"
}

Export records #

PUT /data/{entityName}/export

This feature allows you to export records to a CSV file. You have the flexibility to apply filters to determine which records to export using a query and select specific fields to include in the export.

To specify which fields should be included in the CSV file, you can use the _fields parameter. Its usage is similar to queries, but with a few distinctions:

• You can include related fields, which are fields located in the entities pointed to by relationship fields. For instance, if you have a relationship field named “company” that references the “companies” entity, you can specify “company.type” to be included in the CSV file. If you only specify “company,” only the label will be exported.

• If you leave the _fields parameter empty, all fields will be included in the export, except for related fields.

• System fields such as "id," "label," and "version" are not included in the export.

This flexibility allows you to tailor your CSV exports to your specific needs.

Request #

PUT /data/{entityName}/export
> Content-Type: application/json
> Accept: application/json
> token: token

Response #

A reference to the job in charge of perform the import. To actually fetch the file you need to check when the job is finished and look into the results of the job, where you’ll find something like this:

{
  ...
  "hasErrors": false,
  "results": {
    "fileLink": "https://docs.slingrs.io/dev/runtime/api/files/588f864eb45fc9000bc1bd5c",
    "fileId": "588f864eb45fc9000bc1bd5c",
    "recordsExported": 283
  },
  "status": "FINISHED"
}

The field results.fileLink contains the URL to download the file. You need to pass the token in the headers when fetching the file or the token needs to be set in cookies.

PUT /data/{entityName}/export
< Content-Type: application/json

{
  "jobLink": "/api/status/jobs/588f8357b45fc9000bc1bd2a",
  "jobId": "588f8357b45fc9000bc1bd2a"
}

Posible errors #

Samples #

// exports companies with type 'b', with a maxium of 50 records

PUT /data/companies/export?type=b&_size=50
> Content-Type: application/json
> Accept: application/json
> token: token



PUT /data/companies/export?type=b&_size=50
< Content-Type: application/json

{
  "jobLink": "/api/status/jobs/588f3e65b45fc9000bc1baa7",
  "jobId": "588f3e65b45fc9000bc1baa7"
}

// exports companies with type 'b', with a maxium of 50 records but only the fields name, address->state and mainContact->email.

PUT /data/companies/export?type=b&_size=50&_fields=name,address.state,mainContact.email
> Content-Type: application/json
> Accept: application/json
> token: token


PUT /data/companies/export?type=b&_size=50&_fields=name,address.state,mainContact.email
< Content-Type: application/json

{
  "jobLink": "/api/status/jobs/588f3e65b45fc9000bc1baa8",
  "jobId": "588f3e65b45fc9000bc1baa8"
}

Audit logs #

Audit logs for one record #

GET /data/{entityName}/{id}/auditLogs

Returns the audit logs of a record. The entity needs to have audit logs enabled.

Request #

GET /data/{entityName}/{id}/auditLogs
> Accept: application/json
> token: token

Response #

The list of audit logs for that record, sorted from the newest to the oldest ones.

GET /data/{entityName}/{id}/auditLogs
< Content-Type: application/json

{
  "total": 2,
  "offset": "588f8b99b45fc9000bc1bfc5",
  "items": [
    {
      "id": "588f8ba7b45fc9000bc1bfce",
      "entityId": "57fce228e4b0f6600fdfb836",
      "entityName": "companies",
      "entityVersion": 57,
      "recordId": "588f8b99b45fc9000bc1bfc4",
      "recordName": "test1",
      "user": "dgaviola@slingr.io",
      "timestamp": 1485802407010,
      "ip": "::ffff:10.240.0.15",
      "eventType": "USER_RECORD_CHANGED",
      "eventCategory": "USER",
      "contextPath": "entities.companies.update",
      "recordDeleted": null,
      "deletionDate": null,
      "oldRecord": {
        "type": {
          "json": "a",
          "text": "{type:a}"
        },
        "addresses": {
          "json": null,
          "text": "{}"
        }
      },
      "newRecord": {
        "type": {
          "json": "b",
          "text": "{type:b}"
        },
        "addresses": {
          "json": null,
          "text": "{}"
        }
      }
    },
    {
      "id": "588f8b99b45fc9000bc1bfc5",
      "entityId": "57fce228e4b0f6600fdfb836",
      "entityName": "companies",
      "entityVersion": 57,
      "recordId": "588f8b99b45fc9000bc1bfc4",
      "recordName": "test1",
      "user": "dgaviola@slingr.io",
      "timestamp": 1485802393836,
      "ip": "::ffff:10.240.0.11",
      "eventType": "USER_RECORD_CREATED",
      "eventCategory": "USER",
      "contextPath": "entities.companies.create",
      "recordDeleted": null,
      "deletionDate": null,
      "oldRecord": {},
      "newRecord": {
        "name": "test1",
        "state": "active",
        "type": "a",
        "numberOfEmployees": null,
        "isCustomer": false,
        "contactInformation": {
          "phoneNumber": null,
          "email": null,
          "id": "588f8b99b45fc9000bc1bfc3",
          "label": "Contact Information"
        },
        "homepage": null,
        "taxId": null,
        "rating": null,
        "notes": null,
        "lastMeeting": null,
        "lastUpdate": 1485802380000
      }
    }
  ]
}

Posible errors #

Samples #

// gets the audit logs of a company record

GET /data/companies/588f8b99b45fc9000bc1bfc4/auditLogs
> Accept: application/json
> token: token



GET /data/companies/588f8b99b45fc9000bc1bfc4/auditLogs
< Content-Type: application/json

{
  "total": 2,
  "offset": "588f8b99b45fc9000bc1bfc5",
  "items": [
    {
      "id": "588f8ba7b45fc9000bc1bfce",
      "entityId": "57fce228e4b0f6600fdfb836",
      "entityName": "companies",
      "entityVersion": 57,
      "recordId": "588f8b99b45fc9000bc1bfc4",
      "recordName": "test1",
      "user": "dgaviola@slingr.io",
      "timestamp": 1485802407010,
      "ip": "::ffff:10.240.0.15",
      "eventType": "USER_RECORD_CHANGED",
      "eventCategory": "USER",
      "contextPath": "entities.companies.update",
      "recordDeleted": null,
      "deletionDate": null,
      "oldRecord": {
        "type": {
          "json": "a",
          "text": "{type:a}"
        },
        "addresses": {
          "json": null,
          "text": "{}"
        }
      },
      "newRecord": {
        "type": {
          "json": "b",
          "text": "{type:b}"
        },
        "addresses": {
          "json": null,
          "text": "{}"
        }
      }
    },
    {
      "id": "588f8b99b45fc9000bc1bfc5",
      "entityId": "57fce228e4b0f6600fdfb836",
      "entityName": "companies",
      "entityVersion": 57,
      "recordId": "588f8b99b45fc9000bc1bfc4",
      "recordName": "test1",
      "user": "dgaviola@slingr.io",
      "timestamp": 1485802393836,
      "ip": "::ffff:10.240.0.11",
      "eventType": "USER_RECORD_CREATED",
      "eventCategory": "USER",
      "contextPath": "entities.companies.create",
      "recordDeleted": null,
      "deletionDate": null,
      "oldRecord": {},
      "newRecord": {
        "name": "test1",
        "state": "active",
        "type": "a",
        "numberOfEmployees": null,
        "isCustomer": false,
        "contactInformation": {
          "phoneNumber": null,
          "email": null,
          "id": "588f8b99b45fc9000bc1bfc3",
          "nestedFieldLabel": "Contact Information",
          "id": "588f8b99b45fc9000bc1bfc3",
          "label": "Contact Information"
        },
        "homepage": null,
        "taxId": null,
        "rating": null,
        "notes": null,
        "lastMeeting": null,
        "lastUpdate": 1485802380000
      }
    }
  ]
}

Audit logs in entity #

GET /data/{entityName}/auditLogs

Returns the audit logs for all records in an entity, which needs to have audit logs enabled.

Request #

GET /data/{entityName}/auditLogs
> Accept: application/json
> token: token

Response #

The list of audit logs for that record, sorted from the newest to the oldest ones.

GET /data/{entityName}/auditLogs
< Content-Type: application/json

{
  "total": 3,
  "offset": "588f8ba7b45fc9000bc1bfce",
  "items": [
    {
      "id": "588f9757b45fc9000bc1bfe1",
      "entityId": "57fce228e4b0f6600fdfb836",
      "entityName": "companies",
      "entityVersion": 57,
      "recordId": "588f9757b45fc9000bc1bfe0",
      "recordName": "test2",
      "user": "dgaviola@slingr.io",
      "timestamp": 1485805399966,
      "ip": "::ffff:10.240.0.11",
      "eventType": "USER_RECORD_CREATED",
      "eventCategory": "USER",
      "contextPath": "entities.companies.create",
      "recordDeleted": null,
      "deletionDate": null,
      "oldRecord": {},
      "newRecord": {
        "name": "test2",
        "state": "active",
        "type": "c",
        "color": "#e1e1e1",
        "numberOfEmployees": null,
        "isCustomer": false,
        "contactInformation": {
          "phoneNumber": null,
          "email": null,
          "id": "588f9757b45fc9000bc1bfdf",
          "nestedFieldLabel": "Contact Information",
          "id": "588f9757b45fc9000bc1bfdf",
          "label": "Contact Information"
        },
        "homepage": null,
        "taxId": null,
        "rating": null,
        "notes": null,
        "lastMeeting": null,
        "lastUpdate": 1485805380000
      }
    },
    {
      "id": "588f8ba7b45fc9000bc1bfce",
      "entityId": "57fce228e4b0f6600fdfb836",
      "entityName": "companies",
      "entityVersion": 57,
      "recordId": "588f8b99b45fc9000bc1bfc4",
      "recordName": "test1",
      "user": "dgaviola@slingr.io",
      "timestamp": 1485802407010,
      "ip": "::ffff:10.240.0.15",
      "eventType": "USER_RECORD_CHANGED",
      "eventCategory": "USER",
      "contextPath": "entities.companies.update",
      "recordDeleted": null,
      "deletionDate": null,
      "oldRecord": {
        "type": {
          "json": "a",
          "text": "{type:a}"
        },
        "addresses": {
          "json": null,
          "text": "{}"
        }
      },
      "newRecord": {
        "type": {
          "json": "b",
          "text": "{type:b}"
        },
        "addresses": {
          "json": null,
          "text": "{}"
        }
      }
    }
  ]
}

Posible errors #

Samples #

// gets the last two audit logs in entity 'companies'

GET /data/companies/auditLogs?_size=2
> Accept: application/json
> token: token



GET /data/companies/auditLogs?_size=2
< Content-Type: application/json

{
  "total": 3,
  "offset": "588f8ba7b45fc9000bc1bfce",
  "items": [
    {
      "id": "588f9757b45fc9000bc1bfe1",
      "entityId": "57fce228e4b0f6600fdfb836",
      "entityName": "companies",
      "entityVersion": 57,
      "recordId": "588f9757b45fc9000bc1bfe0",
      "recordName": "test2",
      "user": "dgaviola@slingr.io",
      "timestamp": 1485805399966,
      "ip": "::ffff:10.240.0.11",
      "eventType": "USER_RECORD_CREATED",
      "eventCategory": "USER",
      "contextPath": "entities.companies.create",
      "recordDeleted": null,
      "deletionDate": null,
      "oldRecord": {},
      "newRecord": {
        "name": "test2",
        "state": "active",
        "type": "c",
        "color": "#e1e1e1",
        "numberOfEmployees": null,
        "isCustomer": false,
        "contactInformation": {
          "phoneNumber": null,
          "email": null,
          "id": "588f9757b45fc9000bc1bfdf",
          "nestedFieldLabel": "Contact Information",
          "id": "588f9757b45fc9000bc1bfdf",
          "label": "Contact Information"
        },
        "homepage": null,
        "taxId": null,
        "rating": null,
        "notes": null,
        "lastMeeting": null,
        "lastUpdate": 1485805380000
      }
    },
    {
      "id": "588f8ba7b45fc9000bc1bfce",
      "entityId": "57fce228e4b0f6600fdfb836",
      "entityName": "companies",
      "entityVersion": 57,
      "recordId": "588f8b99b45fc9000bc1bfc4",
      "recordName": "test1",
      "user": "dgaviola@slingr.io",
      "timestamp": 1485802407010,
      "ip": "::ffff:10.240.0.15",
      "eventType": "USER_RECORD_CHANGED",
      "eventCategory": "USER",
      "contextPath": "entities.companies.update",
      "recordDeleted": null,
      "deletionDate": null,
      "oldRecord": {
        "type": {
          "json": "a",
          "text": "{type:a}"
        },
        "addresses": {
          "json": null,
          "text": "{}"
        }
      },
      "newRecord": {
        "type": {
          "json": "b",
          "text": "{type:b}"
        },
        "addresses": {
          "json": null,
          "text": "{}"
        }
      }
    }
  ]
}

Files handling #

Slingr apps offer the capability to store various types of files that can later be downloaded, shared, or linked to fields within records.

When you need to reference a file within a record using a file field, it’s a typical practice to upload the file first. Once you obtain the unique ID of the uploaded file, you can then set it as the value of the corresponding file field in your record.

It’s important to note that if a file is not referenced by any record, it will be automatically deleted after a few hours. Therefore, it’s advisable to upload files only if you intend to link them to records within your app. Uploading files that are not used within your app is unnecessary and may result in their deletion.

Uploading files #

POST /files

This function allows you to upload a file to your app. The uploaded file will be stored temporarily until it is referenced by a record. If no record references the file within 12 hours, it will be automatically removed.

Request #

To upload a file, you must use a multi-part request. This method supports the uploading of files in any format.

POST /files
> Content-Type: multipart/form-data
> Accept: application/json
> token: token

Response #

The metadata of the uploaded file.

POST /files
< Content-Type: application/json

{
  "fileId": "588f9f1eb45fc9000bc1c010",
  "fileLink": "/files/588f9f1eb45fc9000bc1c010"
}

Samples #

// uploads a file

POST /files
> Content-Type: multipart/form-data
> Accept: application/json
> token: token

test file in multi-part


POST /files
< Content-Type: application/json

{
  "fileId": "588f9f1eb45fc9000bc1c010",
  "fileLink": "/files/588f9f1eb45fc9000bc1c010"
}

Downloading files #

GET /files/{id}

Downloads a file. This service is only available for developer and system users.

Request #

GET /files/{id}
> token:
> : token

Response #

Returns the file to download.

GET /files/{id}
> Content-Type: application/force-download
> Content-Disposition: attachment; filename=file.ext

//the content of the file

Possible errors #

Samples #

// fetches a file

GET /files/588f9f1eb45fc9000bc1c010
> token:
> : token

GET /files/588f9f1eb45fc9000bc1c010
> Content-Type: application/force-download
> Content-Disposition: attachment; filename=file.ext

// this is the content of the file

Downloading record files #

GET /data/{entityName}/{recordId}/files/{fileId}

Downloads a file that belongs to a specific record. User permissions check is performed.

Request #

GET /data/{entityName}/{recordId}/files/{fileId}
> Accept: application/json
> token: token

Response #

Returns the record file to download.

GET /data/{entityName}/{recordId}/files/{fileId}
> Content-Type: application/force-download
> Content-Disposition: attachment; filename=file.ext

// the content of the file

Possible errors #

Samples #

// fetches a file that belongs to a record

GET /data/companies/57fd2d65e4b0ce322b0c8665/files/588fa383b45fc9000bc1c014
> Accept: application/json
> token: token


GET /data/companies/57fd2d65e4b0ce322b0c8665/files/588fa383b45fc9000bc1c014
> Content-Type: application/force-download
> Content-Disposition: attachment; filename=file.ext

// this is the content of the file

Sharing files #

PUT /files/{id}/share

Shares a file through a public link. The link will be valid for an hour.

Request #

PUT /files/{id}/share
> Content-Type: application/json
> Accept: application/json
> token: token

Response #

The public link to download the file. This link won’t require any permission.

PUT /files/{id}/share
< Content-Type: application/json

{
  "sharedFileId": "588fa383b45fc9000bc1c014",
  "sharedFileLink": "/files/shared/588fa383b45fc9000bc1c014"
}

Samples #

//shares a file which will expire in one minute

PUT /files/588f9f1eb45fc9000bc1c010/share?ttl=60000
> Content-Type: application/json
> Accept: application/json
> token: token

PUT /files/588f9f1eb45fc9000bc1c010/share?ttl=60000
< Content-Type: application/json

{
  "sharedFileId": "588fa383b45fc9000bc1c014",
  "sharedFileLink": "/files/shared/588fa383b45fc9000bc1c014"
}

Fetch shared file #

Sharing files #

GET /files/shared/{id}

Downloads a shared file.

Request #

GET /files/shared/{id}
> Accept: application/json
> token: token

Response #

Returns the shared file to download.

GET /files/shared/{id}
> Content-Type: application/force-download
> Content-Disposition: attachment; filename=file.ext

//the content of the file

Possible errors #

Samples #

//fetches a shared file

GET /files/shared/588fa383b45fc9000bc1c014
> Accept: application/json
> token: token

GET /files/shared/588fa383b45fc9000bc1c014
> Content-Type: application/force-download
> Content-Disposition: attachment; filename=file.ext

//this is the content of the file

Monitoring and troubleshooting #

Logs #

Logs allow to know what’s going on in the app. The structure of a log is this one:

{
  "id": "57fce0bfe4b0f6600fdfb82c",
  "type": "APP",
  "subType": null,
  "level": "INFO",
  "message": "PUT /api/metadata/clearCache",
  "userEmail": "system@docs.slingrs.io",
  "adminUserEmail": null,
  "timestamp": 1476190399791,
  "ip": "10.64.2.3",
  "additionalInfo": {}
}

Get logs #

GET /status/logs

Query logs from the app.

Keep in mind that logs rotate and when the maximum size of logs is reached older ones are lost.

Request #

GET /status/logs
> Accept: application/json
> token: token

Response #

A list of logs in JSON format.

GET /status/logs
< Content-Type: application/json

{
  "total": 151
  "items": [
    {
      "id": "58907c10b45fc9000bc1c020",
      "type": "APP",
      "subType": "LOGIN",
      "level": "INFO",
      "message": "POST /login",
      "userEmail": "dgaviola@slingr.io",
      "adminUserEmail": null,
      "timestamp": 1485863952895,
      "ip": null
    },
    {
      "id": "58907c1bb45fc9000bc1c023",
      "type": "APP",
      "subType": null,
      "level": "INFO",
      "message": "GET /api/users/57fce0c3e4b0ce322b0c06b2?appsVersion=true",
      "userEmail": "dgaviola@slingr.io",
      "adminUserEmail": null,
      "timestamp": 1485863963701,
      "ip": "::ffff:10.240.0.11"
    },
    {
      "id": "589085b0b45fc9000bc1c02f",
      "type": "APP",
      "subType": null,
      "level": "INFO",
      "message": "Validation exceptions on record [test]. Error: [file: Content type is required when uploading a file and must be a string]",
      "userEmail": "dgaviola@slingr.io",
      "adminUserEmail": null,
      "timestamp": 1485866416124,
      "ip": null,
      "additionalInfo": {
        "recordLabel": "test",
        "errors": [
          {
            "code": "INVALID",
            "field": "file",
            "message": "Content type is required when uploading a file and must be a string"
          }
        ]
      }
    },
    {
      "id": "589085bdb45fc9000bc1c030",
      "type": "APP",
      "subType": "REST_API_RECORD_UPDATED",
      "level": "INFO",
      "message": "PUT /api/data/files/585aea800d29d300072484a8",
      "userEmail": "dgaviola@slingr.io",
      "adminUserEmail": null,
      "timestamp": 1485866429630,
      "ip": "::ffff:10.240.0.15"
    },
    {
      "id": "589085bfb45fc9000bc1c032",
      "type": "APP",
      "subType": null,
      "level": "INFO",
      "message": "Data record of type [files] with label [test] was changed successfully",
      "userEmail": "dgaviola@slingr.io",
      "adminUserEmail": null,
      "timestamp": 1485866431823,
      "ip": null
    },
  ]
}

Possible errors #

Samples #

//finds two logs for yesterday for one specific user

GET /status/logs?period=yesterday&userEmail=test@slingr.io&_size=2
> Accept: application/json
> token: token

GET /status/logs?period=yesterday&userEmail=test@slingr.io&_size=2
< Content-Type: application/json

{
  "items": [
    {
      "id": "58907c10b45fc9000bc1c020",
      "type": "APP",
      "subType": "LOGIN",
      "level": "INFO",
      "message": "POST /login",
      "userEmail": "test@slingr.io",
      "adminUserEmail": null,
      "timestamp": 1485863952895,
      "ip": null
    },
    {
      "id": "58907c19b45fc9000bc1c021",
      "type": "APP",
      "subType": null,
      "level": "INFO",
      "message": "GET /api/users/current",
      "userEmail": "test@slingr.io",
      "adminUserEmail": null,
      "timestamp": 1485863961326,
      "ip": "::ffff:10.240.0.16"
    }
  ],
  "total": 151
}

Post logs #

POST /status/logs

Creates a log. You only need to send the message and the level of log. Other fields will be calculated automatically. An optional additionalInfo object can be send to add extra fields.

Request #

POST /status/logs
> Content-Type: application/json
> Accept: application/json
> token: token

{
  "level": "INFO",
  "message": "This is a test log",
  "additionalInfo": {
    "test": "Additional info property"
  }
}

Response #

The created log in JSON format.

POST /status/logs
< Content-Type: application/json

{
  "id": "589085bdb45fc9000bc1c030",
  "type": "EXTERNAL",
  "subType": null,
  "level": "INFO",
  "message": "This is a test log",
  "userEmail": "test@slingr.io",
  "adminUserEmail": null,
  "timestamp": 1485866429630,
  "ip": null,
  "additionalInfo": {
    "test": "Additional info property"
  }
}

Possible errors #

{
  “code”: “validationErrors”, 
  “message”: “There are validation errors”,
  “errors”: [
   {
     “field”: “message”,
     “fieldLabel”: null,
     “code”: “required”,
     “message”: “Message cannot be empty”,
     “additionalInfo”: null
   }
  ]
 } 

Samples #

//creates a new log

POST /status/logs
> Content-Type: application/json
> Accept: application/json
> token: token

{
  "level": "INFO",
  "message": "This is a test log",
  "additionalInfo": {
    "test": "Additional info property"
  }
}


POST /status/logs
< Content-Type: application/json

{
  "id": "589085bdb45fc9000bc1c030",
  "type": "EXTERNAL",
  "subType": null,
  "level": "INFO",
  "message": "This is a test log",
  "userEmail": "test@slingr.io",
  "adminUserEmail": null,
  "timestamp": 1485866429630,
  "ip": "::ffff:10.240.0.15",
  "additionalInfo": {
    "test": "Additional info property"
  }
}

Jobs #

The API for jobs provides the capability to check various aspects of a job, including its status, progress, logs, and additional information. This helps you gain a comprehensive understanding of the job’s current state and execution.

This is the general job structure:

{
  "id": "588a02c13b063a0007605032",
  "label": "Executing action countEmployees on entity companies",
  "type": "EXECUTE_ACTION",
  "runBy": {
    "id": "57fce0c3e4b0ce322b0c06b2",
    "fullName": "Diego Gaviola"
  },
  "parentJob": null,
  "rootJob": null,
  "createDate": 1485439681643,
  "startDate": 1485439681652,
  "endDate": 1485439681807,
  "status": "FINISHED",
  "hasErrors": false,
  "progress": 100,
  "recordsCount": 0,
  "recordsProcessed": 0,
  "childrenJobsCount": 0,
  "childrenJobsProcessed": 0,
  "stoppable": true,
  "lowPriority": false,
  "data": {}
  "results": {}
}

{
  “results”: {
    “id1”: {
      “status”: “ok”,
      “response”: “response from action”
    },
    “id2”: {
      “status”: “error”,
      “errorMessage”: “error message”
    }
  }
}

{
  “results”: {
    “id1”: {
      “status”: “ok”,
      “response”: “response from action”
    },
    “id2”: {
      “status”: “error”,
      “errorMessage”: “error message”
    }
  }
}

{
  “results”: {
    “status”: “ok”,
    “response”: “response from action”
  }
}

Get one job #

GET /status/jobs/{id}

Gets one job by ID.

Request #

GET /status/jobs/{id}
> Accept: application/json
> token: token

Response #

The job in JSON format.

GET /status/jobs/{id}
< Content-Type: application/json

{
  "id": "588a02c13b063a0007605032",
  "label": "Execute action countEmployees from entity companies",
  "type": "EXECUTE_ACTION",
  "runBy": {
    "id": "57fce0c3e4b0ce322b0c06b2",
    "fullName": "Diego Gaviola"
  },
  "parentJob": null,
  "rootJob": null,
  "createDate": 1485439681643,
  "startDate": 1485439681652,
  "endDate": 1485439681807,
  "status": "FINISHED",
  "hasErrors": false,
  "progress": 100,
  "recordsCount": 0,
  "recordsProcessed": 0,
  "childrenJobsCount": 0,
  "childrenJobsProcessed": 0,
  "stoppable": true,
  "lowPriority": false
}

Possible errors #

Samples #

// gets a job by ID

GET /status/jobs/588a02c13b063a0007605032
> Accept: application/json
> token: token

GET /status/jobs/588a02c13b063a0007605032
< Content-Type: application/json

{
  "id": "588a02c13b063a0007605032",
  "label": "Execute action countEmployees from entity companies",
  "type": "EXECUTE_ACTION",
  "runBy": {
    "id": "57fce0c3e4b0ce322b0c06b2",
    "fullName": "Diego Gaviola"
  },
  "parentJob": null,
  "rootJob": null,
  "createDate": 1485439681643,
  "startDate": 1485439681652,
  "endDate": 1485439681807,
  "status": "FINISHED",
  "hasErrors": false,
  "progress": 100,
  "recordsCount": 0,
  "recordsProcessed": 0,
  "childrenJobsCount": 0,
  "childrenJobsProcessed": 0,
  "stoppable": true,
  "lowPriority": false
}

List jobs #

GET /status/jobs

Lists jobs in the app.

Request #

GET /status/jobs
> Accept: application/json
> token: token

Response #

A list of jobs in JSON format.

GET /status/jobs
< Content-Type: application/json

{
  "total": 54,
  "offset": "5890d8ddb45fc9000bc1c2cf",
  "items": [
    {
      "id": "5890d8deb45fc9000bc1c2d3",
      ...
    },
    {
      "id": "5890d8deb45fc9000bc1c2d1",
      ...
    },
    {
      "id": "5890d8ddb45fc9000bc1c2cf",
      ...
  ]
}

Samples #

// finds up to three finished jobs

GET /status/jobs?status=FINISHED&_size=3
> Accept: application/json
> token: token


GET /status/jobs?status=FINISHED&_size=3
< Content-Type: application/json

{
  "total": 50,
  "offset": "5890d8ddb45fc9000bc1c2cf",
  "items": [
    {
      "id": "5890d8deb45fc9000bc1c2d3",
      ...
    },
    {
      "id": "5890d8deb45fc9000bc1c2d1",
      ...
    },
    {
      "id": "5890d8ddb45fc9000bc1c2cf",
      ...
  ]
}

Get logs of a job #

GET /status/jobs/{id}/logs

Query logs from a job.

Request #

GET /status/jobs/{id}/logs
> Accept: application/json
> token: token

Response #

A list of logs in JSON format.

GET /status/jobs/{id}/logs
< Content-Type: application/json

{
  "total": 3,
  "items": [
    {
      "timestamp": 1485887710544,
      "level": "INFO",
      "message": "Starting processing"
    },
    {
      "timestamp": 1485887710546,
      "level": "INFO",
      "message": "Cleaning up"
    },
    {
      "timestamp": 1485887710704,
      "level": "INFO",
      "message": "Process completed"
    }
  ]
}

Possible errors #

Samples #

// finds logs for one job

GET /status/job/5890d8deb45fc9000bc1c2d3/logs
> Accept: application/json
> token: token



GET /status/job/5890d8deb45fc9000bc1c2d3/logs
< Content-Type: application/json

{
  "total": 3,
  "items": [
    {
      "timestamp": 1485887710544,
      "level": "INFO",
      "message": "Starting processing"
    },
    {
      "timestamp": 1485887710546,
      "level": "INFO",
      "message": "Cleaning up"
    },
    {
      "timestamp": 1485887710704,
      "level": "INFO",
      "message": "Process completed"
    }
  ]
}

Stop job #

PUT /status/jobs/{id}/stop

This action allows you to stop a job. If the job was running, it might take some time to stop gracefully. During this time, the status will be set to "STOPPING." Once the job has been successfully stopped in a graceful manner, the status will change to "STOPPED."

It’s important to note that jobs that have been stopped can be resumed.

Request #

PUT /status/jobs/{id}/stop
> Content-Type: application/json
> Accept: application/json
> token: token

Response #

The job in JSON format.

PUT /status/jobs/{id}/stop
< Content-Type: application/json

{
  "id": "588a02c13b063a0007605032",
  ...
  "status": "STOPPING",
  ...
}

Possible errors #

Samples #

stops a job

PUT /status/jobs/588a02c13b063a0007605032/stop
> Content-Type: application/json
> Accept: application/json
> token: token



PUT /status/jobs/588a02c13b063a0007605032/stop
< Content-Type: application/json

{
  "id": "588a02c13b063a0007605032",
  ...
  "status": "STOPPING",
  ...
}

Force to stop job #

PUT /status/jobs/{id}/forceStop

When attempting to stop a job, the system will first try to stop it gracefully. However, if the job continues to run and you need to forcibly terminate it, you have the option to force stop it, which will immediately terminate the job.

It’s important to keep in mind that forcibly stopping a job can lead to the interruption of the processing it was performing, potentially leaving data in an inconsistent or undesirable state. Therefore, it should only be used in exceptional cases where no other option is available.

Request #

PUT /status/jobs/{id}/forceStop
> Content-Type: application/json
> Accept: application/json
> token: token

Response #

The job in JSON format.

PUT /status/jobs/{id}/forceStop
< Content-Type: application/json

{
  "id": "588a02c13b063a0007605032",
  ...
  "status": "STOPPED",
  ...
}

Possible errors #

Samples #

// force to stop a job

PUT /status/jobs/588a02c13b063a0007605032/forceStop
> Content-Type: application/json
> Accept: application/json
> token: token


PUT /status/jobs/588a02c13b063a0007605032/forceStop
< Content-Type: application/json

{
  "id": "588a02c13b063a0007605032",
  ...
  "status": "STOPPED",
  ...
}

Cancel job #

PUT /status/jobs/{id}/cancel

Cancels a job. Only jobs that are in STOPPED can be canceled.

It’s important to note that jobs that have been canceled can be resumed.

Request #

PUT /status/jobs/{id}/cancel
> Content-Type: application/json
> Accept: application/json
> token: token

Response #

The job in JSON format.

PUT /status/jobs/{id}/cancel
< Content-Type: application/json

{
  "id": "588a02c13b063a0007605032",
  ...
  "status": "CANCELED",
  ...
}

Possible errors #

Samples #

// cancels a job

PUT /status/jobs/588a02c13b063a0007605032/cancel
> Content-Type: application/json
> Accept: application/json
> token: token


PUT /status/jobs/588a02c13b063a0007605032/cancel
< Content-Type: application/json

{
  "id": "588a02c13b063a0007605032",
  ...
  "status": "CANCELED",
  ...
}

Resume job #

PUT /status/jobs/{id}/resume

Resuming a job that has been stopped will allow it to continue execution from where it left off. However, if the job was not started when it was stopped, its status will be set to "PENDING" instead of "RUNNING."

Request #

PUT /status/jobs/{id}/resume
> Content-Type: application/json
> Accept: application/json
> token: token

Response #

The job in JSON format.

PUT /status/jobs/{id}/resume
< Content-Type: application/json

{
  "id": "588a02c13b063a0007605032",
  ...
  "status": "RUNNING",
  ...
}

Possible errors #

Samples #

//  resumes a job

PUT /status/jobs/588a02c13b063a0007605032/resume
> Content-Type: application/json
> Accept: application/json
> token: token

PUT /status/jobs/588a02c13b063a0007605032/resume
< Content-Type: application/json

{
  "id": "588a02c13b063a0007605032",
  ...
  "status": "RUNNING",
  ...
}