{
"openapi": "3.0.3",
"info": {
"title": "Bs4 API",
"description": "This API works with bs4 CORE. bs4 CORE is an advanced system that goes well beyond the capabilities of a regular CRM, but in this documentation bs4 CORE will be called \"CRM\" to simplify reading and understanding.
API uses Bearer token as\n authentication method. Token have to be created in the CRM settings.\n
Our API is a part of CRM, which means that every CRM has it's own\n API. Base URL for API is therefore a CRM URL - Example;\n http:///api/class/id",
"version": "1.0.1"
},
"tags": [
{
"name": "Simple - Create / Read / Update / Delete",
"description": "Simple commands for CRUD operations on objects from CRM"
},
{
"name": "Exec - Advanced commands",
"description": "Exec are commands that perform more advanced operations."
}
],
"paths": {
"/api/{className}/{objectID}": {
"get": {
"summary": "Reads data about an object with a given ID. It can also read multiple IDs.",
"description": "Reads data about an object with a given ID. It can also read multiple IDs.",
"tags": [
"Simple - Create / Read / Update / Delete"
],
"operationId": "simpleRead",
"parameters": [
{
"name": "className",
"in": "path",
"description": "The name of the class from which the object/objects we want to read. The class name is case-insensitive. The classes that can be used are in....",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "objectID",
"in": "path",
"description": "IDs of the objects we want to read. You can provide several values separated by a comma, e.g. /api/files/34,45 - Reads the file with ID 31 and 45. If no ID is provided, it reads all files.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "This parameter limits the number of returned objects",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Correct response from API. The 'results' list contains data regarding\n read objects.",
"content": {
"application/json": {
"examples": {
"Default": {
"value": "{\n \"code\": 200,\n \"results\": [\n {\n \"job\": 0,\n \"contractor\": 0,\n \"who_downloaded\": 0,\n \"id\": 45,\n \"name\": \"File45.pdf\",\n \"name_on_disk\": \"15137762313bba2a14e400d690f75cb3a6428b6a45\",\n \"size\": \"1123\",\n \"added_by\": 14,\n \"description\": \"File description\",\n \"status\": \"o\",\n \"mime\": \"application/pdf; charset=binary\",\n \"file_type\": 2038,\n \"external_id\": \"\",\n \"account_synchronized\": 0,\n \"recently_downloaded\": \"0000-00-00 00:00:00\",\n \"archiving_status\": \"\",\n \"archiving_date\": \"0000-00-00 00:00:00\",\n \"id_common_version\": \"5a3a64231bba0\",\n \"last_modification_who\": 14,\n \"added_who\": 14,\n \"file_source\": \"1\",\n \"how_many_downloads\": \"0.00\",\n \"name_extension\": \"pdf\",\n \"last_modification_date\": \"2017-12-20 13:23:51\",\n \"added_date\": \"2017-12-20 13:23:51\",\n \"icon_type\": \"4\",\n \"cloud_file_address\": \"\"\n },\n {\n \"job\": 0,\n \"contractor\": 0,\n \"who_downloaded\": 0,\n \"id\": 34,\n \"name\": \"instruction.pdf\",\n \"name_on_disk\": \"144136427401dasdaf2f124e2b06f69c843c1f5\",\n \"size\": \"8328596\",\n \"added_by\": 14,\n \"description\": \"\",\n \"status\": \"y\",\n \"mime\": \"application/pdf; charset=binary\",\n \"file_type\": 2038,\n \"external_id\": \"\",\n \"account_synchronized\": 0,\n \"recently_downloaded\": \"0000-00-00 00:00:00\",\n \"archiving_status\": \"\",\n \"archiving_date\": \"0000-00-00 00:00:00\",\n \"id_common_version\": \"55e6f24e340c5\",\n \"last_modification_who\": 14,\n \"added_who\": 14,\n \"file_source\": \"1\",\n \"how_many_downloads\": \"0.00\",\n \"name_extension\": \"pdf\",\n \"last_modification_date\": \"2015-09-04 10:57:54\",\n \"added_date\": \"2015-09-04 10:57:54\",\n \"icon_type\": \"4\",\n \"cloud_file_address\": \"\"\n }\n ],\n \"success\": true\n}"
}
}
}
}
},
"401": {
"description": "Authentication Failure"
},
"404": {
"description": "Resource not Found"
}
}
},
"put": {
"summary": "API command that updates data about object in CRM",
"description": "This command is responsible for updating data about object in CRM. One request can be used to change multiple fields. This command requires appropriate permissions set in the connector settings. \nIn the request body, we provide pair values - field:value.",
"tags": [
"Simple - Create / Read / Update / Delete"
],
"operationId": "update",
"parameters": [
{
"name": "className",
"in": "path",
"description": "The name of the class from which the object we want to update. The class name is case-insensitive. The classes that can be used are in....",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "objectID",
"in": "path",
"description": "ID of the object we want to update.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"fieldToChange": {
"type": "string",
"example": "valueToSet"
},
"name": {
"type": "string",
"example": "filenameABC.jpg"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success - data has been updated",
"content": {
"application/json": {
"examples": {
"Default": {
"value": "{\n \"code\": 200,\n \"results\": 1,\n \"success\": true\n}"
}
}
}
}
},
"400": {
"description": "Client or Validation Error"
},
"401": {
"description": "Authentication Failure"
},
"404": {
"description": "Resource not found!"
}
}
},
"delete": {
"summary": "API command that deletes object from CRM.",
"description": "This command is responsible for deleting object of provided class. Request body should be empty - there is no need for additional data.",
"tags": [
"Simple - Create / Read / Update / Delete"
],
"operationId": "delete",
"parameters": [
{
"name": "className",
"in": "path",
"description": "The name of the class from which the object we want to delete.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "objectID",
"in": "path",
"description": "ID of the object we want to delete.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success - data has been deleted",
"content": {
"application/json": {
"examples": {
"Default": {
"value": "{\n \"code\": 200,\n \"results\": 1,\n \"success\": true\n}"
}
}
}
}
},
"400": {
"description": "Client or Validation Error"
},
"401": {
"description": "Authentication Failure"
},
"404": {
"description": "Resource not found!"
}
}
}
},
"/api/{className}/": {
"post": {
"summary": "Creates a new object of provided class.",
"description": "Creates a new object of provided class. Values for object's fields are specified in request body. This command requires appropriate permissions set in the connector settings.",
"tags": [
"Simple - Create / Read / Update / Delete"
],
"operationId": "create",
"parameters": [
{
"name": "className",
"in": "path",
"description": "Name of the class you want to create object for.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"fieldName1": {
"type": "string",
"example": "fieldValue1"
},
"fieldName2": {
"type": "string",
"example": "fieldValue2"
},
"fieldName3": {
"type": "string",
"example": "fieldValue3"
},
"fieldName4": {
"type": "string",
"example": "fieldValue4"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Correct response from API. Object has been created. \"results\" field contain ID of created object.",
"content": {
"application/json": {
"examples": {
"Default": {
"value": "{\n \"code\": 201,\n \"results\": 175,\n \"success\": true\n}"
}
}
}
}
},
"400": {
"description": "Client or Validation Error"
},
"401": {
"description": "Authentication Failure"
},
"404": {
"description": "Resource not Found"
}
}
}
},
"/api/exec/notification": {
"post": {
"summary": "API command that creates a bell notification in CRM bs4 CORE.",
"description": "Notifications are available in CRM under the bell icon. Various messages are sent there to inform the user about certain processes and results of activities. This command creates such a notification.\nParameters classId and objectId are optional - when supplied, the notification will contain link to related object",
"tags": [
"Exec - Advanced commands"
],
"operationId": "notification",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"msgs": {
"type": "array",
"description": "List of notification to send. Each notification contain error code and optional params. Some of the errors have placeholder where text from 'params' will be inserted",
"items": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "ID of the Error",
"example": 500001
},
"params": {
"type": "array",
"description": "List of strings that are used for placeholders.",
"items": {
"type": "string",
"description": "Optional text values for placeholders",
"example": "example@gmail.com"
}
}
}
}
},
"idUser": {
"type": "integer",
"description": "ID of CRM user to which a notification should be sent",
"example": 14
},
"classId": {
"type": "integer",
"description": "ID of class related to that notification. (Optional)",
"example": 123
},
"objectId": {
"type": "integer",
"description": "ID of object related to that notification. (Optional)",
"example": 432
}
},
"required": [
"msgs",
"idUser"
]
}
}
}
},
"responses": {
"200": {
"description": "Success - notification has been sent.",
"content": {
"application/json": {
"examples": {
"Default": {
"value": "{\n \"results\": \"OK\",\n \"success\": true\n}"
}
}
}
}
},
"400": {
"description": "Missing error code! / Missing idUser!"
},
"401": {
"description": "Authentication Failure"
}
}
}
},
"/api/exec/downloadfile": {
"post": {
"summary": "API command that downloads file from CRM repository",
"description": "This command is responsible for downloading the file from the CRM repository. The file content is downloaded in Base64 format, so the requester must decode the content themselves and save it as a file. The API response also includes the filename, making it easier to create the file. ",
"tags": [
"Exec - Advanced commands"
],
"operationId": "download",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"fileIdCRC": {
"type": "string",
"example": "1232-25dgd62846fj3764yhnf736trpold34",
"description": "ID + Checksum of the file. If the API detects any problems with the checksum, an error will be returned."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success - file has been downloaded.",
"content": {
"application/json": {
"examples": {
"Default": {
"value": "{\n \"results\": {\n \"content\": \"< CONTENT OF A FILE AS BASE64 >\",\n \"filename\": \"filename.extension\"\n},\n \"success\": true\n}"
}
}
}
}
},
"400": {
"description": "fileIdCRC - missing or empty / fileIdCRC - checksum error"
},
"401": {
"description": "Authentication Failure"
},
"404": {
"description": "File not found!"
}
}
}
},
"/api/exec/uploadfile": {
"post": {
"summary": "API command that uploads file to CRM repository",
"description": "This command is responsible for uploading the file to the CRM repository. Request have to be send as multipart/form-data. You can only send one file at a time. At the moment, there are no special restrictions regarding size and extensions. Response contains idCRC of added file from CRM repository.",
"tags": [
"Exec - Advanced commands"
],
"operationId": "upload",
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"FileContent": {
"type": "string",
"format": "binary",
"description": "File to upload"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success - file has been uploaded.",
"content": {
"application/json": {
"examples": {
"Default": {
"value": "{\n \"results\": \"< fileIdCRC of added file >\",\n \"success\": true\n}"
}
}
}
}
},
"400": {
"description": "Missing parameter!"
},
"401": {
"description": "Authentication Failure"
}
}
}
},
"/api/exec/runtrigger": {
"post": {
"summary": "API command that executes trigger from CRM",
"description": "This command is responsible for executing Triggers that were set-up in CRM. We have to specify ID of the trigger and related object ID for the execution.",
"tags": [
"Exec - Advanced commands"
],
"operationId": "trigger",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"triggerId": {
"type": "integer",
"example": 50001,
"description": "ID of the trigger"
},
"objectId": {
"type": "integer",
"example": 11,
"description": "ID of the object related to this execution of trigger"
}
},
"required": [
"triggerId",
"objectId"
]
}
}
}
},
"responses": {
"200": {
"description": "Success - Trigger has been requested to execute. Result 1 - Trigger executed, 0 - Trigger could't be executed",
"content": {
"application/json": {
"examples": {
"Default": {
"value": "{\n \"results\": {\n \"result\": 1\n },\n \"success\": true\n}"
}
}
}
}
},
"401": {
"description": "Authentication Failure"
}
}
}
},
"/api/exec/report": {
"post": {
"summary": "API command that creates report from selected CRM page",
"description": "This command is responsible for creating report from selected CRM page. We have to specify ID of that page and optional criteria for filtering. As a result, we get list of IDs of elements from that page.",
"tags": [
"Exec - Advanced commands"
],
"operationId": "report",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"reportId": {
"type": "integer",
"example": 5000012,
"description": "ID of the CRM page"
},
"criteria": {
"type": "array",
"description": "List of filters IDs. Filters are configured in CRM",
"items": {
"type": "string",
"description": "IDs of filters - comma separated",
"example": "1923,2361"
}
}
},
"required": [
"reportId"
]
}
}
}
},
"responses": {
"200": {
"description": "Success - Returns IDs.",
"content": {
"application/json": {
"examples": {
"Default": {
"value": "{\n \"results\": {\n \"ids\": [\n 2000,\n 2001,\n 2002,\n 2003,\n 2004,\n 2005,\n 2005\n ]\n },\n \"success\": true\n}"
}
}
}
}
},
"401": {
"description": "Authentication Failure"
}
}
}
},
"/api/exec/read": {
"post": {
"summary": "API command that reads objects from based on filters.",
"description": "API command that reads objects from CRM. We have to specify which class will be searched and then we can specify filters for searching. Objects that meet the criteria will be returned. This command requires appropriate permissions set in the connector settings.",
"tags": [
"Exec - Advanced commands"
],
"operationId": "read",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"className": {
"type": "string",
"example": "files",
"description": "Name of the CRM class"
},
"criteriaFields": {
"type": "object",
"description": "Pairs of criteria for searching. Only objects meeting the criteria will be returned.",
"properties": {
"id": {
"type": "string",
"example": 5
},
"fieldName": {
"type": "string",
"example": "fieldValue"
}
}
}
},
"required": [
"classId"
]
}
}
}
},
"responses": {
"200": {
"description": "Success - Returns IDs.",
"content": {
"application/json": {
"examples": {
"Default": {
"value": "{\n \"results\": [\n {\n \"id\":5,\n \"comment\": \"\",\n \"product_categories\": \"0\",\n \"full_name\": \"\",\n \"tax_identification_number\": \"\",\n \"promote_on_www\": \"0\",\n \"payment_method\": \"9\",\n \"source_of_customer_acquisition\": \"0\",\n \"importance_of_the_company\": \"1\",\n \"phase\": \"6\",\n \"discounts\": \"0\",\n \"form_of_activity\": \"1\",\n \"contractor_symbol\": \"SE4VA\",\n \"link_to_the_catalogue\": \"\",\n \"documents\": \"\",\n \"number_of_employees\": \"0\",\n \"turnover_2005\": \"0\",\n \"end_of_subscription\": \"2021-02-04 00:00:00\",\n \"crm_tree\": \"\",\n \"nextField\":\"nextValue\"\n }\n ],\n \"success\": true\n}"
}
}
}
}
},
"401": {
"description": "Authentication Failure"
}
}
}
},
"/api/exec/response": {
"post": {
"summary": "API command that sends response to action activated by trigger.",
"description": "API command that sends response to action activated by trigger. Used, for example in ERP integrators. ",
"tags": [
"Exec - Advanced commands"
],
"operationId": "response",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"response": {
"type": "string",
"example": "New ID: 3",
"description": "Content of the response"
}
},
"required": [
"response"
]
}
}
}
},
"responses": {
"200": {
"description": "Success - Response has been sent. result 1 - success, 0 - error",
"content": {
"application/json": {
"examples": {
"Default": {
"value": "{\n \"results\": {\n \"result\": \"1\"\n },\n \"success\": true\n}"
}
}
}
}
},
"401": {
"description": "Authentication Failure"
}
}
}
}
}
}