Infinite Blue Platform

Infinite Blue Platform REST v2.0

Download OpenAPI specification:Download

E-mail: support@infiniteblue.com Terms of Service

REST (REpresentational State Transfer) is an architectural style, that defines how applications interact using HTTP (HyperText Transfer Protocol). Using REST enables Platform to transfer information quickly and efficiently without using any defined data formats, as it usually exchanges JSON or XML documents within the client and database server.

The Primary HTTP methods used in APIs are :

  • A POST method creates new subordinate resource(s) to a given resource. The content of the new resource is usually enclosed in the body of the request.
  • A GET method reads the targeted resource and returns a representation in XML or JSON.
  • A PUT method is often considered as an update functionality. This method includes the updated version of the targeted resource in the request body. Note: The entire definition of the entity to be updated must be provided in the request body for Admin (/meta/*) endpoints - even if just 1 detail has to be updated.
  • A PATCH method is used to partially modify a targeted resource. While a PUT method places a resource in the target service, a PATCH method simply modifies the same resource, instead of replacing it. Currently, Platform does not support any PATCH methods.
  • A DELETE method deletes a targeted resource.

Infinite Blue Platform is now bundled with enriched REST APIs. This represents a significant aim to enhance capabilities to incorporate improved functionality. It also enables API developers to interact with Platform while accessing web services in a simple and adaptable manner.

This REST API Documentation essentially comprises of Record, User, Admin, and System APIs along with elaborate descriptions and examples for better understanding.

Note: Most examples in this documentation depict API implementation with reference to CRM application, available in Infinite Blue Marketplace.

To get started with formulating requests, please see the following

API Endpoint Versioning: Versioning for endpoints is supported by using a custom header "Accept-Version". Resource structures in META endpoints for requests and responses have been changed since the InfinteBlue Platform Release of v6.0 for "Application" (only GET), "Object", "Relationship", "Field", "BatchJob", "Triggers", "Authentication Profiles". If you wish to access a previous version of these endpoints, you must specify the header "Accept-Version" with the value "5.10.0.0". The consequent response confirms the version through the "Content-Version" header. If "Accept-Version" is not specified, then the latest version is taken as the default version.

Record

The Record API section describes operations pertaining to data records in Platform. From this section, API developers can understand how to formulate requests to create, update, retrieve, and delete data records as required. Here are a few important descriptions :

Data Records : A data record is a string of field data within an object definition. For instance, a data record can hold all relevant information about an individual, such as his name, country, email, etc.

Related Records: Relationships can be created between records if they need to be attached. For instance, if 4 (child) records need to be attached to one (parent) record, then a relationship can be established between them. Once the attachment of records is successful, the records are called as related records.

Field Data: Field data implies field integration names and values for the field.

To get started with formulating record creation requests, and understand the value formats, please see Field Types

Find out more about records

Retrieve Object Records

This request retrieves all records that fall under the filter category specified in the request query. If the request query has fields(fieldList) passed as query parameters, then it retrieves only specified field values of those records that satisfy the filter condition.If the query parameter specifies ALL fields, then it retrieves the records based on the filter value with all object field values. If no fields are passed as query parameters, then the fields present in the default view(all leads) are returned. A view can also be passed as a query parameter.

Example : If the filter is set to a particular country(where filterName is country and filterValue is the country-name), then all records from that country are retrieved.

Start and count : If positions of the required data records are to be specified, then start and count can be used. Start and count are used in a conjunction for pagination.

  • Example 1: start=2 and count=3, returns the 3rd, 4th, and 5th data records of the array as a response.
  • Example 2: start=5 and count=2 returns the 6th and 7th data records of the array as a response.

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object that the record belongs to must be specified.

query Parameters
viewIntegrationName
string

The integration name of the view. If this string value is not provided, then the first view based on the order number is considered as the default integration name.

filterName
string

The name of the field to filter the output using the equals option (replaces the filter set in the view, if any).

filterValue
string

The value of the field to filter the output using the equals option.

fieldList
string

A comma-separated list of field integrationNames. If present, only fields from this list are included in the output. The fields should be a part of the given view, else ignored. Provide ALL as the value to include all fields in the object definition.

start
integer <int32>

The Start and count are used in a conjunction for pagination. Start denotes the position of the first record in the set of all records. The first record is at position 0 by default. So start=0 indicates the first record, start=2 indicates the third record, and so on.

count
integer <int32>

The Start and count are used in a conjunction for pagination.

  • Example 1: start=2 and count=3, returns the 3rd, 4th, and 5th data records of the array as a response.
  • Example 2: start=5 and count=2 returns the 6th and 7th data records of the array as a response.

Responses

Response samples

Content type
application/json
Example

In this example, we have retrieved a Lead Object record in CRM Application, whose country(filterName=country) is Serbia(filterValue=CS).

The consequent response returns record(s) that fall under the specified filter category (country=CS). The fields here are the ones present in the default view(all leads). Only one record happens to fall under the specified filter. Hence the response has returned that one record.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update Object Records

This request comes in handy when we need to update/modify the same set of existing-values for multiple records. This simplifies the task of updating multiple records in one go, by eliminating the need to individually update every record.

Example: Using this request, records can be attached to multiple records in one go, and related records of multiple records can be updated.

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

Request Body schema: application/json

As demonstrated in the examples, the values to be updated are mentioned inside the function(request) body along with the IDs for the respective records. IDs of all records to be updated, must be specified correctly. Only those already existing values that need to be updated/modified must be added in the request-body.

Record field values such as city, country, rating, title, email, status, mobile phone, annual revenue, etc. that need to be updated can be specified in the request body. The request body must contain field data in pairs, each pair constitutes of a field integration name and its corresponding value (for example, in the field data :"lastName":"Storks", lastname is the field integration name and Storks is its value).

object

Responses

Request samples

Content type
application/json

In this example, we are updating the lead object with the following in CRM application:Status("status":"Working - Contacted"), Email Opt Out("email_opt_out":true), Industry("industry":"Energy"), website("website":"www.storks.com").

We are also attaching two account records to multiple records.

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json

In this example, we have updated the lead object with the following in CRM application:Status("status":"Working - Contacted"), Email Opt Out("email_opt_out":true), Industry("industry":"Energy"), website("website":"www.storks.com").

We have also attached two account records to multiple records.

The consequent response confirms the successful update of the lead object with the following in CRM application:Status("status":"Working - Contacted"), Email Opt Out("email_opt_out":true), Industry("industry":"Energy"), website("website":"www.storks.com"). Two account records have been successfully attached to multiple records ("R1850980":[109586, 109344]).

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Create Record

Request Description This request is used to create a data record, with all its relevant details, such as name, status, etc. One or many records can be created at once using this request.

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

Request Body schema: application/json

In the request body, the object name along with the record field values such as city, country, rating, title, email, status, mobile phone, annual revenue, etc. can be mentioned. The request body must contain field data in pairs; each pair constitutes of a field integration name and its corresponding value (for example, in the field data :"lastName":"Storks", lastname is the field integration name and Storks is its value). Different records can have different number of details/parameters. There is no fixed number of parameters needed to create a record. Records can be created at first with a few details using the POST request, and can be later updated with more details.

Important: For the creation of a record to be successful, it is mandatory that all field integration names labelled “Required” must be present in the request body. Along with mandatory field integration names, optional fields can also be added.

object

Responses

Request samples

Content type
application/json
Example

This example shows a sample request to create a new record in the Lead Object, in CRM Application. As demonstrated in the request below, the attributes of the record such as name, country, city, email, company, etc. are specified in the body of the request. All relevant details of a record can be specified in this manner.

{
  • "lastName": "Storks",
  • "country": "BR",
  • "city": "Skpje",
  • "rating": "Warm",
  • "title": "Mr",
  • "email_opt_out": false,
  • "company": "Topiczoom",
  • "email": "adolphe.storks@company.com",
  • "firstName": "Adolphe",
  • "mobilePhone": "988-564-8338",
  • "fax_opt_out": false,
  • "annual_revenue": 7801467.07,
  • "R1850980": [
    ],
  • "status": "Open - Not Contacted"
}

Response samples

Content type
application/json
Example

A record has been created with a unique record ID 109585. The object name is indicated as lead.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Delete Object Record(s)

This request is used in cases where multiple records with known record IDs need to be deleted in a single instance. Multiple record IDs can be specified in the request query by separating them with commas. The response confirms the deletion of given records with their respective IDs.

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

query Parameters
recordIds
required
string

Comma separated list of record IDs.

Responses

Response samples

Content type
application/json

In this example we have deleted multiple records(recordIds=109442,109466,109439,109499,109430,109488) from Lead Object in CRM application.

This response confirms the deletion of records with IDs 109442,109466,109439,109499,109430,109488.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Count Object Records

This request is used to retrieve the number of records that fall under a particular filter/view specified in the request query.

Example: If a view is mentioned in the query, then the number of records that have the specified view is returned as the response.

Since this request is used to retrieve the number of records that fall under a particular filter/view specified in the request query, the filter name must be specified in the request query, along with the object name. For example, if a view is mentioned in the query, then the number of records that have the specified view is returned as the response.

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

query Parameters
viewIntegrationName
string

The integration name of the view. If not provided, the first view according to the order number is considered as the default name.

Responses

Response samples

Content type
application/json
Example

In this example, we have retrieved the number of all Lead Object records in CRM application.

This consequent response retrieves the number of all Lead Object records in CRM application, which happens to be 100.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Run Trigger On Record(s)

A trigger is a stored procedure that is automatically executed when certain events occur. Triggers can perform automated validation, notification, and data manipulation. You can configure triggers to fire upon events such as record creation, update, and deletion, as a result of a workflow action, and you can also run triggers manually. They may eliminate the need to write a lengthy program. When an action needs to be performed, its respective trigger can be invoked.

Note: When a trigger is invoked, it affects only those object records whose record IDs are specified in the request body. The different types of triggers include ‘Object Script’, ‘Send Email’, Workflow Status', ‘Create New Record’, ‘Attach Related Record’, ‘Update Field Value’, etc. For more information, see Trigger Overview.

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

triggerIntegrationName
required
string

The integration name of the trigger. This is unique across the object.

query Parameters
runValidations
boolean

If set to true, checks validation formula before running the trigger. This is set to false by default.

runRecursions
boolean

When true, configures the trigger to run recursively, if recursive properties on the trigger definition page are set. Defaults to false if the properties are not set.

Note: For example, the Recursion settings could be such that the trigger gets fired once in every 5 months, for 10 times. This would mean that the total timespan that the trigger runs for is 5*10=50 months, and in these 50 months the trigger is fired exactly 10 times.

runDelay
integer <int64> >= 0

Schedule trigger to run asynchronously after given delay (in ms) from current time

runAsJob
boolean

Schedule trigger to run as large job with enhanced monitoring and cancellation capabilities

Request Body schema: application/json

IDs of records that the trigger must run on. If you want the trigger to run on all records, then do not specify any record IDs.

recordIds
Array of integers <int64> [ items <int64 > ]

Responses

Request samples

Content type
application/json
Example

Consider that in a CRM application, a Send Mail trigger has been created on the lead object. send_mail is the triggerIntegrationName for a trigger that belongs to the ‘Send Mail’ type. The contents of the email are based on the email-template. This request is to invoke the trigger on the records : 109585 and 109587. This means that the trigger email will be sent to the corresponding email recipients only. Since runValidations is not specified, it is False (by default).

{
  • "recordIds": [
    ]
}

Response samples

Content type
application/json
Example

Consider that in a CRM application, a Send Mail trigger has been created on the lead object. send_mail is the triggerIntegrationName for a trigger that belongs to the ‘Send Mail’ type. The contents of the email are based on the email-template. This request is to invoke the trigger on the records :109585 and 109587. This means that the trigger email will be sent to the corresponding email recipients only. Since runValidations is not specified, it is False (by default).

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve Record

This request is used to retrieve a record with a known record ID. If record fields are specified in the request query along with the record ID, then the specified field values only are returned as a response. If no fields are specified with the record ID, then records are returned with all field values.

If record fields are specified in the request query along with the record ID, then the specified field values only are returned as a response. If no fields are specified with the record ID, then records are returned with all field values.

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

recordId
required
string

A string containing the record ID.

query Parameters
fieldList
string

A comma-separated list of field names. If present, only fields from this list are included in the output.

Responses

Response samples

Content type
application/json
Example

In this example, we have retrieved a Lead Object record with a known record ID(109472), in CRM application.

The consequent response retrieves a Lead Object record with a known record ID(109472), in CRM application.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update Record

This request is used to update one or more field values for a particular record in an application, such as city, country, rating, title, email, status, mobile phone, annual revenue, etc.

Path Parameters: These include the integration name of the object and the record ID.

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

recordId
required
string

A string containing the record ID.

Request Body schema: application/json

Those already-existing field value(s) that need to be updated/modified for a particular record in an object, must be specified in the request body.

Important: The request body must contain field data in pairs; each pair constitutes of a field integration name and its corresponding value (for example, in the field data :"lastName":"Storks", lastname is the field integration name and Storks is its value). Using this request, account records can be attached to a record, and related records can be updated.

Record field values such as city, country, rating, title, email, status, mobile phone, annual revenue, etc. that need to be updated can be specified in the request body.

Note: A record for an object can be updated by using only those field integration names that belong to that particular object, whether they are mandatory or optional.

object

Responses

Request samples

Content type
application/json

In this example, we are updating the following in the Lead Object in CRM Application :Status("status":"Working - Contacted"), Email Opt Out("email_opt_out":true), Industry("industry":"Energy"), website("website":"www.storks.com"), and attaching two account records to the current record("R1850980":[109586,109344]).

{
  • "R1850980": [
    ],
  • "email_opt_out": true,
  • "industry": "Energy",
  • "status": "Working - Contacted",
  • "website": "www.storks.com"
}

Response samples

Content type
application/json

In this example, we have updated the following in the Lead Object in CRM Application :Status("status":"Working - Contacted"), Email Opt Out("email_opt_out":true), Industry("industry":"Energy"), website("website":"www.storks.com"), and attached two account records to the current record("R1850980":[109586,109344]).

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Delete Record

This request is used to delete a single record with a known record ID. The record ID is specified in the request query; the consequent response confirms the deletion of the particular record with the specified record ID.

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

recordId
required
string

A string containing the record ID.

Responses

Response samples

Content type
application/json

In this example, we have deleted a record from Lead Object, in CRM application.

This response confirms the deletion of the specified record from Lead Object, in CRM application.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve Field Value

This request retrieves file upload and image upload field values for a specific record, based on the field names specified in the request body. The response returns the values of the fields passed in the request.

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

recordId
required
string

A string containing the record ID.

fieldIntegrationName
required
string

The integration name of the field.

query Parameters
output
string
Enum: "raw" "json"

This parameter applies to only file input fields. If it is not specified, its default value is "json" and returns meta-data and base-64 encoded content of the file. If specified as "raw", the file is returned in a raw format.

Responses

Response samples

Content type
application/json

In this example we are retrieving details of the userProfilePic field. The response returns all relevant details of the field userProfilePic including the fileName, fileData/value, contentType, etc.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update Advanced field

Updates only the following Advanced type of fields

  • File Upload
  • Image Upload

Request Description This request can be used to set or update advanced type of fields such as images and documents for a single specific record at a time. The field value can either be set for the first time, or it can be updated from an old value to a new value

Note for your reference For instance, if a field is to be updated for a particular record, then the contentType must specify what type of file is being uploaded. The value parameter is applicable only for file upload fields and the input value can be the file itself or a Base-64 encoded binary value of the file. If the value is a Base-64 encoded binary value of the file, then a parameter called fileName must imply the new name of the file being uploaded in the request. For instance, a Base-64 encoded binary value of a file to be uploaded can be “iVBORw0KGgoAAAANSUhEUgAAAQAAAA………” and while uploading it as a field value, its new fileName can be “XYZ.png”. If the value is the file name itself, then the need to use fileName is eliminated. Both these parameters are specific to the new file being uploaded, as opposed to old files(if any)

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

recordId
required
string

A string containing the record ID. Every record has a unique record ID.

fieldIntegrationName
required
string

The integration name of the field.

Request Body schema:
value
string <base64>

The request body must contain the value, the type of file, and the type of content. Value is applicable only for file upload fields. The input value can be the file name itself or Base-64 encoded binary value of the file. The type of content varies - for example,image/gif is used for an image in the GIF format, and text/html is used for text with embedded HTML commands. fileName is the original name of file being uploaded. It is applicable only for file upload fields (if the value is given as Base-64 encoded binary).

contentType
string

MIME content type of uploaded data. It is applicable only for file upload fields (if the value is given as Base-64 encoded binary). For example,image/gif is used for an image in the GIF format, and text/html is used for text with embedded HTML commands.

fileName
string

Original name of file being uploaded. It is applicable only for file upload fields (if the value is given as Base-64 encoded binary).

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
Example

The consequent response confirms that the user profile picture has been updated/set for the user ID specified in the request. In the response below, Field "User Profile Pic" has been updated on Daniel Romano is returned.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve Related Records

Related records for a particular record can be retrieved using this request. Child records of a parent record can be retrieved

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

recordId
required
string

A string containing the record ID.

relIntegrationName
required
string

The integration name of the relationship

query Parameters
getChildren
boolean

This parameter applies to hierarchical relationships. Default value is false. This value determines whether to retrieve Parent field's value or Child field's value for the given hierarchical relationship.

Responses

Response samples

Content type
application/json
Example

In this example, we are getting related account IDs for lead object record(109443) in CRM application. The relIntegrationName of the relationship between these records is R1850980.

The consequent response returns the record IDs of all related records of the lead object record(109443). That is, it returns the records attached to the lead object record with the relationship R1850980.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Attach Records

Relationships can be created between records if they need to be attached. For instance, if 4 (child) records need to be attached to one (parent) record then a relationship can be established between them.Once the attachment of records is successful, the records are called as related records.

Note- Already attached records are overridden with the new ones.

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

recordId
required
string

A string containing the record ID.

relIntegrationName
required
string

The integration name of the relationship

Request Body schema: application/json

In the request body, it is necessary to specify the record IDs that we wish to attach to a particular record.

recordIds
Array of integers <int64> [ items <int64 > ]

List of record IDs to be attached.

Responses

Request samples

Content type
application/json
Example

In this request, we are attaching 2 account records with record IDs 109586 and 109344 to the lead object record with record ID 109585, in CRM application. The relIntegrationName is R1850980. It is necessary to specify the record IDs of the records we wish to attach to a particular record, along with the record ID of the record that the attachment is being made to. Hence in the request, the record IDs of the 2 account records are specified along with the record ID of the lead object record. The consequent response confirms the success of the request made. A message that resembles 2 records have been attached. is returned thereby confirming the successful attachment of 2 account records with record IDs 109586 and 109344 to the lead object record with record ID 109585.

{
  • "recordIds": [
    ]
}

Response samples

Content type
application/json
Example

In this example, we are attaching 2 account records with record IDs 109586 and 109344 to the lead object record with record ID 109585, in CRM application. The relIntegrationName is R1850980.

The consequent response confirms the success of the request made. A statement 2 records have been attached. is returned thereby confirming the successful attachment of 2 account records with record IDs 109586 and 109344 to the lead object record with record ID 109585.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Detach Records

If related records are no longer required to be attached, then they can be detached using this request

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

recordId
required
string

A string containing the record ID.

relIntegrationName
required
string

The integration name of the relationship

query Parameters
recordIds
required
string

A comma separated list of record IDs.

Responses

Response samples

Content type
application/json

In this example, we are detaching a related account(109586) from given lead object record(109585), in CRM application.

The consequent response confirms the detachment of a related account(109586) from given lead object record(109585), by returning 1 records have been removed.

Note: The response only returns information relevant to the request made. Information relevant to other records that are still attached after the detachment of the specified record, will not be returned. For instance, in this example, the lead object record actually had 2 related records :109586,109344, of which the record(109586) was detached according to the request made. The record (109344) is still attached to the lead object record, but this is not specified in the response.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Run Workflow Action

This request runs a workflow action on a record. For objects in dedicated tables, you must specify the objName parameter. Workflow status indicates the current status of a record, and a workflow action changes the workflow status to the desired status. To define a workflow action, you must specify the workflow action display name (For example, the workflow actions could be working, closed, etc.) The default workflow status is usually open, until a workflow action is run. The consequent response returns a statement that resembles"Action run is successful", confirming the successful transition of the record from one workflow status to another.

Authorizations:
Api-KeyJWT
path Parameters
objectIntegrationName
required
string

The integration name of the object.

recordId
required
string

A string containing the record ID.

actionIntegrationName
required
string

The integration name of the action.

Request Body schema: application/json

Optional Map of field integration names to values.

object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json

This example shows a sample request to change the workflow status by running an action on the record in the Lead Object, in a CRM Application. The action requested in the request below is Working-Contacted, meaning that post the submission of the request, the final workflow status of the record 109585 would be Working-Contacted. This means that regardless of what the current workflow status of the record is, we want the the final workflow status to be as specified in the request.

The above request runs the “Working-Contacted“ workflow action on the record (109585) and thus changes the workflow status to “Working - Contacted“. "Action run is successful" confirms that the workflow status has been changed for the specified record.

{
  • "code": 200,
  • "message": "Action run is successful",
  • "results": [
    ]
}

Data Import

If several records need to be created or updated in bulk, then this can be done by using a CSV file, rather than individually. If values for a particular field need to be updated for a huge number of records at once, then this request comes in handy. For instance, if a huge number of employee details need to be created at once, or a huge amount of employee data needs to be updated, then this request can be used.

Note- A Content-Type HTTP header with a value text/csv since the request body contains CSV data.

Authorizations:
Api-KeyJWT
query Parameters
mapIntegrationName
required
string

The integration name of a previously created Data Import Map.

fieldIntegrationName
string

The integration name of a unique field(with "Do not allow duplicates" attribute) used to identify records whose fields need to be updated.

triggerIntegrationName
string

The integration name of a Unique Fields Combination trigger to be updated.

synch
boolean

Can be set to True or False(Default Value is False).

  • If set to true, the import is processed synchronously and the IDs of the created records are returned.
  • If set to false, the import is processed asynchronously. The user will receive an email with the results of the import.
  • If it is not set, then the default boolean value is False.
importType
integer <int32>

The import type can be one of the following (Default Value is 0 - Create new record) -

  • 0 - Create new records.
  • 1 - Update existing records
  • 2 - Create or update records
  • 3 - Delete existing records
importMode
integer <int32>

Specifies the import mode. Can be one of the following -

  • 0 - Normal - Runs all triggers and creates picklist values on the fly if createAction is true. Note It is best to use this for medium-sized uploads.
  • 1 - TEST - Limits upload to five records at a time and displays results including debug information from triggers. Creates picklist values on the fly if createAction is true. Used to test before loading a full set of data.
  • 2 - BULK - Does not run triggers and does not create picklist values on the fly. Optimized for fast processing of large imports.
createAction
boolean

Specifies whether to create picklist values on the fly while importing -

  • When set to true, picklist values are created.
  • When set to false, picklist values are not created. The importMode parameter must be 0 or 1 for picklist values to be created. Default value is false.
treatEmptyCellAsNull
boolean

Specifies whether to treat empty spreadsheet cells as NULL values for updated records -

  • When set to true, sets empty value to updated record.
  • When set to false, ignore empty values from excel and keeps the record value as is. Default value is false.
Request Body schema: text/csv

The request body can contain the CSV data with a header row containing field integration names such as Contact, Job Title, Account, Phone, Email Address, etc. with their corresponding values in the following rows such as "Tom Williams", "Software Engineer", "", "(780)780-0780", "tom.williams@abc.com".

Note: This CSV data must be in-line with the field mappings saved in "Data Import Map".

string <binary>

Responses

Response samples

Content type
application/json
Example

In this example, we are creating records in the Contact object of CRM Application. Before we get to the part where we create the records, it is essential to have a Data Import Map already in place with mapping fields and spreadsheet columns. To create a Data Import Map, use the CSV file attached below.

The consequent response returns the IDs of created records along with a message that contains the following information:

  • Data import start date and time
  • The name and size of the file (Since CSV data is passed in the request body, the standard CSV file name - upload.csv is returned.)
  • The maximum records allowed
  • The number of already existing records
  • The number of records created
  • The number of errors
  • The import finish date and time.

Note: The total number of records, would therefore be the sum of already existing records and newly created records.

{
  • "code": 200,
  • "message": "\nImport: Contact\nStarted at 02/03/2021, 2:56 PM\nUploaded file: upload.csv Size: 1 KB\n\nMaximum 2500000 records allowed, 241 records already exist.\n\n=====================================================\nCreated records: 2\nNumber of errors: 0\nFinished at 02/03/2021, 2:56 PM\n",
  • "results": [
    ]
}

List of Running jobs

This request is used to retrieve the runtime information of the jobs.

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json
{
  • "description": "In this example, we are retrieving the runtime information of the jobs.",
  • "value": {
    }
}

Details of a Running job

This request is used to retrieve the detailed information of a job whose ID is specified in the request.

Authorizations:
Api-KeyJWT
path Parameters
id
required
string

A string containing the job ID. Every job has a unique job ID.

query Parameters
fetchErrorFile
boolean
Default: false

Retrieves the error file for the specific job.

fetchFile
boolean
Default: false

Retrieves the file for the specific job.

Responses

Response samples

Content type
application/json
{
  • "description": "In this example, we are retrieving the detailed information of a job whose ID is specified in the request.",
  • "value": {
    }
}

Get Jobs History Count

This request retrieves the number of jobs in the job history.

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json
{
  • "description": "In this example, we are retrieving the number of jobs in job history.",
  • "value": {
    }
}

Get Jobs History

This request retrieves the complete job History.

Authorizations:
Api-KeyJWT
query Parameters
start
integer <int32>

For pagination, the parameters - start and count are used in conjunction. The position of the first record in the set of all records is denoted by start. By default, the first record is at position 0. So start=0 represents the first record, likewise start=2 represents the third record.

count
integer <int32>

For pagination, the parameters - start and count are used in conjunction. count represents the number of jobs to be chosen for pagination. If count=4`, the pagination is set to 4 jobs.

Responses

Response samples

Content type
application/json
{
  • "description": "In this example, we are retrieving the Job history.",
  • "value": {
    }
}

Admin

The Admin API section describes operations that can be performed by tenant administrators. These involve creating, updating, retrieving, or deleting a field, object, application, relationship, role, view, permission, authentication profile, portal, etc. in Platform. From this section, API developers can understand how to formulate requests to perform administrative operations. Here are a few important descriptions :

Object Definition : An Object holds the entire schema structure of the data fields. In simple, Object definitions are the containers for fields, which define the attributes and properties that specify how the individual records are structured, how they will behave, and how they can be accessed. For more information, see Object definition overview..To access the previous version of this endpoint, you must provide a header Accept-Version with the value, 5.10.0.0. The latest version, 6.0.0.0 is the default version.The Content-Version in the response indicates the version accessed.

Field : Field contains a defined set of information for any corresponding object definition. A field can be of any type - Text, Checkbox, Currency, Decimal, Integer, Date, Time, Email, URL, Password, etc.To access the previous version of this endpoint, you must provide a header Accept-Version with the value, 5.10.0.0. The latest version, 6.0.0.0 is the default version.The Content-Version in the response indicates the version accessed.

Relationship : A relationship definition specifies cardinality (how many records of one object type can be related to another) between objects. For more information, see Relationships between objects..To access the previous version of this endpoint, you must provide a header Accept-Version with the value, 5.10.0.0. The latest version, 6.0.0.0 is the default version.The Content-Version in the response indicates the version accessed.

View : A view is a result set, a list of records that users can act on individually or in bulk. When you create an object definition, Platform creates a list view of all records of that object type. For more information, see Working with views.

Trigger : A trigger is a stored procedure that is automatically executed when certain events occur. Triggers can perform automated validation, notification, and data manipulation. A tenant admin can configure triggers to send emails, create audit trail records, validate record data, update field values, change workflow status, create new records, etc.To access the previous version of this endpoint, you must provide a header Accept-Version with the value, 5.10.0.0. The latest version, 6.0.0.0 is the default version.The Content-Version in the response indicates the version accessed.

Batch Job : Platform Batch Jobs can be used to schedule periodic system maintenance, notification, and integration tasks. Batch jobs use the permissions set on each object for the Query API.To access the previous version of this endpoint, you must provide a header Accept-Version with the value, 5.10.0.0. The latest version, 6.0.0.0 is the default version.The Content-Version in the response indicates the version accessed.

Authentication Profile : Authentication profiles include the authentication parameters along with authentication method to be used for authentication. Authentication is essentially the process of verifying a user’s identity using credentials. Authentication profiles can be created, updated, retrieved, and deleted on requirement basis.To access the previous version of this endpoint, you must provide a header Accept-Version with the value, 5.10.0.0. The latest version, 6.0.0.0 is the default version.The Content-Version in the response indicates the version accessed.

Portals : Portals are essentially external-facing web applications built using the same components as standard Platform applications. Portals typically run on a corporate website or intranet. You can create portal pages to display dynamic lists of records, to allow creation of records through custom forms, and to invoke triggers and custom business logic. For more information, see Platform Portals.

List Application Definitions

This request is used by a tenant admin to retrieve the information of all applications installed in a tenant

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json

In this example request, a tenant admin has retrieved all application definitions installed in a tenant. In the current scenario there are only 2 applications(Infinite Blue and CRM).

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Install Application

This request is used by a tenant admin to install a new application definition using an XML file/content.

Note: To prevent compatibility issues, do not install applications built on a higher platform version onto a lower version. This may result in unexpected behaviour or functionality issues.

Authorizations:
Api-KeyJWT
query Parameters
overrideChanges
boolean
Default: true

When set to true, the existing application components are overwritten with the latest updates. When set to false, only the new application components included in this update are received without any updates to the existing components. For instance, if overrideChanges=false, the changes made to existing fields, pages, views, templates, portals, portal pages, etc. are not reflected; only the new components are reflected.

Note: This is applicable only when using an XML file/content.

overridePermissions
boolean
Default: true

When set to true, the existing permissions are overwritten with the latest updates.

When set to false, the changes made by the publisher to the existing role level permissions are ignored.

Note: This is applicable only when using an XML file/content.

ignoreWarnings
boolean
Default: false

When set to true, any warnings would not prevent the installation of the application.

When set to false, any warnings would prevent the installation of the application.

Prior to 6.6.1.0, application installations were possible with warnings. To allow application installations with any warning, you can also use the header Accept-Version with value 6.6.0.0 or less

Note: This is applicable only when using an XML file/content.

Request Body schema:

The XML file or content of the application, must be specified in the body of the request.

string

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json

In this example, a tenant admin is installing an application called CRM.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Test Install Application

Validate the application for any errors or warnings prior to installation.

Authorizations:
Api-KeyJWT
Request Body schema: application/xml

The XML file or content of the application, must be specified in the body of the request.

string

Responses

Response samples

Content type
application/json
Example

In this example, a tenant admin is validating application XML that has errors.

{
  • "code": 200,
  • "message": "Validation performed successfully. Please check errors or warnings in the 'results'",
  • "results": [
    ]
}

Test Generate Application

Validate the application for any errors or warnings prior to XML generation.

Authorizations:
Api-KeyJWT
path Parameters
appIntegrationName
required
string

The integrationName of the application.

Responses

Response samples

Content type
application/json
Example

In this example, a tenant admin validating generation an application that has an error but no warnings.

{
  • "code": 200,
  • "message": "Validation performed successfully. Please check errors or warnings in the 'results'",
  • "results": [
    ]
}

Retrieve Application Definition

This request is used by a tenant admin to retrieve the complete description of a Platform application definition as an XML /JSON script, by specifying its appIntegrationName (as a path parameter).

Authorizations:
Api-KeyJWT
path Parameters
appIntegrationName
required
string

The integrationName of the application.

query Parameters
isXML
boolean
Default: false
  • If set to `true`, the application description is returned in XML format.
  • If set to `false`, the application description is returned in JSON format.
  • The default format is JSON.
version
integer <int32>

The version of the application XML to be generated. When no value provided, the version of generated application XML is set incrementally.

Note: This parameter is applicable only when isXML is true.

lockStatus
string (AppLockStatusEnum)
Enum: "UNLOCKED" "PARTIALLY_LOCKED" "LOCKED"

The lock status of the application XML to be generated. The user can choose any of the following values:

  • UNLOCKED: (default) The generated application XML allows the users to modify all application's components.
  • PARTIALLY_LOCKED: The generated application XML prevents the users to modify the application's components which are selected in Partial Lock Preferences.
  • LOCKED: The generated application XML does not allow the users to modify any application's components.

Note: This parameter is applicable only when isXML is true.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Update Application Definition

This request is used by a tenant admin to update an already existing application. For instance, if a new version of an application has been released, then the tenant admin can update the application to the latest version.

Authorizations:
Api-KeyJWT
path Parameters
appIntegrationName
required
string

The integrationName of the application.

Request Body schema: application/json

The application content must be passed in the request body in XML format.

integrationName
string

The application integration name.

displayName
string

The application display name.

description
string

The application description.

object (ApplicationPropsModel)

The application properties. See the description forApplicationProps.

dependentDefs
string

A set of comma-separated objects, which must be installed prior to installing this application.

Array of objects (ObjectDefModel)

A set of object definitions. See the description for DataObjectDef.

id
integer <int64>

The application ID.

orderNo
integer <int32>

The order in which this application appears in the list of applications.

isSystem
boolean

Specifies whether this is a system application.

version
integer <int32>

The application version.

terminateOnError
boolean

Specifies whether to terminate the application when an error occurs.

originalId
string
createdBy
integer <int64>
createdAt
string
updatedBy
integer <int64>
updatedAt
string

Responses

Request samples

Content type
application/json
{
  • "integrationName": "string",
  • "displayName": "string",
  • "description": "string",
  • "props": {
    },
  • "dependentDefs": "string",
  • "dataObjectDefs": [
    ],
  • "id": 0,
  • "orderNo": 0,
  • "isSystem": true,
  • "version": 0,
  • "terminateOnError": true,
  • "originalId": "string",
  • "createdBy": 0,
  • "createdAt": "string",
  • "updatedBy": 0,
  • "updatedAt": "string"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Delete Application Definition

This request is used by a tenant admin to delete an existing application, by specifying the appIntegrationName (as a path parameter).

Authorizations:
Api-KeyJWT
path Parameters
appIntegrationName
required
string

The integrationName of the application.

Responses

Response samples

Content type
application/json

On successfully deleting CRM application definition, the consequent response confirms the same by returning a statement, 'CRM' application has been deleted, including 7 objects, 8 tabs, and 1 portals.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve Application Permissions

This request is used by a tenant admin to retrieve application view permission assigned to a particular user/role. The appIntegrationName (as a path parameter) and roleIntegrationName/userId (as a request body parameter) are specified.

The retrieved view permission of an application indicates the following:

  • If retrieved as True, then application view permission is set.
  • If retrieved as False, then application view permission is removed.

Authorizations:
Api-KeyJWT
path Parameters
appIntegrationName
required
string

The integration name of the application.

query Parameters
roleIntegrationName
string

The integration name of the role.

userId
string

The id of the user.

Responses

Response samples

Content type
application/json

In this example, a tenant admin has retrieved the CRM application view permission for a user with userId -441586302. The consequent response returns details such as type, name, id of the application, and permissions. In this case, view is retrieved as True, indicating that application viewing is permitted for the specified user.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update Application Permission

This request is used by a tenant admin to set/remove the application view permission assigned to a particular user/role, by specifying the view parameter as True/False. The appIntegrationName (as a path parameter) and roleIntegrationName/userId (as a request body parameter) are specified.

Authorizations:
Api-KeyJWT
path Parameters
appIntegrationName
required
string

The integration name of the application.

query Parameters
roleIntegrationName
string

The integration name of the role.

userId
string

The id of the user.

Request Body schema: application/json

The view permission of an application.

  • If set to True, then application view permission is set.
  • If set to False, then application view permission is removed.

view
string
  • if `true`, then the view permission is enabled.
  • if `false` then the view permission is disabled.
create
string
  • if `true`, then the create permission is enabled.
  • if `false` then the create permission is disabled.
edit
string
  • if `true`, then the edit permission is enabled.
  • if `false` then the edit permission is disabled.
delete
string
  • if `true`, then the delete permission is enabled.
  • if `false` then the delete permission is disabled.
viewConditionScript
string

Only applicable for Field Level permissions. Formula should be mentioned in base64 encoded format.

Note works only when view permission is set to conditional

editConditionScript
string

Only applicable for Field Level permissions. Formula should be mentioned in base64 encoded format.

Note works only when edit permission is set to conditional

login
string

Applicable only when the object is CUSTOMER

  • if true, then the view permission is enabled.
  • if false then the view permission is disabled.

Responses

Request samples

Content type
application/json

In this example request, a tenant admin is setting CRM application view permission for all users with a non-admin role by specifying view as True.

{
  • "view": "true"
}

Response samples

Content type
application/json

In this example, a tenant admin has set CRM application view permission for all users with a non-admin role. The consequent response confirms the same by returning a statement, 'Permissions set successfully'

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

List Object Definitions

This request retrieves the information of all objects under a specified application providing appIntegrationName

Authorizations:
Api-KeyJWT
query Parameters
appIntegrationName
string

The integration name of the app.

onlyDefNames
boolean

Specify only if names to be returned instead of full description

permission
string

Applicable when onlyDefNames is true. It takes Any of view, create, edit or delete as value.

Responses

Response samples

Content type
application/json
Example

The consequent response to the GET request returns name,integrationName,isDeployed,dataSourcevalues for the objects present in that application.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Create Object Definition

This request is used to create a new object definition. A new object definition can be created based on the context of an application, or from the list of available objects from the setup.

Authorizations:
Api-KeyJWT
Request Body schema: application/json

Provide object definition.

singularName
string

Defines a singular name for the object definition. This name will be used throughout the account to refer similar records of this type.

pluralName
string

Defines a plural name for the object definition.This name will be used throughout the account to refer similar records of this type.

recordName
string

A Record Name field is used in pages, views, selectors, and search results which refer records of this type. Once created, the display format of the Record Name field can be customized using merge fields.

integrationName
string

The Integration Name of the object is used to refer this object via merge fields and the Web Services APIs. This name must be unique. Be careful when changing the Integration Name, as it may affect existing templates, formulas and integrations.

description
string

Description of the object

helpDescription
string

Help Description of the object

isDeployed
boolean
Default: true
object

The properties like auditTrail,flagging,viewedTracking and reportsEnabled are defined under this section

object

Enable unique features and provide a group of predefined fields for the newly created object definition. The following list of Object Attributes can be provided upon creation: CONTACT,LOCATION,EVENT,TASK,DOCUMENT,$LDF,TAG

object

The following list of Advanced Object Attributes such as WORKFLOW, APPROVAL can be set using this field.

object

Options like Create a new Tab for the object, Attach the object to the application are available

Responses

Request samples

Content type
application/json
Example

Creating an object under CRM application with all the attributes except Task as Event is enabled and both can’t co-exist at once.

{
  • "advancedAttributes": {
    },
  • "description": "The Object is created from Rest Meta API ",
  • "helpDescription": "Help Description is created from Rest Meta API ",
  • "integrationName": "rest_obj_all_attrib",
  • "isDeployed": true,
  • "objectAttributes": {
    },
  • "objectCreationOptions": {
    },
  • "optionalObjectProperties": {
    },
  • "pluralName": "rest_objs",
  • "recordName": "rest_obj",
  • "singularName": "rest_obj"
}

Response samples

Content type
application/json

response returns the Id of the object

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve Object Definition

This request is used to retrieve the complete definition of the object whose objIntegrationName is specified in the request. Details such as object parameters, field definitions, relationship definitions, and properties are retrieved. For more information, see Viewing and editing an Object Definition

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

Responses

Response samples

Content type
application/json

The consequent response to the GET request returns the complete object definition. Details such as object parameters, field definitions, relationship definitions, and properties are retrieved.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update Object Definition

This request is used to update an existing object definition where the user can update the object’s deployment status, properties, and attributes.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

Request Body schema: application/json

Provide object definition.

singularName
string

Defines a singular name for the object definition. This name will be used throughout the account to refer similar records of this type.

pluralName
string

Defines a plural name for the object definition.This name will be used throughout the account to refer similar records of this type.

recordName
string

A Record Name field is used in pages, views, selectors, and search results which refer records of this type. Once created, the display format of the Record Name field can be customized using merge fields.

integrationName
string

The Integration Name of the object is used to refer this object via merge fields and the Web Services APIs. This name must be unique. Be careful when changing the Integration Name, as it may affect existing templates, formulas and integrations.

description
string

Description of the object

helpDescription
string

Help Description of the object

isDeployed
boolean
Default: true
object

The properties like auditTrail,flagging,viewedTracking and reportsEnabled are defined under this section

object

Enable unique features and provide a group of predefined fields for the newly created object definition. The following list of Object Attributes can be provided upon creation: CONTACT,LOCATION,EVENT,TASK,DOCUMENT,$LDF,TAG

object

The following list of Advanced Object Attributes such as WORKFLOW, APPROVAL can be set using this field.

object

Options like Create a new Tab for the object, Attach the object to the application are available

Responses

Request samples

Content type
application/json

Disabling the following attributes for the object. optionalObjectProperties-> auditTrail,flagging,viewedTracking,reportsEnabled. objectAttributes ->contact,location,document.advancedAttributes->workflow,portalUser,multiCurrency

{
  • "advancedAttributes": {
    },
  • "description": "The Object is created from Rest Meta API ",
  • "helpDescription": "Help Description is created from Rest Meta API ",
  • "integrationName": "rest_obj_all1",
  • "isDeployed": true,
  • "objectAttributes": {
    },
  • "objectCreationOptions": {
    },
  • "optionalObjectProperties": {
    },
  • "pluralName": "rest_objs",
  • "recordName": "rest_obj",
  • "singularName": "rest_obj"
}

Response samples

Content type
application/json
{
  • "On updating the Object definition": {
    }
}

Delete Object Definition

This request is used to delete an object definition from the tenant. On request, this also removes triggers, templates, relationships, charts gauges, etc associated with the object definition. For more information, see Deleting an object definition.

Note Once deleted, the user cannot undo the deletion of the object definition.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

Responses

Response samples

Content type
application/json

The consequent response confirms the deletion of the object definition lead from the CRM application , by returning a statement, Lead object definition has been permanently deleted.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieves Object's Permissions

This request retrieves the information pertaining to the permissions (View, Edit, Create or Delete) of a specified object associated with a user or role. Either of roleIntegrationName or userId should be provided to update the object definition's permission(s). For more information, see Viewing and editing an Object Definition

Note Login Permission is retrieved only for CUSTOMER Objects.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

query Parameters
roleIntegrationName
string

The integrationName of the role.

userId
string

The id of the user.

Responses

Response samples

Content type
application/json

In this example, the Tenant admin is retrieving the permissions for the object lead associated by the user id 112015.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update Object's Permissions

This request updates permissions for a specified object definition for the given role/user. Either roleIntegrationName or userId must be specified to update the object definition's permission(s). For more information, see Roles and permissions

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

query Parameters
roleIntegrationName
string

The integrationName of the role.

userId
string

The id of the user.

Request Body schema: application/json

Any of the following parameter(s) can be passed to update the permissions of an object definition.

view
string
  • if `true`, then the view permission is enabled.
  • if `false` then the view permission is disabled.
create
string
  • if `true`, then the create permission is enabled.
  • if `false` then the create permission is disabled.
edit
string
  • if `true`, then the edit permission is enabled.
  • if `false` then the edit permission is disabled.
delete
string
  • if `true`, then the delete permission is enabled.
  • if `false` then the delete permission is disabled.
viewConditionScript
string

Only applicable for Field Level permissions. Formula should be mentioned in base64 encoded format.

Note works only when view permission is set to conditional

editConditionScript
string

Only applicable for Field Level permissions. Formula should be mentioned in base64 encoded format.

Note works only when edit permission is set to conditional

login
string

Applicable only when the object is CUSTOMER

  • if true, then the view permission is enabled.
  • if false then the view permission is disabled.

Responses

Request samples

Content type
application/json

In this request, the Tenant admin is updating the permissions (view= true,create = false,edit= true,delete= false) for the object lead of the CRM application associated with the role NONADMIN.

{
  • "create": false,
  • "delete": false,
  • "edit": true,
  • "view": true
}

Response samples

Content type
application/json

The consequent response to the PUT request of updating permission of an object associated with the userId returns the successful update of object's permissions with a message as Permissions set successfully.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

List Field Definitions

This request is used to retrieves the entire description of all the fields for a given object definition. For more information, see Viewing and editing an Object Definition

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

Responses

Response samples

Content type
application/json

On retrieving all fields

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Create Field

This request is used to create one a field definition by specifying the field type such as Text, Checkbox, etc. depending upon the type of information that this field should contain.

Below is the list of supported fields ( also, values for the key fieldType)

  1. Text
  2. TextArea
  3. Checkbox
  4. Currency
  5. Decimal
  6. Integer
  7. Percent
  8. Date
  9. DateTime
  10. Time
  11. Email
  12. PhoneNumber
  13. URL
  14. Password
  15. Picklist
  16. PicklistMulti
  17. RadioButton
  18. CheckboxGroup
  19. AutoNumber
  20. FileUpload
  21. ImageUpload
  22. SharedImage
  23. Formula
  24. Expression
  25. RollUpSummary
  26. ReferenceRecord
  27. Template
  28. DocumentTemplate
  29. EmailTemplate
  30. RelatedField
  31. IntegrationLink
  32. DependentPicklist
  33. VersionNumber
  34. CaptchaImage
  35. HiddenInput
  36. IPAddress

The value for the key fieldType is used to specify the type of field to be created. Only relevant key-value pairs mentioned for selected fieldType need to be passed in the request body.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

Request Body schema: application/json

Provide field definition.

integrationName
string

The Integration Name is used to reference this field via merge fields and the Web Services APIs. This name must be unique.

Note- Be careful when changing the Integration Name as it may affect existing templates, formulas and integrations.

fieldType
string

Type of the field determines what parameters are required to create it.

fieldLabel
string

Label of the field displayed on the left from the field on view, edit, and new record pages

fieldLevelHelp
string

If an application has Field-Level Help enabled, this text is displayed upon clicking the '?' icon next to this field's label

viewHeader
string

You can specify text label to be used in the headers in Views and Reports. This label is optional. If not specified, Display Label will be used.

viewWidth
string

It is used to set width (in pixels or %) of columns in views and reports. If not specified, the browser calculates the width of columns automatically

defaultSize
integer <int32>

The default size of the input field shown in forms.

length
integer <int32>

The maximum allowed length (number of characters).

object
object
isIndexed
boolean
Default: false

If set to true, the field is indexed and added to the global search engine whenever a record is created and updated.

Note: This may increase your database space usage if the field value changes often

isAuditable
boolean
Default: false

If set to true, adds a record-level audit trail entry whenever the field is updated, showing the value of the field before and after the update, as well as the user that performed the update and the date and time the update occurred.

Note: This may increase your database space usage if the field value changes often

isEncrypted
boolean
Default: false

If set to true, store values in an encrypted format.

Note: Encrypted fields cannot be audited, marked unique or indexed as part of the search engine. Once set, this option cannot be removed.

isRequired
boolean
Default: false

Specifies if a field value is always required in form pages (such as New and Edit).

allowDuplicateValues
boolean
Default: false

If set to false, it enforces uniqueness of this field's value across all records of that object type.

allowInlineEditing
boolean
Default: false

This field allows inline editing from view pages by clicking on icon

allowFiltering
boolean
Default: true

If enabled, users can edit this field on record view pages by clicking the pencil icon.

Responses

Request samples

Content type
application/json
Example

In this example, a Tenant Admin is creating a Text Field.

{
  • "allowDuplicateValues": false,
  • "allowFiltering": true,
  • "allowInlineEditing": false,
  • "defaultSize": 20,
  • "defaultValue": {
    },
  • "fieldLabel": "name",
  • "fieldLevelHelp": "name of the field",
  • "fieldType": "Text",
  • "inputMask": {
    },
  • "integrationName": "salutation",
  • "isAuditable": false,
  • "isEncrypted": false,
  • "isIndexed": false,
  • "isRequired": false,
  • "length": 20,
  • "viewHeader": "name header",
  • "viewWidth": "30"
}

Response samples

Content type
application/json

Upon successful creation of a field definition, a response similar to below is returned

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve Field Definition

Get field definition

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

fieldIntegrationName
required
string

The integrationName of the field.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Update Field Definition

This request updates a specified field definition.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

fieldIntegrationName
required
string

The integrationName of the field.

Request Body schema: application/json

Provide field definition.

integrationName
string

The Integration Name is used to reference this field via merge fields and the Web Services APIs. This name must be unique.

Note- Be careful when changing the Integration Name as it may affect existing templates, formulas and integrations.

fieldType
string

Type of the field determines what parameters are required to create it.

fieldLabel
string

Label of the field displayed on the left from the field on view, edit, and new record pages

fieldLevelHelp
string

If an application has Field-Level Help enabled, this text is displayed upon clicking the '?' icon next to this field's label

viewHeader
string

You can specify text label to be used in the headers in Views and Reports. This label is optional. If not specified, Display Label will be used.

viewWidth
string

It is used to set width (in pixels or %) of columns in views and reports. If not specified, the browser calculates the width of columns automatically

defaultSize
integer <int32>

The default size of the input field shown in forms.

length
integer <int32>

The maximum allowed length (number of characters).

object
object
isIndexed
boolean
Default: false

If set to true, the field is indexed and added to the global search engine whenever a record is created and updated.

Note: This may increase your database space usage if the field value changes often

isAuditable
boolean
Default: false

If set to true, adds a record-level audit trail entry whenever the field is updated, showing the value of the field before and after the update, as well as the user that performed the update and the date and time the update occurred.

Note: This may increase your database space usage if the field value changes often

isEncrypted
boolean
Default: false

If set to true, store values in an encrypted format.

Note: Encrypted fields cannot be audited, marked unique or indexed as part of the search engine. Once set, this option cannot be removed.

isRequired
boolean
Default: false

Specifies if a field value is always required in form pages (such as New and Edit).

allowDuplicateValues
boolean
Default: false

If set to false, it enforces uniqueness of this field's value across all records of that object type.

allowInlineEditing
boolean
Default: false

This field allows inline editing from view pages by clicking on icon

allowFiltering
boolean
Default: true

If enabled, users can edit this field on record view pages by clicking the pencil icon.

Responses

Request samples

Content type
application/json
Example
{
  • "integrationName": "string",
  • "fieldType": "Text",
  • "fieldLabel": "string",
  • "fieldLevelHelp": "string",
  • "viewHeader": "string",
  • "viewWidth": "string",
  • "defaultSize": 0,
  • "length": 0,
  • "inputMask": {
    },
  • "defaultValue": {
    },
  • "isIndexed": false,
  • "isAuditable": false,
  • "isEncrypted": false,
  • "isRequired": false,
  • "allowDuplicateValues": false,
  • "allowInlineEditing": false,
  • "allowFiltering": true
}

Response samples

Content type
application/json

Below response indicates successful updation of given field definition (of type Picklist, in this example).

{
  • "code": 200,
  • "message": "\"countryPickList\" field has been updated.",
  • "results": [
    ]
}

Delete Field Definition

This request is used to delete a field definition from an object. On deletion, all the specified field data for all existing records, pages, views, and reports are also removed.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

fieldIntegrationName
required
string

The integrationName of the field.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Retrieve Field's Permissions

This request is used to fetch details of the permissions granted to the specific role of a particular field. If a fieldIntegrationName is specified, then only the particular field’s permission details are fetched.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

fieldIntegrationName
required
string

The integrationName of the field.

query Parameters
roleIntegrationName
required
string

The integrationName of the role.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Updates Field's Permissions

This request can be used to update the permissions granted to the specific role of a particular field. If a fieldIntegrationName is specified, then only the particular field’s permission details are updated. Ensure either of roleIntegrationName or userId is provided.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

fieldIntegrationName
required
string

The integrationName of the field.

query Parameters
roleIntegrationName
required
string

The integrationName of the role.

Request Body schema: application/json

To set 'view/edit' permission, pass the value 'true' against respective key. Passing any other value for 'view/edit' or if a permission is omitted in request body, respective permission is treated as 'false'. To grant conditional view/edit permission, the permissions must include 'view'/'edit' with value 'conditional'. To grant conditional edit permission, the permissions parameter must include both 'view' and 'edit'. Both of these parameters are exclusive to field level permissions. While granting conditional permission for view or edit access, pass the condition formula as a base64-encoded string against 'viewConditionScript' or 'editConditionScript' respectively.

view
string
  • if `true`, then the view permission is enabled.
  • if `false` then the view permission is disabled.
create
string
  • if `true`, then the create permission is enabled.
  • if `false` then the create permission is disabled.
edit
string
  • if `true`, then the edit permission is enabled.
  • if `false` then the edit permission is disabled.
delete
string
  • if `true`, then the delete permission is enabled.
  • if `false` then the delete permission is disabled.
viewConditionScript
string

Only applicable for Field Level permissions. Formula should be mentioned in base64 encoded format.

Note works only when view permission is set to conditional

editConditionScript
string

Only applicable for Field Level permissions. Formula should be mentioned in base64 encoded format.

Note works only when edit permission is set to conditional

login
string

Applicable only when the object is CUSTOMER

  • if true, then the view permission is enabled.
  • if false then the view permission is disabled.

Responses

Request samples

Content type
application/json
Example

In this request, an admin is enabling the view and edit permission of a field country in an object leads in the CRM application for a role with integration name nonadmin

{
  • "edit": true,
  • "view": true
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

List Relationship Definitions

This request is used to retrieve the complete definitions of all relationships of the specified objectIntegrationName. For instance, if a given object(Case) has relationship1 with Lead, and relationship2 with Account, then the complete descriptions of these relationships can be retrieved by specifying the objIntegrationName of the object(Case).

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integration name of the source object.

Responses

Response samples

Content type
application/json

In this example, a tenant admin is retrieving all relationships between the source object (Account) and other objects in CRM application. Different relationships have different cardinalities and some can be hierarchical as well.

The consequent response to the GET request retrieves all the relationships of the Account object in a list format. Attributes such as the id, originalId, createdBy, createdAt, sourceObject(Account), destinationObject(other objects), integrationName,etc. of each relationship are returned for each relationship of the object.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Create Relationship Definition

This request is used to create a new relationship definition between two objects. The source of the relationship is identified by objIntegrationName from the request path (usually, the integration name of the source object). sourceObject and destinationObject in the request body denote the 2 objects that the relationship is created between.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integration name of the source object.

Request Body schema: application/json

The body parameters include the respective attributes of the sourceObject and destinationObject such as their singularName, pluralName, cardinality, foreignKey, relatedRecordOrphanControl, relatedRecordCloneControl, etc.

object
object

Responses

Request samples

Content type
application/json
Example

In this example, a Tenant Admin is creating a Many("cardinality":"MANY") to One("cardinality":"ONE")relationship between Case(sourceObject) and Account(destinationObject) objects in CRM application. Here, the integration of the source object(case) is specified as a path parameter.

{
  • "destinationObject": {
    },
  • "sourceObject": {
    }
}

Response samples

Content type
application/json

In this example, a tenant admin has created a One (cardinality":"ONE") to One ("cardinality":"ONE") relationship between Case(sourceObject) and Account(destinationObject) objects in CRM Application.

On successful creation of a new relationship definition, the consequent response returns the id and integrationName of the relationship, along with the names of the object definitions.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve Object's Relationship

This request is used to retrieve the complete definition of a relationship of the specified object. For instance, if a given object(Case) has relationship1 with Lead, then the complete definition of this relationship can be retrieved by specifying the objIntegrationName of the object(Case) along with the relIntegrationName of the relationship between the object(Case) and Lead.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

relIntegrationName
required
string

The integrationName of the relationship.

Responses

Response samples

Content type
application/json
Example

In this example, we have retrieved the complete definition of a relationship (relIntegrationName:R1850980)for an object(Lead). This relationship happens to be between the Lead object and the Account object in CRM application, and its cardinality is “Many Leads to Many Accounts”.

The consequent response to the GET request retrieves the complete relationship definition for the specified relIntegrationName(R1850980 here) and objIntegrationName(lead here). Attributes such as the id, originalId, createdBy, createdAt, sourceObject(Lead), destinationObject(Account), integrationName of the relationship, etc. are returned.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update Object's Relationship

This request is used to update a relationship definition. The cardinality of the relationship, clone parameters, and orphan options can be modified.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the source object.

relIntegrationName
required
string

The integrationName of the relationship.

Request Body schema: application/json

Update relationship definition

object
object

Responses

Request samples

Content type
application/json
Example

In this example a Tenant Admin is updating an existing One to One relationship between objects Case and account, to a Many to Many relationship by setting "cardinality":"MANY" for both the objects.

{
  • "destinationObject": {
    },
  • "sourceObject": {
    }
}

Response samples

Content type
application/json

On successfully fixing the records cardinality issue and then updating a relationship definition, the consequent request confirms the same by returning, "Relationship has been updated.".

{
  • "code": 200,
  • "message": "Relationship has been updated.",
  • "results": [
    ]
}

Delete Object's Relationship

This request is used to delete an entire relationship definition between 2 objects by specifying one of their objIntegrationNames, along with the relIntegrationName.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

relIntegrationName
required
string

The integrationName of the relationship.

Responses

Response samples

Content type
application/json

In this example, we are deleting the complete relationship definition (relIntegrationName:R1850980)for an object(lead). This relationship is between the Lead object and the Account object in CRM application, and its cardinality is “Many Leads to Many Accounts”.

The consequent response to the DELETE request returns a message, "Relationship deleted successfully" to confirm the same.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

List View Definitions

This request is used to retrieve details of all views that belong to a particular object, in a list format. For each view that belongs to the specified object, the id, originalId, createdBy, createdAt, updatedBy, updatedAt, orderNo, name, and integrationName of the view are retrieved.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

Responses

Response samples

Content type
application/json

In this example, we are retrieving all the views that belong to the lead object in CRM application.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Create View Definition

This request is used to create and configure views, and to define grouping, sorting, totaling, and filtering behaviors (including formulae and expressions).

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

Request Body schema: application/json

Description

orderNo
integer <int32>
name
string
integrationName
string
id
integer <int64>
objDefName
string

The integration name of the Object.

hideFromViewSelector
boolean
hideCounter
boolean
isPrivate
boolean
usedInSearch
boolean
showInDesktop
boolean
showInTablet
boolean
showInSmartPhone
boolean
columns
Array of strings
showActions
boolean
object
object
object

Responses

Request samples

Content type
application/json
Example

In this example, we are requesting the creation of a view with certain columns ("salutation", "firstName", lastName", ”email, "city", ”company", "mobilePhone") in lead object of CRM application.

{
  • "columns": [
    ],
  • "integrationName": "leadBasicView",
  • "name": "leadBasicView"
}

Response samples

Content type
application/json
Example

Upon successfully creating a view, the consequent response to POST returns the orderNo, name, integrationName, and id of the created view.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve View Definition

This request is used to retrieve complete information about a view whose viewIntegrationName and objIntegrationName (integration name of the object that the view is a part of) are specified in the request.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

viewIntegrationName
required
string

The integrationName of the view.

Responses

Response samples

Content type
application/json

In this example, we are retrieving a view with integrationName=All_Leads in the lead object in CRM application.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update View Definition

This request is used to update views, and to alter grouping, sorting, totaling, and filtering behaviors (including dynamic filtering, expressions, and exporting).

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

viewIntegrationName
required
string

The integrationName of the view.

Request Body schema: application/json

Any node can be passed and the resultant will be the update of the view with the current node.

id
integer <int64>
originalId
string
createdBy
integer <int64>
createdAt
string
updatedBy
integer <int64>
updatedAt
string
orderNo
integer <int32>
name
string
integrationName
string
objDefName
string

The integration name of the Object.

hideFromViewSelector
boolean
hideCounter
boolean
isPrivate
boolean
usedInSearch
boolean
showInDesktop
boolean
showInTablet
boolean
showInSmartPhone
boolean
columns
Array of strings
showActions
boolean
object
object
object

Responses

Request samples

Content type
application/json

In CRM application, updating the filter for the view “Recent Leads (Last 7 Days)” to show the results for last 14 days.

{
  • "viewFilters": null,
  • "filters": [
    ],
  • "joinType": "AND"
}

Response samples

Content type
application/json

Upon successfully updating the view, the consequent response returns the entire view definition, that is the modified and unmodified values together.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Delete View Definition

This request is used to delete a specific view that belongs to an object.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

viewIntegrationName
required
string

The integrationName of the view.

Responses

Response samples

Content type
application/json

In this example, we are deleting a view with viewIntegrationName = Today's_Leads, in the lead object in CRM application.

In CRM application , for the lead object deleting a view “Today's Leads”(added integration name as Today's_Leads)

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve View's Permission(s)

This request is used to retrieve a view’s access permissions by specifying either the roleIntegrationName or the userId (not both). If view permissions are enabled for the specified role/user ID, then the response returns view:true. If they are disabled, then the response returns view:false

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

viewIntegrationName
required
string

The integrationName of the view.

query Parameters
roleIntegrationName
string

The integrationName of the role.

userId
string

The id of the user.

Responses

Response samples

Content type
application/json
Example

In this example, we are retrieving view permissions (where viewIntegrationName = All_Leads) for a role whose roleIntegrationName is NONADMIN in lead object in CRM application.

In CRM application, lead object,… fetching the view permissions for the all Leads view for the role whose integrationName is NONADMIN

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update View's Permission(s)

This request is used to update View permissions for a specific view for a given role/user ID. Either the roleIntegrationName or the userId must be specified(not both). View permissions can be enabled/disabled for a specific user or for all users with the specified role.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

viewIntegrationName
required
string

The integrationName of the view.

query Parameters
roleIntegrationName
string

The integrationName of the role.

userId
string

The id of the user.

Request Body schema: application/json

The request body must contain information about enabling/disabling view permissions. If “view” is set to True, then view permissions are assigned to the view definition.

view
string
  • if `true`, then the view permission is enabled.
  • if `false` then the view permission is disabled.
create
string
  • if `true`, then the create permission is enabled.
  • if `false` then the create permission is disabled.
edit
string
  • if `true`, then the edit permission is enabled.
  • if `false` then the edit permission is disabled.
delete
string
  • if `true`, then the delete permission is enabled.
  • if `false` then the delete permission is disabled.
viewConditionScript
string

Only applicable for Field Level permissions. Formula should be mentioned in base64 encoded format.

Note works only when view permission is set to conditional

editConditionScript
string

Only applicable for Field Level permissions. Formula should be mentioned in base64 encoded format.

Note works only when edit permission is set to conditional

login
string

Applicable only when the object is CUSTOMER

  • if true, then the view permission is enabled.
  • if false then the view permission is disabled.

Responses

Request samples

Content type
application/json
Example

In this example, we are disabling view permissions for the “nonadmin” role for the view definition recentLeads (Last 7 Days) in the lead object of CRM application. In CRM applicaiton, for the view definition Recent Leads (Last 7 Days) (integration name set to recentLeads) in the object leads we are trying to disable the view permissions for the role “nonadmin“

{
  • "view": false
}

Response samples

Content type
application/json
Example

Upon successfully updating a view definition/view's access permissions, the consequent response confirms the same by returning "Permissions set successfully".

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

List Triggers

This request is used by a tenant admin to retrieve information of all triggers for the object whose objIntegrationName is specified in the request.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

Responses

Response samples

Content type
application/json

The request is to fetch all the triggers under the Meeting object in Infinite Blue application.The consequent response retrieves information of all triggers for the object. Details of each of the triggers, such as the Id, triggerName,integrationName,triggerType,isDeployed,isDelayed are retrieved.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Create Trigger Definition

A trigger is a stored procedure that is automatically executed when certain events occur. Triggers can perform automated validation, notification, and data manipulation. A tenant admin can configure triggers to send emails, create audit trail records, validate record data, update field values, change workflow status, create new records, etc.

Request description : Requests must be formulated based on the type of trigger being fired, and can include parameters such as the triggerType, triggerName, integrationName, isDeployed, onFieldChange, triggerTiming, etc. Essentially, there are 14 types of trigger

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

Request Body schema: application/json
triggerName
required
string

The display name of the trigger that appears everywhere in the UI.

integrationName
required
string

The unique code name of the trigger across the tenant, used in scripts to uniquely identify a trigger.

isDeployed
boolean
Default: true

Enables/disables the trigger for execution. If set to false, the trigger is not executed. The default value is true.

onFieldChange
Array of strings

If you want this trigger to run only when certain field values change, select the fields that should fire this trigger here. This option will only affect "Before Update" and "After Update" triggers. If no fields are specified, then the default is "Any Update".

triggerType
required
string

The type of the trigger.

triggerTiming
Array of strings
Items Enum: "BEFORE_CREATE" "BEFORE_UPDATE" "BEFORE_DELETE" "BEFORE_RESTORE" "ON_FINALIZE" "AFTER_CREATE" "AFTER_UPDATE" "AFTER_DELETE" "AFTER_RESTORE"

Specifies when this trigger must run. In addition to this timing criterion, triggers can also be invoked from workflow actions of the type 'Run Triggers'.

object

Information about email.

triggerConditionFormula
string

The script for defining condition, based on the evaluation of which, the trigger is executed/is not executed. The trigger runs if the evaluation result is true. If the evaluation result is false, then the trigger is not executed. Note: The Value should be provided in BASE64 encoded format.

object

The delay criteria for the trigger, to be specified if you do not want the trigger to run immediately.

Note: For delayed triggers, the options Before and After do not make a difference.

object

The recurrence settings for the trigger, to be specified if you want the trigger to run multiple times after being fired for the first time.

runAsJob
boolean
Default: false

Schedule trigger to run as large job with enhanced monitoring and cancellation capabilities

Responses

Request samples

Content type
application/json
Example

In this example, a Tenant Admin is creating a Send Email trigger, by specifying details such as the triggerType, triggerName, integrationName, isDeployed, onFieldChange, triggerTiming, etc.

{
  • "emailInfo": {
    },
  • "integrationName": "rest_sendEmail",
  • "isDeployed": true,
  • "onFieldChange": "email",
  • "recursion": {
    },
  • "triggerConditionFormula": "cmV0dXJuIHRydWU7",
  • "triggerDelayTime": {
    },
  • "triggerName": "rest_sendEmail",
  • "triggerTiming": [
    ],
  • "triggerType": "SendEmail"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Retrieve Trigger Definition

This request is used by a tenant admin to retrieve the complete definition of a specific trigger, by specifying its objIntegrationName and triggerIntegrationName. Details of the trigger such as the triggerType, triggerName, integrationName, isDeployed, onFieldChange, httpRequestBody, triggerTiming, etc. are retrieved.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

triggerIntegrationName
required
string

The integrationName of the trigger.

Responses

Response samples

Content type
application/json
Example

The consequent response to this GET request retrieves details of the trigger such as the triggerType, triggerName, integrationName, isDeployed, onFieldChange, httpRequestBody, triggerTiming, etc.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update Trigger Definition

Requests to update triggers must be formulated based on the type of trigger being updated, and can be used to update values such as the triggerType, triggerName, integrationName, isDeployed, onFieldChange, triggerTiming, etc. Essentially, there are 14 types of triggers. One or more attributes can be updated at a time. The request must contain both, the values to be updated, as well as the values that do not need to be updated.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

triggerIntegrationName
required
string

The integrationName of the trigger.

Request Body schema: application/json

Update trigger definition

triggerName
required
string

The display name of the trigger that appears everywhere in the UI.

integrationName
required
string

The unique code name of the trigger across the tenant, used in scripts to uniquely identify a trigger.

isDeployed
boolean
Default: true

Enables/disables the trigger for execution. If set to false, the trigger is not executed. The default value is true.

onFieldChange
Array of strings

If you want this trigger to run only when certain field values change, select the fields that should fire this trigger here. This option will only affect "Before Update" and "After Update" triggers. If no fields are specified, then the default is "Any Update".

triggerType
required
string

The type of the trigger.

triggerTiming
Array of strings
Items Enum: "BEFORE_CREATE" "BEFORE_UPDATE" "BEFORE_DELETE" "BEFORE_RESTORE" "ON_FINALIZE" "AFTER_CREATE" "AFTER_UPDATE" "AFTER_DELETE" "AFTER_RESTORE"

Specifies when this trigger must run. In addition to this timing criterion, triggers can also be invoked from workflow actions of the type 'Run Triggers'.

object

Information about email.

triggerConditionFormula
string

The script for defining condition, based on the evaluation of which, the trigger is executed/is not executed. The trigger runs if the evaluation result is true. If the evaluation result is false, then the trigger is not executed. Note: The Value should be provided in BASE64 encoded format.

object

The delay criteria for the trigger, to be specified if you do not want the trigger to run immediately.

Note: For delayed triggers, the options Before and After do not make a difference.

object

The recurrence settings for the trigger, to be specified if you want the trigger to run multiple times after being fired for the first time.

runAsJob
boolean
Default: false

Schedule trigger to run as large job with enhanced monitoring and cancellation capabilities

Responses

Request samples

Content type
application/json
Example

In this example, a Tenant Admin is updating a Create New Record trigger, by setting hours to 12,delayTiming to BEFORE and specifying all other details such as the triggerType, triggerName, integrationName, runDependentTrigger, isDeployed, onFieldChange, etc.

{
  • "accessControlPolicy": "THROW_ERROR",
  • "conversionMap": "api_map",
  • "integrationName": "REST_CreateNewRecord_INT",
  • "isDeployed": true,
  • "onFieldChange": "firstName",
  • "recursion": {
    },
  • "runDependentTrigger": true,
  • "triggerConditionFormula": "cmV0dXJuIHRydWU",
  • "triggerDelayTime": {
    },
  • "triggerName": "REST_CreateNewRecord_Name",
  • "triggerTiming": [
    ],
  • "triggerType": "CreateNewRecord"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Delete Trigger Definition

This request is used by a tenant admin to delete the complete definition of a specific trigger, by specifying its objIntegrationName and triggerIntegrationName.

Authorizations:
Api-KeyJWT
path Parameters
objIntegrationName
required
string

The integrationName of the object.

triggerIntegrationName
required
string

The integrationName of the trigger.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Retrieve Currency Formats

Retrieves pre-defined currency formats.

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List Batch-Jobs

This request is used by a tenant admin to retrieve the list of batch jobs.

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json

In this example, we are requesting to list all the batch-jobs present under current tenant admin.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Create Batch-Job Definition

Platform batch jobs can be used to schedule periodic system maintenance, notification, and integration tasks. Batch jobs use the permissions set on each object for the Query API.

Request Description This request is used by a tenant admin to create a batch job by specifying its name, integration name, recursive properties, type, etc. The parameters to be added while formulating the request depend on the type of batch job being created. Batch jobs supported by Platform are of the following types

  • System Backup This job generates a system backup file. Optionally, it can upload the backup file to a remote FTP server.
  • Data Maintenance This job runs the specified object script from the Platform client-side API on each record of the selected type
  • Generate Report This job runs the selected report and sends it as an email attachment to the specified recipient.
  • FTP Data Snapshot This job takes a snapshot of report data and uploads it via FTP/SFTP to a remote server in CSV, XLS, XLSX or XML format.
  • Re-index Search Data This job re-creates the index used for global text search.
  • Scheduled FTP Import This job downloads spreadsheet file from a remote FTP/SFTP server and starts the import process defined in the selected import map

Authorizations:
Api-KeyJWT
Request Body schema: application/json
batchJobType
string
jobName
string

The display name of the batch job across system.

integrationName
string

Code name of the batch job that is unique across system and can be used during scripting.

isDeployed
boolean

Determines if the batch job is active for execution. If set to false,then the batch job is disabled and can’t run. The default value is true.

object

A set of parameters to schedule the running of the batch job after a specific time interval. If no recursion parameters are specified, then by default the batch job executes once everyday.

notifyEmailAddress
string

Email address to which the result of the batch job is sent.

conditionalFormula
string <byte>

The script for defining condition, based on the evaluation of which, the batch job is executed/is not executed. The batch job runs if the evaluation result is true. If the evaluation result is false, then the batch job is not executed. Note: The Value should be provided in BASE64 encoded format.

object (BackupType)

Responses

Request samples

Content type
application/json
Example

In this example, a tenant admin is generating a system backup file. As backupType is not specified , the backup is created in the customer's storage folder.

{
  • "batchJobType": "SystemBackup",
  • "conditionalFormula": "cmV0dXJuIHRydWU7",
  • "integrationName": "test_backup_local",
  • "isDeployed": true,
  • "jobName": "test_backup_",
  • "notifyEmailAddress": "email@company.com",
  • "recursion": {
    }
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Retrieve Batch-Job

This request is used by a tenant admin to retrieve the complete definition of a batch job, by specifying its batchJobIntegrationName.

Authorizations:
Api-KeyJWT
path Parameters
batchJobIntegrationName
required
string

The integrationName of the batch job.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Update Batch-Job Definition

This request is used by a tenant admin to update a batch job. Requests to update batch jobs must be formulated based on the type of batch job being updated, and can be used to update values such as the batchJobType, conditionalFormula, emailSubject, isDeployed, etc. One or more attributes can be updated at a time. The request must contain both, the values to be updated, as well as the values that do not need to be updated. Batch jobs supported by Platform are of the following types

  • System Backup This job generates a system backup file. Optionally, it can upload the backup file to a remote FTP server.
  • Data Maintenance This job runs the specified object script from the Platform client-side API on each record of the selected type
  • Generate Report This job runs the selected report and sends it as an email attachment to the specified recipient.
  • FTP Data Snapshot This job takes a snapshot of report data and uploads it via FTP/SFTP to a remote server in CSV, XLS, XLSX or XML format.
  • Re-index Search Data This job re-creates the index used for global text search.
  • Scheduled FTP Import This job downloads spreadsheet file from a remote FTP/SFTP server and starts the import process defined in the selected import map

Authorizations:
Api-KeyJWT
path Parameters
batchJobIntegrationName
required
string

The integrationName of the batch job.

Request Body schema: application/json

Update batch job definition

batchJobType
string
jobName
string

The display name of the batch job across system.

integrationName
string

Code name of the batch job that is unique across system and can be used during scripting.

isDeployed
boolean

Determines if the batch job is active for execution. If set to false,then the batch job is disabled and can’t run. The default value is true.

object

A set of parameters to schedule the running of the batch job after a specific time interval. If no recursion parameters are specified, then by default the batch job executes once everyday.

notifyEmailAddress
string

Email address to which the result of the batch job is sent.

conditionalFormula
string <byte>

The script for defining condition, based on the evaluation of which, the batch job is executed/is not executed. The batch job runs if the evaluation result is true. If the evaluation result is false, then the batch job is not executed. Note: The Value should be provided in BASE64 encoded format.

object (BackupType)

Responses

Request samples

Content type
application/json
Example

In this example, a tenant admin is updating a System Backup batch job, by setting recursionType from DAYS to MONTHS, and also specifying all other values that do not need to be updated, such as the backupType, batchJobType, conditionalFormula, integrationName, etc.

{
  • "backupType": {
    },
  • "batchJobType": "SystemBackup",
  • "conditionalFormula": "cmV0dXJuIHRydWU7",
  • "integrationName": "test_backup",
  • "isDeployed": true,
  • "jobName": "test_backup_F3",
  • "notifyEmailAddress": "email@company.com",
  • "recursion": {
    }
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Delete Batch-Job Definition

This request is used by a tenant admin to delete the complete definition of a batch job by specifying its batchJobIntegrationName.

Authorizations:
Api-KeyJWT
path Parameters
batchJobIntegrationName
required
string

The integrationName of the batch job.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

List Authentication Profiles

This GET request retrieves major details of all authentication profiles of a tenant. Details such as the id, name, authenticationType, defaultUIAuth, and defaultAPIAuth are retrieved.

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json

The consequent response retrieves major details of all authentication profiles of a tenant. Details such as the id, name, authenticationType, defaultUIAuth, and defaultAPIAuth are retrieved.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Create Authentication Profile

This request creates a new authentication profile. Authentication is the process of verifying a user’s identity using credentials. Authentication profiles are created by specifying their authentication type and other parameters. The authentication types are as follows

  • PASSWORD
  • LDAP
  • LDAP_ADVANCED
  • HTTP_POST
  • HTTP_GET
  • CUSTOM
  • KERBEROS
  • SAML_ADFS
  • API_TOKEN

NOTE A tenant is limited to creating only one authentication profile if the authentication type is Password, Kerberos, and Custom

Authorizations:
Api-KeyJWT
Request Body schema: application/json

In the request body, attributes of the authentication profile to be created such as the authentication profile name, authentication type, security details, additional parameters, etc. can be specified.

id
string

This is a Auto-generated Parameter and is unique for each Authentication profile.

name
string

Name assigned to the authentication profile - for convenient remembrance.

authenticationType
string

The following mapping must be followed to give the correct authentication type.

defaultUIAuth
boolean

An optional parameter which when set to True sets the authentication profile being created as the customer's default UI authentication profile.

Note

  • This parameter cannot be set in case of API tokens.
  • If you wish to change the default UI profile then you can simply set this parameter as true for another profile; False is an invalid value.

defaultAPIAuth
boolean

An optional parameter which when set to True sets the authentication profile being created as the customer's default API authentication profile.

Note

  • This parameter cannot be set in case of KERBEROS.
  • If you wish to change the default API profile then you can simply set this parameter as true for another profile; False is an invalid value.

securityLevel
string

The security level as a number. The numbers for specific levels of security are as follows:low, medium, and high.

isMFAEnabled
boolean

Indicates whether Multi-Factor Authentication (MFA) is enabled. For GET, Returns true if MFA is currently enabled, false otherwise. For PUT, Accepts true to enable MFA, or false to disable it.

expirPolicy
integer <int32>

The number of days before a password expires. Set it to 0 for no password expiration (this is also the default value) and a value that is more than or equal to the value of the shared property MinExpirationPolicy ( which is 30 by default)

formula
string

The custom validation formula. Value should be provide in BASE64 format.

enablePasswordHistory
boolean
Default: false

This is a boolean value. If set to True, then the password history is recorded. If set to False, then no such record is kept.

passwordHistoryLimit
integer <int32>
useKnowledgeFactorToken
boolean

This must be set to true to use a knowledge factor token.

knowledgeFactorToken
string

This must be a mandatory field from the User object definition that can be configured as a token.

object
newUserPasswordActivationContextExpiry
integer <int32>

This is the activation link expiry time.

passwordActivationContextExpiry
integer <int32>

The password activation link expiry time.

Responses

Request samples

Content type
application/json
Example

In this example, we are requesting the creation of an authentication profile with the name LDAP-Profile-For-Ground-Staff

{
  • "additionalParamKeys": [
    ],
  • "additionalParamValues": [
    ],
  • "authenticationType": "LDAP",
  • "defaultAPIAuth": false,
  • "defaultUIAuth": false,
  • "name": "LDAP-Profile-For-Ground-Staff",
  • "securityAuthentication": "simple",
  • "securityCredential": "{!password}",
  • "securityPrincipal": "uid={!loginName},dc=example,dc=com",
  • "targetURL": "ldap://ldap.forumsys.com:389"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Retrieve Authentication profile

This GET request retrieves all the details of the authentication profile whose authenticationProfileId is specified in the request

Authorizations:
Api-KeyJWT
path Parameters
authenticationProfileId
required
string

The originalId of the authentication profile.

Responses

Response samples

Content type
application/json

In the consequent response, all the details of the authentication profile(password Authentication profile) whose authenticationProfileId is specified in the request are retrieved. Details of the authentication profile such as id, name, description, etc. are returned.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update Authentication profile

This request updates an already existing authentication profile, by using its unique (known) authentication profile ID. This request and its usage vary based on the authentication type used. 'Authentication Profile has been updated successfully' is returned as the response to confirm the update made to the authentication profile.

Authorizations:
Api-KeyJWT
path Parameters
authenticationProfileId
required
string

The originalId of the authentication profile.

Request Body schema: application/json

This request and its usage vary based on the authentication type used. Likewise, the parameters also vary. In the request body, attributes of the authentication profile to be updated can be specified, such as the authentication profile name, security details, additional parameters, etc. along with the parameters whose values need not be updated.

If the password of the authentication profile is to be updated, then security, history, and expiry parameters can be specified in the request body.

id
string

This is a Auto-generated Parameter and is unique for each Authentication profile.

name
string

Name assigned to the authentication profile - for convenient remembrance.

authenticationType
string

The following mapping must be followed to give the correct authentication type.

defaultUIAuth
boolean

An optional parameter which when set to True sets the authentication profile being created as the customer's default UI authentication profile.

Note

  • This parameter cannot be set in case of API tokens.
  • If you wish to change the default UI profile then you can simply set this parameter as true for another profile; False is an invalid value.

defaultAPIAuth
boolean

An optional parameter which when set to True sets the authentication profile being created as the customer's default API authentication profile.

Note

  • This parameter cannot be set in case of KERBEROS.
  • If you wish to change the default API profile then you can simply set this parameter as true for another profile; False is an invalid value.

securityLevel
string

The security level as a number. The numbers for specific levels of security are as follows:low, medium, and high.

isMFAEnabled
boolean

Indicates whether Multi-Factor Authentication (MFA) is enabled. For GET, Returns true if MFA is currently enabled, false otherwise. For PUT, Accepts true to enable MFA, or false to disable it.

expirPolicy
integer <int32>

The number of days before a password expires. Set it to 0 for no password expiration (this is also the default value) and a value that is more than or equal to the value of the shared property MinExpirationPolicy ( which is 30 by default)

formula
string

The custom validation formula. Value should be provide in BASE64 format.

enablePasswordHistory
boolean
Default: false

This is a boolean value. If set to True, then the password history is recorded. If set to False, then no such record is kept.

passwordHistoryLimit
integer <int32>
useKnowledgeFactorToken
boolean

This must be set to true to use a knowledge factor token.

knowledgeFactorToken
string

This must be a mandatory field from the User object definition that can be configured as a token.

object
newUserPasswordActivationContextExpiry
integer <int32>

This is the activation link expiry time.

passwordActivationContextExpiry
integer <int32>

The password activation link expiry time.

Responses

Request samples

Content type
application/json
Example

In this Example, we are updating the Password authentication profile by setting enablePasswordHistory to true,useKnowledgeFactorToken to true, knowledgeFactorToken to email, formula to aWYocGFzc3dvcmQubGVuZ3RoPjUpDQogcmV0dXJuICJwYXNzd29yZCBzaG91bGQgYmUgZ3JlYXRlciB0aGFuIDUgY2hhcmFjdGVycyI= etc.

{
  • "authenticationType": "PASSWORD",
  • "defaultAPIAuth": true,
  • "defaultUIAuth": true,
  • "enablePasswordHistory": true,
  • "expirPolicy": 1,
  • "formula": "aWYocGFzc3dvcmQubGVuZ3RoPjUpDQogcmV0dXJuICJwYXNzd29yZCBzaG91bGQgYmUgZ3JlYXRlciB0aGFuIDUgY2hhcmFjdGVycyI=",
  • "knowledgeFactorToken": "email",
  • "name": "Password",
  • "newUserPasswordActivationContextExpiry": 1,
  • "passwordActivationContextExpiry": 1,
  • "passwordHistoryLimit": 1,
  • "securityLevel": "LOW",
  • "securityQuestions": {
    },
  • "useKnowledgeFactorToken": true
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

Delete Authentication Profile

This request is used to delete an authentication profile, by specifying its authenticationProfileId

NOTE You cannot delete an authentication profile that is mapped to any role.

Authorizations:
Api-KeyJWT
path Parameters
authenticationProfileId
required
string

The originalId of the authentication profile.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "Operation was successful.",
  • "results": [
    ]
}

List Roles

This request is used by Tenant Admin to retrieve information about all the roles that are a part of the tenant

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json

In this example, we are retrieving details of all the roles that are a part of the tenant.

The consequent response to GET, retrieves details of all the roles that are a part of the tenant whose JWT token/API-key is specified in the request, in a list format. Different roles have different attributes such as id, originalId, integrationName, description, etc.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Create Role Definition

This request is used to create a new role for a user in a tenant, by providing necessary details of the role. A user has all permissions assigned to that user's role. For more information, see Setting permissions by role).

Authorizations:
Api-KeyJWT
Request Body schema: application/json

The request body must contain the role’s name and integrationName. The role description and the IDs/integrationNames of applications to which this role is required to be attached can also be specified, along with the authentication profile details.

id
integer <int64>
originalId
string
createdBy
integer <int64>
createdAt
string
updatedBy
integer <int64>
updatedAt
string
name
string
integrationName
string

The integrationName of the role.

description
string
Array of objects
uiAuthProfileId
string

A string containing the authentication profile ID to which UI authentication of above role is to be mapped.

apiAuthProfileId
string

A string containing the authentication profile ID to which API authentication of above role is to be mapped.

Responses

Request samples

Content type
application/json

In this example, we are requesting the creation of a “Test role”, and its attachment to the CRM application.

{
  • "applications": [
    ],
  • "description": "Test role",
  • "integrationName": "Guest",
  • "name": "Guest"
}

Response samples

Content type
application/json

In this example, we are creating a “Test role”, and attaching it to the CRM application.

The consequent response confirms the creation of the role by returning a message of the form “Role created with ID:4540202 and integrationName :Guest", along with the role ID, name, integrationName, and description. The application to which this role has been attached, that is “CRM” is also returned.

{
  • "code": 200,
  • "message": "Role created with ID: 4540202 and integrationName : Guest",
  • "results": [
    ]
}

Retrieve Role Definition

This request is used to retrieve all the details of a role by passing its roleIntegrationName as a path parameter.

Authorizations:
Api-KeyJWT
path Parameters
roleIntegrationName
required
string

The current integrationName of the role. This is used to identify the role that needs to be updated.

Note: In case the integrationName of the role also needs to be updated, the new integrationName can be passed in the request body.

Responses

Response samples

Content type
application/json

In this example, we are retrieving the details of a role with “nonadmin” as the roleIntegrationName.

we are retrieving the details of a role with “nonadmin” as the roleIntegrationName.

The consequent response to the GET call has retrieved all the details of the role specified in the request such as the ID, originalId, createdBy, createdAt, description, etc.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update Role Definition

This request is used to to update certain role details such as the role’s name, integrationName, and description.

Authorizations:
Api-KeyJWT
path Parameters
roleIntegrationName
required
string

The current integrationName of the role. This is used to identify the role that needs to be updated.

Note: In case the integrationName of the role also needs to be updated, the new integrationName can be passed in the request body.

Request Body schema: application/json

Only the parameters that need to be updated, such as the role’s name, integrationName, and description can be passed in the request body.

id
integer <int64>
originalId
string
createdBy
integer <int64>
createdAt
string
updatedBy
integer <int64>
updatedAt
string
name
string
integrationName
string

The integrationName of the role.

description
string
Array of objects
uiAuthProfileId
string

A string containing the authentication profile ID to which UI authentication of above role is to be mapped.

apiAuthProfileId
string

A string containing the authentication profile ID to which API authentication of above role is to be mapped.

Responses

Request samples

Content type
application/json

In this example we are updating the description of a role with roleIntegrationName “SalesAgent” to "A role for sales agents". Hence, only the description is passed as a parameter in the request body, since no other role details need to be updated.

{
  • "description": "A role for sales agents"
}

Response samples

Content type
application/json

In this example we are updating the description of a role with roleIntegrationName “SalesAgent” to "A role for sales agents".

The consequent response to confirms the update by returning a statement of the form "Updated Role with ID:<ID> and integrationName:<integrationName>". It also returns all the details of the now-updated roles, including modified and unmodified values, such as the id, name, integrationName, and description.

{
  • "code": 200,
  • "message": "Updated Role with ID: 4296110 and integrationName: SalesAgent",
  • "results": [
    ]
}

Delete Role Definition

This request is used to delete a particular role by specifying its integration name.

Note: At the time of deletion, no users must be attached to the role being deleted.

Authorizations:
Api-KeyJWT
path Parameters
roleIntegrationName
required
string

The current integrationName of the role. This is used to identify the role that needs to be updated.

Note: In case the integrationName of the role also needs to be updated, the new integrationName can be passed in the request body.

Responses

Response samples

Content type
application/json

In this example, we are deleting a role whose roleIntegrationName is SalesAgent.

The consequent response confirms the deletion of the role “SalesAgent” by returning the following statement :"Role deleted successfully".

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update Role Authentication Mapping

This request is used to update the UI authentication and API authentication profile IDs that a role is mapped to.

Authorizations:
Api-KeyJWT
path Parameters
roleIntegrationName
required
string

The integrationName of the role.

Request Body schema: application/json

Since this request updates UI authentication and API authentication profile IDs that a role is mapped to, only these must be passed as parameters.

uiAuthProfileId
string

A string containing the authentication profile ID to which UI authentication of above role is to be mapped.

apiAuthProfileId
string

A string containing the authentication profile ID to which API authentication of above role is to be mapped.

Responses

Request samples

Content type
application/json

In this example, we are mapping the role with SalesAgent as its roleIntegrationName to the following authentication profile IDs:

  • uiAuthProfileId:4b8c2c4f-be74-48ba-a4af-9482ad299dc4
  • apiAuthProfileId:4b8c2c4f-be74-48ba-a4af-9482ad299dc4

{
  • "apiAuthProfileId": "4b8c2c4f-be74-48ba-a4af-9482ad299dc4",
  • "uiAuthProfileId": "4b8c2c4f-be74-48ba-a4af-9482ad299dc4"
}

Response samples

Content type
application/json

In this example, we are mapping the role with SalesAgent as its roleIntegrationName to the following authentication profile IDs:

  • uiAuthProfileId:4b8c2c4f-be74-48ba-a4af-9482ad299dc4
  • apiAuthProfileId:4b8c2c4f-be74-48ba-a4af-9482ad299dc4

On successfully updating the mapped UI authentication and API authentication profile IDs of a role, the consequent response confirms the same by returning a statement of the form "Role <roleIntegrationName> is mapped to the Authentication profiles.".

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

List Portals

Portals are essentially external-facing web applications built using the same components as standard Platform applications. Portals typically run on a corporate website or intranet. You can create portal pages to display dynamic lists of records, to allow creation of records through custom forms, and to invoke triggers and custom business logic. For more information, see Platform Portals.

This request is used by a Tenant Admin to retrieve all portal definitions that are attached to an application by specifying the integration name of the application. If all portal definitions in a particular tenant are to be retrieved, then this can be achieved by specifying the Tenant Admin credentials; the appIntegrationName is not required.

Authorizations:
Api-KeyJWT
query Parameters
appIntegrationName
string

Responses

Response samples

Content type
application/json
Example

The consequent response to the GET request, retrieves the complete definitions of all portals attached to CRM application (appIntegrationName=CRM). Portal attributes such as id, originalId, name, integrationName, isDeployed, pageURL, etc. and page attributes such as id, origId,pageType, pageDefName, jspName, etc. are returned.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve Portal Definition

Portals are essentially external-facing web applications built using the same components as standard Platform applications. Portals typically run on a corporate website or intranet. You can create portal pages to display dynamic lists of records, to allow creation of records through custom forms, and to invoke triggers and custom business logic. For more information, see Platform Portals.

This request is used by a Tenant Admin to retrieve a portal definition by specifying its portalIntegrationName. Portal attributes such as id, originalId, name, integrationName, isDeployed, pageURL, etc. and page attributes such as id, origId,pageType, pageDefName, jspName, etc. are returned.

Authorizations:
Api-KeyJWT
path Parameters
portalIntegrationName
required
string

The integration name of the portal to be returned.

Responses

Response samples

Content type
application/json

The consequent response to the GET request retrieves the complete definition of the portal (portalIntegrationName = Leads_Portal as specified in the request). Portal attributes such as id, originalId, name, integrationName, isDeployed, pageURL, etc. and page attributes such as id, origId,pageType, pageDefName, jspName, etc. are returned.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

System

The System API section describes system-related operations that can be performed by master administrators. These may be used to alter/retrieve information, statistics, topology, etc. From this section, API developers can also create a published application, customer record, etc. Here are a few important descriptions :

Customer Record - A customer record defines the applications, security level, storage information and usage for an organization or group that will be using a customer tenant. For more information, see Creating a new customer record.

Reload global cache.

This request is used to reinitialize global cache.

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json

On successfully reinitializing global cache, the consequent response confirms the same by returning a statement, "Global Cache has been reloaded in memory".

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Revert the recent upgrade.

This request is used to revert the latest version changes.

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json

On successfully reverting the recent upgrade changes, the consequent response confirms the same by returning a statement, "Rollback Upgrade operation completed successfully".

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve Shared Properties Information

This request is used by a master admin to retrieve shared properties information.

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json

Retrieves Shared Properties status.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

update shared properties.

This request is used to update shared properties.

Authorizations:
Api-KeyJWT
Request Body schema: application/json

Since this request updates shared property only shared properties must be passed as parameter.

readOnlyInstance
boolean

Set to 'true' to make tenant read only instance.

Responses

Request samples

Content type
application/json
{
  • "readOnlyInstance": true
}

Response samples

Content type
application/json

On successfully updating shared property "ReadOnlyInstance", all write access will be revoked for that tenant.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve System Information

This request is used by a master admin to retrieve component-specific high level information such as the name, displayName, type, internalURL,externalURL, componentURL, power, active, activeLogger, etc. by specifying master admin credentials. Different components may have different attributes.

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json

In this example, a master admin has fetched component-specific high level information. The consequent response retrieves all the component-specific high level information such as the name, displayName, type, internalURL,externalURL, componentURL, power(for PROD),active(for SEARCH),activeLogger(for STORAGE), etc.

{}

Retrieve System Statistics

This request is used by a master admin to retrieve the following:

  1. Server related information such as serverUID and hostName.
  2. Components details for STORAGE, MASTER ,ROUTER ,PROD1 ,PROD2 ....., REST ,SEARCH , and WEBAPI.
  3. Other server details such as numThreads , numConnections , java(java version) , appServer(application server) , OS , OSVersion , rbVersion(platform version) , processor, processorCore (number of cores) , ram , totalMemory , freeMemory , usedMemory , maxMemory , freeMemoryLabel , maxMemoryLabel , state , cloudInstance , fontDir , storageDir , logDir , indexDir , and usageAnalyticsDir.

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json

In this example request, a master admin is specifying credentials in order to retrieve server statistics.

{}

Retrieve Node Level Statistics

This request is used by a master admin to retrieve the following by specifying the serverUID

  1. Server related information such as serverUID and hostName.
  2. Components details for STORAGE, MASTER ,ROUTER ,PROD1 ,PROD2 ....., REST ,SEARCH , and WEBAPI.
  3. Other server details such as numThreads , numConnections , java(java version) , appServer(application server) , OS , OSVersion , rbVersion(platform version) , processor, processorCore (number of cores) , ram , totalMemory , freeMemory , usedMemory , maxMemory , freeMemoryLabel , maxMemoryLabel , state , cloudInstance , fontDir , storageDir , logDir , indexDir , and usageAnalyticsDir.

Authorizations:
Api-KeyJWT
path Parameters
serverUID
required
string

A string UID of the server.

Responses

Response samples

Content type
application/json

In this example, a master admin has retrieved complete statistics of a server with serverUID = 359384b9-9c74-4a43-b064-9edbe9f5ac1a.The consequent response to this GET request retrieves the following

{}

Retrieve Component Statistics

This request is used by a master admin to retrieve complete information about a single component of a server, such as STORAGE, MASTER ,ROUTER,PROD1,PROD2....., REST,SEARCH, and WEBAPI, by specifying the name of the server component.

Authorizations:
Api-KeyJWT
path Parameters
serverUID
required
string

A string containing UID of the server.

componentName
required
string

A string componentName of the component.

Responses

Response samples

Content type
application/json
Example

In this example, a master admin has retrieved complete statistics of the MASTER component in the server with serverUID = 359384b9-9c74-4a43-b064-9edbe9f5ac1a. The consequent response has returned component details such as name, displayName, type, internalURL, externalURL, componentURL, numLoadedCustomers, startupTime, timeRunning, numJobs, emailQueueSize, customers(details of loaded customers), sessions(details of active sessions), and jobs(details of active jobs).

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve Build License Status

This request is used by a master admin to retrieve build license status details for an instance/set-up, such as the releaseNumber,releaseDate, edition, expiration, and host.

Authorizations:
Api-KeyJWT

Responses

Response samples

Content type
application/json

In this example request, a master admin has requested to retrieve build license status details for an instance/set-up. The consequent response retrieves build license status details for the instance/set-up, such as the releaseNumber,releaseDate, edition, expiration, and host.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

List Published Application Records

This request retrieves all published application records that fall under the filter/view category specified in the request query. If the request query has fields(fieldList) passed as query parameters, then it retrieves only specified field values of those applications that satisfy the filter condition.

If no fields are passed as query parameters, then the fields present in the default view are returned. A view can also be passed as a query parameter.

Example : If the filter is set to a particular version(where filterName is version and filterValue is the version number), then all published application records with that version are retrieved.

Start and count: If positions of the required published application records are to be specified, then start and count can be used. Start and count are used in a conjunction for pagination.

  • Example 1 : start=2 and count=3, returns the 3rd, 4th, and 5th published application records of the array as a response.
  • Example 2 : start=5 and count=2 returns the 6th and 7th published application records of the array as a response.

Authorizations:
Api-KeyJWT
query Parameters
viewIntegrationName
string

The integration name of the view. If this string value is not provided, then the first view based on the order number is considered as the default integration name.

filterName
string

The name of the field to filter the output using the equals option (replaces the filter set in the view, if any).

filterValue
string

The value of the field to filter the output using the equals option.

fieldList
string

A comma-separated list of field integrationNames. If present, only fields from this list are included in the output. The fields must be a part of the given view, else they are ignored.

start
integer <int32>

The 'Start' and 'count' are used in a conjunction for pagination. 'Start' denotes the position of the first published application record in the set of all published application records. The first record is at position 0 by default. So start=0 indicates the first record, start=2 indicates the third record, and so on.

count
integer <int32>

The 'Start' and 'count' are used in a conjunction for pagination.

  • Example 1: start=2 and count=3, returns the 3rd, 4th, and 5th published application records of the array as a response.
  • Example 2: start=5 and count=2 returns the 6th and 7th published application records of the array as a response.

Responses

Response samples

Content type
application/json

In this example, a master admin is retrieving published applications with viewIntegrationName=Published_Applications, filterName=version, and filterValue=1. The fieldList in the request contained name, isSystem, isApproved, and version. The start and count values were specified as 0 and 10, meaning that the first 10 published application records that satisfy the specified conditions were to be retrieved.

The consequent response retrieves all applications that satisfy the specified filter conditions. In this case, there were 6 available published application records, out of which only 3 applications happened to satisfy the filter conditions.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Count Published Application Records

This request is used to retrieve the number of published applications that fall under a particular view specified in the request query.

Authorizations:
Api-KeyJWT
query Parameters
viewIntegrationName
string

The integration name of the view. If not provided, the first view as per the order number is considered as default.

Responses

Response samples

Content type
application/json

The consequent response here has fetched the total number("count":4) of published application records with the specified view (viewIntegrationName=Marketplace_Popular_Apps).

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve Published Application Record

This request is used to retrieve information about a published application record with a known record ID. If record fields are specified in the request query along with the record ID, then only the specified field values are returned as a response. If no fields are specified with the record ID, then all field values are returned.

Authorizations:
Api-KeyJWT
path Parameters
recordId
required
string

Record ID of the application whose details are to be retrieved.

Note: This application must belong to the Published Applications object in Marketplace application.

query Parameters
fieldList
string
Examples:
  • - In this example, a master admin is retrieving the field values of name, version, appName, isSystem, and RB188873 of a published application record (6750). supply values in fieldList query parameter e.g. `fieldList=name,version,appName,isSystem,RB18887`
  • - In this example, a master admin is retrieving all field values of a published application record (6750). Hence the fieldList parameter is not specified.

A comma-separated list of field names. If present, only fields from this list are included in the output.

Responses

Response samples

Content type
application/json
Example

In this example, a master admin is retrieving the field values of name, version, appName, isSystem, and RB188873 of a published application record (6750). supply values in fieldList query parameter e.g. fieldList=name,version,isSystem.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Update Published Application Record

This request is used by a master admin to update attributes of a published application record, such as isApproved, description, app_featured, isSystem, etc.

Authorizations:
Api-KeyJWT
path Parameters
recordId
required
string

Record ID of the application record whose attributes are to be updated.

Note: This application must belong to the Published Applications object in Marketplace application.

Request Body schema: application/json

The request body must contain the integration names of the fields from the Published Application object, whose values are to be updated.

object

Responses

Request samples

Content type
application/json

In this example, a master admin is updating the values of the fields - description,appName,version,isSystem,app_paid, and isApproved in the Published Applications object in CRM application.

{
  • "appName": "CRM",
  • "app_paid": "false",
  • "description": "The CRM application includes all the core functionality required of a basic customer relationship management system by providing a central place for all of your sales, marketing, and support representatives to access and manage customer Accounts, Contacts, Leads, Cases and Opportunities. Also included in the CRM application is a Leads portal which you can embed into your website to accept lead submissions from visitors to your website. Configure as many different leads portals and pages as you want to manage all of your marketing campaigns. Lead records can easily be converted into Account records as needed by using standard conversion mapping functionality. Feel free to add your own Case portal to allow web submission of Cases. As with any other Infinite Blue application, CRM can be fully customized and extended to meet the needs of your organization. For example, administrators can create custom workflow events to assign incoming Leads to specific users based on territory assignments.",
  • "isApproved": "true",
  • "isSystem": "true",
  • "version": 2
}

Response samples

Content type
application/json

In this example, a master admin has updated the values of the fields - description,appName,version,isSystem,app_paid, and isApproved, in the Published Applications object in CRM application. The response here has returned the entire application record data - a combination of unmodified and modified record field values.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Push Update

This request can be used by a master admin to update the version of an already-installed application (from the Published Applications object in Marketplace application), for selected customers. Hence by using this request, a master admin can push the newer version of an application for several customers who already have the older version installed, at once.

Authorizations:
Api-KeyJWT
path Parameters
recordId
required
string

Record ID of the application whose version is to be updated.

Note: This application must belong to the Published Applications object in Marketplace application.

query Parameters
overrideChanges
boolean

Its True when existing application components are to be overwritten with latest updates.

False when only new application components included in this update are to be received, and not updated components.

For instance, if overrideChanges=false, then changes made by the publisher to existing fields, pages, views, templates, portals, portal pages, etc. are not reflected; only new components created by the publisher are reflected.

overridePermissions
boolean

If True, existing permissions are overwritten with latest updates.

If False, changes made by the publisher to existing role level permissions are ignored.

Request Body schema: application/json

The request body must contain an array of customer IDs for which the published application must be updated.

customerIds
Array of integers <int64> [ items <int64 > ]

Array of customer IDs for which the published application must be installed/updated.

Responses

Request samples

Content type
application/json

In this example, a master admin is pushing an updated version of the application (6750) to a customer(137287).

{
  • "customerIds": [
    ]
}

Response samples

Content type
application/json
Example

In this example, a master admin has pushed an updated version of the application(6750) to a customer(137287). The consequent response confirms that the update is scheduled by returning a statement, "Update is scheduled for push into 1 Customer(s) :137287".

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Retrieve Published Application Field

This end point is used by a master admin to fetch the following advanced type of fields from the Published Applications object:

  • file upload
  • image upload

Authorizations:
Api-KeyJWT
path Parameters
recordId
required
string

A string containing the published application record ID.

fieldIntegrationName
required
string

The integration name of the field.

query Parameters
output
string
Enum: "raw" "json"

This parameter applies to only file input fields. If it is not specified, its default value is "json" and returns meta-data and base-64 encoded content of the file. If specified as "raw", the file is returned in a raw format.it defaults to "json" and returns meta-data and base-64 encoded content of the file. If specified as "raw", the file is returned in raw format.

Responses

Response samples

Content type
application/json

In this example, a master admin has fetched the company_logo field in a published application record in Marketplace application.

The consequent response returns information about the company_logo field, such as the fileName, fileData, and contentType in JSON, since the output query parameter was not specified by the master admin.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Updates Published Application Fields(file upload, ImageUpload)

This request can be used to set or update advanced type of fields such as images and documents for a single specific published application record at a time in Marketplace application. A published application record can have several fields, that can be textual or of an advanced type. The field value can either be set for the first time, or it can be updated from an old value to a new value. The value, contentType, and fileName can be specified in the body of the request. A consequent response of the form Field <field name>" has been updated on <user name> confirms the update of the field for the given record. This request cannot be used for textual fields such as URLs, names, etc. (Textual updates can be made using updateDataRecord request.)

Notes: For instance, if a field is to be updated for a published application record in Marketplace application, then the contentType must specify what type of file is being uploaded. The value parameter is applicable only for file upload fields and the input value can be the file itself or a Base-64 encoded binary value of the file. If the value is a Base-64 encoded binary value of the file, then a parameter called fileName must imply the new name of the file being uploaded in the request. For instance, a Base-64 encoded binary value of a file to be uploaded can be “iVBORw0KGgoAAAANSUhEUgAAAQAAAA………” and while uploading it as a field value, its new fileName can be “XYZ.png”. If the value is the file name itself, then the need to use fileName is eliminated. Both these parameters are specific to the new file being uploaded, as opposed to old files (if any)

Authorizations:
Api-KeyJWT
path Parameters
recordId
required
string

A string containing the record ID.

fieldIntegrationName
required
string

The integration name of the field.

Request Body schema:
value
string <base64>

Can be the file path, or a Base-64 encoded binary value of the file.

  1. If the value is a Base-64 encoded binary value of the file, then a parameter called fileName must be specified. For instance, a Base-64 encoded binary value of a file to be uploaded can be iVBORw0KGgoAAAANSUhEUgAAAQAAAA.. and while uploading it as a field value, its new fileName can be XYZ.png.
  2. If the value is the file path, then fileName need not be specified.

contentType
string

MIME content type of uploaded data. It is applicable only for file upload fields (if the value is given as Base-64 encoded binary). For example,image/gif is used for an image in the GIF format, and text/html is used for text with embedded HTML commands.

fileName
string

Original name of file being uploaded. It is applicable only for file upload fields (if the value is given as Base-64 encoded binary).

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json

In this request, a master admin is updating the file field in a published application record(59012) in Marketplace application, with a application/xml type of file.

The consequent response confirms that the update has been made successfully, by returning a statement, Field "Application XML" has been updated on BUG VALIDAte.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

Install Published Application

By using this request, a master admin can install an already published application for customers. For more information, see Managing the Marketplace using the Marketplace application in Platform Private Cloud.

Authorizations:
Api-KeyJWT
path Parameters
recordId
required
string

Record ID of the application to be installed.

Note This application must belong to the Published Applications object in Marketplace application.

Request Body schema: application/json

Description

customerIds
Array of integers <int64> [ items <int64 > ]

Array of customer IDs for which the published application must be installed/updated.

Responses

Request samples

Content type
application/json

In this request, a master admin is installing CRM application for customers (137287 and 140891). This application belongs to the Published Applications object in Marketplace application, and its recordId is 6750 (specified as a path parameter).

{
  • "customerIds": [
    ]
}

Response samples

Content type
application/json
Example

In this request, a master admin has installed CRM application for customers (137287 and 140891). This application belongs to the Published Applications object in Marketplace application, and its recordId is 6750 (specified as a path parameter).

The consequent response returns a message, "Installation is scheduled for given Customer(s).", implying that the application will be installed as scheduled.

{
  • "code": 200,
  • "message": "OK",
  • "results": [
    ]
}

List Customer Records

This request is used to fetch details of all customers that fall under the view category specified in the request. These fields must be a part of the given view, else they are ignored. If the request query has fields(fieldList) passed as query parameters, then it retrieves only specified field values of those customers that satisfy the filter condition.

If no fieldList is specified, then all fields of the customer records are fetched.

Example : For example, if a filter is set, (where filterName is isActive, and filterValue is the true), then all customer records that have isActive=true are retrieved. If the request query has fields(fieldList) passed as query parameters, then it retrieves only specified field values of those records that satisfy the filter condition.

Start and count : If positions of the required customer records are to be specified, then start and count can be used. Start and count are used in a conjunction for pagination. <ul

  • Example 1 : start=2 and count=3, returns the 3rd, 4th, and 5th customer records of the array as a response.
  • Example 2 : start=5 and count=2 returns the 6th and 7th records of the array as a response.

    • Authorizations:
    Api-KeyJWT
    query Parameters
    viewIntegrationName
    string

    The integration name of the view. If this string value is not provided, then the first view based on the order number is considered as the default integration name

    filterName
    string

    The name of the field to filter the output using the equals option (replaces the filter set in the view, if any).

    filterValue
    string

    The value of the field to filter the output using the equals option. option.

    fieldList
    string

    A comma-separated list of field integrationNames. If present, only fields from this list are included in the output. The fields should be a part of the given view, else they are ignored.

    start
    integer <int32>

    'Start' and 'count' are used in a conjunction for pagination. 'Start' denotes the position of the first published application record in the set of all published application records. The first record is at position 0 by default. So start=0 indicates the first record, start=2 indicates the third record, and so on.

    count
    integer <int32>

    The 'Start' and 'count' are used in a conjunction for pagination.

    • Example 1: start=2 and count=3, returns the 3rd, 4th, and 5th customer records of the array as a response.
    • Example 2: start=5 and count=2 returns the 6th and 7th customer records of the array as a response.

    Responses

    Response samples

    Content type
    application/json

    In this example, a master admin is retrieving the first 10 records (count=10) that fall under the specified filter category, isActive= true. The fields required to be retrieved for each customer are specified in the fieldList (fieldList=id,name,status).The consequent response returns the first 10 customer record(s) that fall under the specified filter category, isActive= true. For each customer, fields specified in the fieldList (fieldList=id,name,status) are retrieved. Only 6 records satisfy isActive= true. Hence 6 customer records are retrieved.

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Update Customer Records

    This request can only be used to update fields that are not associated with any background actions such as DB Move, Storage Move, etc. in multiple records at once. Customer details such as expiredAt, language, companyName, firstName, lastName, job_title, phone, timeZone, company_size, maxAPIHitsHourly, and all maxlimits can be updated.

    Note We currently do not support modifying the following using APIs. Doing so may cause inconsistent results.

    • Database
    • Storage
    • Search Index
    • Installed Application(instApps)

    Authorizations:
    Api-KeyJWT
    Request Body schema: application/json

    The request body contains an array of customer JSONs, where the ID of each customer is specified in its respective JSON.

    Note Values from the default set cannot be modified. For instance, if a service level plan that a customer already has, is altered, then the dependent values such as maxApplications,maxBackupStorageMB,maxFieldDefs,maxForeignLangs,maxObjectDefs,maxPortals,maxObjectRecords,maxStorageMB,maxUsers, etc. remain unmodified. The admin must alter each dependent field individually.

    object

    Responses

    Request samples

    Content type
    application/json

    In this example request, a master admin is setting max limits for two customers with IDs 140891 and 137287.

    [
    • {
      },
    • {
      }
    ]

    Response samples

    Content type
    application/json
    {
    • "code": 200,
    • "message": "Operation was successful.",
    • "results": [
      ]
    }

    Create Customer Record(s)

    This request is used to create one or more customer records by specifying customer details such as the customer’s company, city, state, country, etc. Upon successful creation of a customer record, a unique customer ID is returned, which can later be used to update it. Multiple customer records can be created at once by specifying an array of JSONs with the respective key value pairs.

    Authorizations:
    Api-KeyJWT
    Request Body schema: application/json

    Parameters such as companyName, firstName, lastName, loginName, etc. are passed in the request body. Certain parameters may have picklist code values.

    Note Fields that are mandatory/required in the object must be passed while creating a customer.

    object

    Responses

    Request samples

    Content type
    application/json
    Example

    In this request, a master admin is creating a customer with basic values, such as companyName, loginName, email, etc. The values for database, search servers, storage servers, plan details, etc. are also specified.

    {
    • "city": "Hyderabad",
    • "companyName": "United Company",
    • "company_size": "Less than 10 employees",
    • "country": "US",
    • "dbName": "SQLServer",
    • "email": "george.tree@company.com",
    • "emailEncoding": "UTF-8",
    • "expiredAt": "2021-05-25",
    • "firstName": "George",
    • "instApps": [
      ],
    • "job_title": "CEO",
    • "language": "en",
    • "lastName": "Tree",
    • "loginName": "George.tree",
    • "mailSender": "george.tree@company.com",
    • "maxAPIHitsHourly": 500,
    • "maxSystemBackups": 5,
    • "phone": "+91 7788338877",
    • "renewal_date": "",
    • "searchIndex": "SEARCH<>Built-In",
    • "securityLevel": "Medium",
    • "serviceLevel": "Standard",
    • "state": "AL",
    • "status": "A",
    • "storageLocation": "ab7986cb-f158-466a-b815-57523a0bc1a1<>jane-doe-electrica",
    • "timeZone": "Asia/Kolkata"
    }

    Response samples

    Content type
    application/json
    {
    • "code": 200,
    • "message": "Operation was successful.",
    • "results": [
      ]
    }

    Delete Customer Record(s)

    This request is used in cases where multiple customer records need to be deleted in a single instance. Multiple customer record IDs can be specified in the request query by separating them with commas. The response confirms the deletion of given records with their respective IDs. Deleting a customer clears up all data related to the customer (for instance, users, storagefiles, backups, Data,Batchjobs, etc.).

    Note If IDs of non-existent/invalid customer records are specified, then they are ignored

    Authorizations:
    Api-KeyJWT
    query Parameters
    recordIds
    required
    string

    Comma separated list of record IDs.

    Responses

    Response samples

    Content type
    application/json

    The consequent response confirms the deletion of the customer records whose IDs are specified in the request (recordIds=115694,133687) by returning a statement, "Deleted record with ids 115694,133687".

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Count Customer Records

    This request is used to retrieve a count of the customer records, based on the viewIntegrationName specified in the request.

    Authorizations:
    Api-KeyJWT
    query Parameters
    viewIntegrationName
    string

    The integration name of the view. If not provided, the first view as per the order number is considered as default.

    Responses

    Response samples

    Content type
    application/json

    In this request, a master admin is retrieving the total number of customer records in the specified view(viewIntegrationName=Expiring_in_1_week).

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Retrieve Customer Record

    This request is used to fetch details of the customer whose record ID is specified in the request. If a fieldList is specified, then only those customer record fields are retrieved. If no fieldList is specified, then all fields of the customer record are fetched.

    Authorizations:
    Api-KeyJWT
    path Parameters
    recordId
    required
    string

    Customer record Id(custId)

    query Parameters
    fieldList
    string

    A comma-separated list of field names. If present, only fields from this list are included in the output.

    Responses

    Response samples

    Content type
    application/json

    In this example, a master admin is retrieving specific fields(fieldList=maxAPIHitsHourly, maxApplications, maxBackupStorageMB, maxFieldDefs, maxForeignLangs, maxObjectDefs, maxPortals, maxObjectRecords, maxStorageMB, maxSystemBackups, maxUsers) of the customer with record ID 140891.

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Update Customer Record

    This request can only be used to update fields that are not associated with any background actions such as DB Move, Storage Move, etc. in multiple records at once. Customer details such as expiredAt ,language ,companyName,firstName,lastName,job_title,phone,timeZone,company_size,maxAPIHitsHourly, and all maxlimits can be updated.

    Note We currently do not support modifying the following using APIs. Doing so may cause inconsistent results.

    • Database
    • Storage
    • Search Index
    • Installed Application(instApps)

    Authorizations:
    Api-KeyJWT
    path Parameters
    recordId
    required
    string
    Request Body schema: application/json

    The request body contains an array of customer JSONs, where the ID of each customer is specified in its respective JSON.

    Note Values from the default set cannot be modified. For instance, if a service level plan that a customer already has, is altered, then the dependent values such as maxApplications,maxBackupStorageMB,maxFieldDefs,maxForeignLangs,maxObjectDefs,maxPortals,maxObjectRecords,maxStorageMB,maxUsers, etc. remain unmodified. The admin must alter each dependent field individually.

    object

    Responses

    Request samples

    Content type
    application/json

    In this request, a master admin is individually setting max limits for a customer(137286).

    {
    • "maxAPIHitsHourly": 1000,
    • "maxApplications": 10,
    • "maxBackupStorageMB": 50,
    • "maxFieldDefs": 10,
    • "maxForeignLangs": 3,
    • "maxObjectDefs": 20,
    • "maxObjectRecords": 1000,
    • "maxPortals": 20,
    • "maxStorageMB": 25,
    • "maxUsers": 15
    }

    Response samples

    Content type
    application/json

    The consequent response to the PUT request returns all the modified and unmodified customer details.

    Note The record ID returned in the response is the customer record ID.

    {
    • "CUSTOMER_comm": [ ],
    • "R1721682": [ ],
    • "R5683293": [ ],
    • "R7803": [ ],
    • "RB188873": [
      ],
    • "RSUBSCRIBER": [
      ],
    • "apiLog": false,
    • "city": "Hyderabad",
    • "companyName": "East India Company",
    • "company_size": 2906,
    • "country": 1187,
    • "createdAt": "2021-02-23T11:38:13.000+00:00",
    • "createdBy": 18784,
    • "createdByDefId": 1769,
    • "dbName": "SQLServer",
    • "email": "gandhi.mahatma@company.com",
    • "emailEncoding": "UTF-8",
    • "expiredAt": "2021-05-24T18:30:00.000+00:00",
    • "firstName": "Gandhi",
    • "hideSidebar": false,
    • "id": 137287,
    • "instApps": [
      ],
    • "isActive": true,
    • "isTestDrive": false,
    • "job_title": "CEO",
    • "language": "en",
    • "lastName": "Mahatma",
    • "logLevel": false,
    • "loginBlocked": false,
    • "loginName": "Gandhi.Mahatma",
    • "mailSender": "george.tree@company.com",
    • "maxAPIHitsHourly": 1000,
    • "maxApplications": 10,
    • "maxBackupStorageMB": 50,
    • "maxFieldDefs": 10,
    • "maxForeignLangs": 3,
    • "maxObjectDefs": 20,
    • "maxObjectRecords": 1000,
    • "maxPortals": 20,
    • "maxStorageMB": 25,
    • "maxSystemBackups": 5,
    • "maxUsers": 15,
    • "mobileDevEnabled": true,
    • "name": "East India Company",
    • "overusedRes": false,
    • "paying_customer": false,
    • "phone": "917788338877",
    • "plan_description": "Standard: 10 Users, 50,000 Records, 500MB Storage, 2 Portals, 4GB Bandwidth",
    • "process": 3063,
    • "searchIndex": "SEARCH<>Built-In",
    • "searchServer": "SEARCH",
    • "securestore": true,
    • "securityLevel": 2,
    • "serviceLevel": 3,
    • "showAppTree": false,
    • "state": 1196,
    • "status": 3060,
    • "storageLocation": "ab7986cb-f158-466a-b815-57523a0bc1a1<>jane-doe-electrica",
    • "storageServer": "STORAGE",
    • "stylesheet": "rbtheme.css",
    • "supportAccessEnabledTime": "2021-02-24T11:38:20.000+00:00",
    • "timeZone": "Asia/Kolkata",
    • "updatedAt": "2021-02-23T12:17:00.863+00:00",
    • "updatedBy": 18784,
    • "updatedByDefId": 1769,
    • "useNewUI": false
    }

    Delete Customer Record

    This request is used to delete a single customer record with a known customer record ID. The record ID is specified in the request query; the consequent response confirms the deletion of the record.

    Note Deleting a customer clears up all data related to the customer (for instance, users, storagefiles, backups, Data,Batchjobs, etc.).

    Authorizations:
    Api-KeyJWT
    path Parameters
    recordId
    required
    string

    Responses

    Response samples

    Content type
    application/json

    The consequent response confirms the deletion of the customer record whose ID is specified in the request(here, 133686), by returning a statement, "Deleted record with id 133686".

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Unload Customer

    This request is used to unload a single customer at a time; all users who are currently logged in are logged out when a customer is unloaded. Upon unloading, the customer is unloaded from all prod servers and the respective UI/API sessions expire.

    Authorizations:
    Api-KeyJWT
    path Parameters
    customerId
    required
    string

    The id of the customer record.

    Responses

    Response samples

    Content type
    application/json

    On successfully unloading a customer(54808), the consequent response confirms the same by returning a statement, "Customer 54808 unloaded successfully".

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Users

    The Users API section describes operations pertaining to user records in Platform. From this section, API developers can understand how to formulate requests to create, update, retrieve, and delete user records as required. Here are a few important descriptions :

    User Record - A user record is a collection of user data. A user can use his/her loginName to log into an application. The access permissions depend on the user’s role. For more information, see Working with records.

    List User Records

    This request is used to retrieve all the field names and corresponding field values of user records that satisfy the conditions specified in the request. If the parameter fieldList is given, then only fields from this list are returned in the response. This request retrieves all records that fall under the specified filter category in the request query. For instance, a filter can be set in order to retrieve user records of users with the job title of a Software Developer.

    Authorizations:
    Api-KeyJWT
    query Parameters
    viewIntegrationName
    string

    Integration name of the view.

    filterName
    string

    The name of the field to filter the output using the equals option (replaces the filter set in the view, if any).

    filterValue
    string

    The value of the field to filter the output using the equals option.

    fieldList
    string

    A comma-separated list of field integrationNames. If present, only fields from this list are included in the output. The fields should be a part of the given view, else ignored.

    start
    integer <int32>

    The start and count are used in a conjunction for pagination. Start denotes the position of the first record in the set of all record.The first record is at position 0 by default. So start=0 indicates the first record start=2 indicates the third record and so on.

    count
    integer <int32>

    The Start and count are used in a conjunction for pagination.

    • Example 1: start=2 and count=3, returns the 3rd, 4th, and 5th records of the array as a response.
    • Example 2: start=5 and count=2 returns the 6th and 7th records of the array as a response.

    Responses

    Response samples

    Content type
    application/json

    In this example, we are fetching the first 5 user records from the view (custom_view) whose job title is QA. The consequent response here has fetched the first 5 user records with the fields in the viewcustom_view,whose job title matches with “QA“.

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Update User Record(s)

    This request is used to update the one or more details (field values) of multiple given records in user object at once. Record field values such as firstName, lastName, timeZone, email, role, etc. can be updated with this request.

    Authorizations:
    Api-KeyJWT
    Request Body schema: application/json

    This request is used to update the one or more details (field values) of multiple given records in an user object at once. Record field values such as firstName, lastName, timeZone, email, role, etc. can be updated with this request.

    Note: Different details can be updated for different user records. For instance, firstName and lastName can be updated for one user record, while timeZone can be updated for another record.

    object

    Responses

    Request samples

    Content type
    application/json

    In this example, we are updating two user records.

    • We are using the key value pair - record ID :110551 as an identifier to update “email” and “job_title” for a user (Chuck Greedy).
    • We are using the key value pair - record ID :110557 as an identifier to update “email” for another user (Tedda Cornwell).

    [
    • {
      },
    • {
      }
    ]

    Response samples

    Content type
    application/json

    In this example, we are updating two user records.

    • We are using the key value pair - record ID :110551 as an identifier to update “email” and “job_title” for a user (Chuck Greedy).
    • We are using the key value pair - record ID :110557 as an identifier to update “email” for another user (Tedda Cornwell).

    The consequent response has returned the updated and unaltered values of 2 user records with record IDs :110551 and 110557 (specified in the request body ). Details of user records appear in a list format, meaning that user record details are returned in a sequential manner.

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Create User Record(s)

    This request is used to create a user record, with relevant details, such as firstName, lastName, loginName, timeZone, email, role, etc. One or many user records can be created at once with this request.

    Authorizations:
    Api-KeyJWT
    Request Body schema: application/json
    object

    Responses

    Request samples

    Content type
    application/json
    Example

    In this example we are creating a user with Admin role. In the request body, all the mandatory and optional field integration names are specified along with their corresponding values. The user attributes specified in this particular request are firstName, lastName, loginName, timeZone, email, and role. Hence, we are requesting record creation for a user named John Doe whose role is Administrator.

    {
    • "email": "john.doe@company.com",
    • "firstName": "John",
    • "lastName": "Doe",
    • "loginName": "john.doe@company.com",
    • "role": "Administrator",
    • "timeZone": "Asia/Calcutta"
    }

    Response samples

    Content type
    application/json
    Example

    In this example we are creating a user with Admin role. In the request body, all the mandatory and optional field integration names are specified along with their corresponding values. The user attributes specified in this particular request are firstName, lastName, loginName, timeZone, email, and role. Hence, we are requesting record creation for a user named John Doe whose role is Administrator.

    The consequent response confirms the creation of the user record, by returning its unique record ID (110854), along with the object name (USER in this case).

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Delete User Records

    This request deletes multiple user records in their entirety in one go.

    Authorizations:
    Api-KeyJWT
    query Parameters
    recordIds
    required
    string

    A string containing the record IDs of the records required to be deleted.

    Responses

    Response samples

    Content type
    application/json

    In this example, we are deleting 3 user records by specifying their record IDs(110557,110555,110553) in the request.The consequent response confirms the deletion of the 3 user records whose record IDs were specified in the request, by returning the message “Deleted records with ids 110557,110555,110553”.

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Retrieve User Count

    This request is used to retrieve the number of records that fall under a particular filter/view specified in the request query. For instance, if a view is mentioned in the query, then the number of records that have the specified view is returned as the response.

    Authorizations:
    Api-KeyJWT
    query Parameters
    viewIntegrationName
    string

    The integration name of the view. If not provided, the first view as per the order number is considered as default.

    Responses

    Response samples

    Content type
    application/json
    Example

    In this example, we are retrieving the number of user records with the view IntegrationName All_Users by passing the viewIntegrationName=All_User.

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Retrieve User Record

    This request is used to retrieve all the field names and corresponding field values of a single user record whose loginName/record ID is specified in the request. If the parameter fieldList is given, then only fields from this list are returned in the response.

    Authorizations:
    Api-KeyJWT
    path Parameters
    loginNameOrRecordId
    required
    string

    Any one of the following must be specified:

    • loginName : Login name for an active Platform user account in the same tenant.
    • RecordID : A string containing the user record ID. No two user records can have the same record ID.

    query Parameters
    fieldList
    string

    A comma-separated list of field names. If given, then only fields from this list are included in the output.

    Responses

    Response samples

    Content type
    application/json
    Example

    n this example we are retrieving a user record by specifying the loginName in the request. This consequent response has returned the user fields relevant to the user whose loginName is specified in the request. Since a fieldList was not specified in the request, all the user fields have been returned.

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Update User Record

    This request is used to update one or more field values for a single user record in an application, such as firstName, lastName, timeZone, email, role, etc.

    Authorizations:
    Api-KeyJWT
    path Parameters
    loginNameOrRecordId
    required
    string

    Any one of the following must be specified.

    • loginName- Login name for an active Platform user account in the same tenant.
    • RecordId- A string containing the user record ID. No two user records can have the same record ID.

    Request Body schema: application/json

    This request is used to update one or more field values for a single user record in an application, such as firstName, lastName, timeZone, email, role, etc.

    object

    Responses

    Request samples

    Content type
    application/json

    In this example, we are updating the email address of a user whose record ID is 110854. In the request, we are specifying the field integration name email, along with the value we want to update the field email to, that is danny.scott@company.com.

    {
    • "email": "danny.scott@company.com"
    }

    Response samples

    Content type
    application/json

    On updating the record by passing the email for the specific id of user, the consequent response has returned the entire user record data - a combination of unmodified and modified user record field values. Hence, along with the now-updated email address (danny.scott@company.com), the unaltered field values are also returned.

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Delete User Record

    This request deletes a single user record in its entirety.

    Authorizations:
    Api-KeyJWT
    path Parameters
    loginNameOrRecordId
    required
    string

    Any one of the following must be specified:

    • loginName : Login name for an active Platform user account in the same tenant.
    • RecordID : A string containing the user record ID. No two user records can have the same record ID.

    Responses

    Response samples

    Content type
    application/json

    In this example, we are deleting a user record by using the loginName (jane.doe) as an identifier. The consequent response confirms the deletion of the user record whose loginName is jane.doe as specified in the request, by returning the message Deleted record with id 110854.

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Reset Password Privileges

    This request resets the password of a specified user based on the loginName/record ID provided.

    Note Resetting a password requires administrative privileges.

    Authorizations:
    Api-KeyJWT
    path Parameters
    loginNameOrRecordId
    required
    string

    Any one of the following must be specified:

    • loginName : Login name for an active Platform user account in the same tenant.
    • RecordID : A string containing the user record ID. No two user records can have the same record ID.

    Responses

    Response samples

    Content type
    application/json

    In this example we are resetting the password for a user (Emlen Tinton) by using his loginName (emlen.tinton) as an identifier. Upon successfully resetting the password, the consequent response confirms the same. An email is sent to the user’s registered email address.

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Retrieve User's LDF Details

    This request is used to get LDF IDs corresponding to each of the dimensions - $ORG_LOCN, $ORG_DEPT and $ORG_FUNC.

    Authorizations:
    Api-KeyJWT
    path Parameters
    loginNameOrRecordId
    required
    string

    Any one of the following must be specified:

    • loginName : Login name for an active Platform user account in the same tenant.
    • RecordID : A string containing the user record ID. No two user records can have the same record ID.

    Responses

    Response samples

    Content type
    application/json

    In this example, we are retrieving the LDF details of a user. The consequent response returns access permissions to the Location(445637462), Department(445637455) and Function(445637465) records for the specified user(445638426).

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    userResource

    The User Resource API section describes operations pertaining to manage a user’s login in the Platform. In this section, API developers can log in/log out using a request.

    Login

    Users can initiate a login through this request by providing all required authentication details, such as the username, password, API token, etc., depending on the authentication type used during profile creation.

    This endpoint should be prefixed with the PROD's value that the current customer is loaded in, such as /prod3/user/login. This prefix remains constant for customers hosted on dedicated production servers, or the necessary production server information may be obtained from UI sessions.

    If the value of the production environment where the customer is already loaded is unknown, refer to Platform REST API 2.0 Documentation

    Note: When a shared property, AllowMultipleRestSessions is set to True, the user can execute multiple Login requests that return corresponding JWT tokens that are simultaneously active. The default value for this property is False.

    Authorizations:
    basic_authApi-Key
    query Parameters
    version
    integer <int32>

    Version of APIs

    Responses

    Response samples

    Content type
    application/json
    Example

    In this example, we have API authentication set to Password in the Platform. We are executing the Login API in order to request a JWT token and a URL with basic authentication (Authorization :Basic aGFyaXRlamExQHlvcG1haWwuY29tOnByb2dyZXNz). A user password is used as a password to formulate a basic auth header.

    For instance, if the username is 'narendramodi', and the Password is 'India', then the formulated basic auth header is Basic bmFyZW5kcmFtb2RpOkluZGlh.

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    Logout

    The user can invalidate a JWT token using this request. The currently active JWT token (returned in the response to the login request) must be used to log out of the currently active API session that began when the user executed the login request.

    Note: A JWT can expire in 2 ways:

    1. The configured expiration time is reached.
    2. When the Logout request is executed. If the shared property, AllowMultipleRestSessions is set to True, and multiple API sessions exist for the same user, then the user can execute the Logout request individually for each JWT token.
    3. User cannot invalidate the API token using this endpoint

    Authorizations:
    Api-KeyJWT

    Responses

    Response samples

    Content type
    application/json

    The consequent response returns a message, 'User has logged out of given JWT session' to confirm that the user has logged out of the API session. This implies that the JWT token that was used for this session can no longer be used as it has become invalid.

    {
    • "code": 200,
    • "message": "OK",
    • "results": [
      ]
    }

    customMethod

    The Custom Method API section describes operations pertaining to any business method used in the Platform. In this section, API developers can customize the behavior of requests to the backend by providing a means to implement server-side business logic. See Custom Methods for more information.

    GET operation on business method

    GET operation on business method

    Authorizations:
    Api-KeyJWT
    path Parameters
    customMethodName
    required
    string

    The name that needs to be executed.

    Responses

    Response samples

    Content type
    application/json
    {
    • "code": 200,
    • "message": "Operation was successful",
    • "results": { }
    }

    PUT operation on business method

    PUT operation on business method

    Authorizations:
    Api-KeyJWT
    path Parameters
    customMethodName
    required
    string

    The name that needs to be executed.

    Responses

    Response samples

    Content type
    application/json
    {
    • "code": 200,
    • "message": "Operation was successful",
    • "results": { }
    }

    POST operation on business method

    POST operation on business method

    Authorizations:
    Api-KeyJWT
    path Parameters
    customMethodName
    required
    string

    The name that needs to be executed.

    Responses

    Response samples

    Content type
    application/json
    {
    • "code": 200,
    • "message": "Operation was successful",
    • "results": { }
    }

    DELETE operation on business method

    DELETE operation on business method

    Authorizations:
    Api-KeyJWT
    path Parameters
    customMethodName
    required
    string

    The name that needs to be executed.

    Responses

    Response samples

    Content type
    application/json
    {
    • "code": 200,
    • "message": "Operation was successful",
    • "results": { }
    }