Odata web service (OData 4)

Advanced

Depending on the request type, OData 4 protocol can return different data. Learn more about the request and response structure below.

// Request string.
method Creatio_application_address/0/odata/objects_collection(object_id)/object_field?$parameters

// Request headers.
Accept: application/json
Content-Type: application/json; charset=utf-8; IEEE754Compatible=true
ForceUseSession: true
BPMCSRF: authentication_cookie_value

// Request body (for POST and PATCH requests).
{
    "field1": "value1",
    "field2": "value2",
    ...
}

// The status code.
Status: code

// Response body (available in GET and post requests).
{
    "@odata.context": "http://Creatio_application_address/0/odata/$metadata#data_resource",
    "value": [
    {
        "object1 field1": "object1 field_value1",
        "object1 field2": "object1 field_value2",
        ...
    },
    {
        "object2 field1": "object2 field_value1",
        "object2 field2": "object2 field_value2",
        ...
    },
    ...
    ]
}

Request string 

method required

Creatio supports the following request methods:

  • GET – retrieve data
  • POST – add data
  • PATCH – modify data
  • DELETE – delete data
Creatio_application_address required

Creatio application URL.

odata required

OData 4 protocol's web service URL. Unmodifiable part of the request.

objects_collection required

Name of the database table (the name of the object collection). Run the authentication and execute one of the requests to retrieve the list of database tables.

// The result will be received in JSON.
GET Creatio_application_address/0/odata/

// Request headers.
ForceUseSession: true
BPMCSRF: authentication_cookie_value

// The result will be received in XML.
GET Creatio_application_address/0/odata/$metadata

// Request headers.
ForceUseSession: true
BPMCSRF: authentication_cookie_value

// The result will be received from the [SysSchema] database table in JSON.
GET Creatio_application_address/0/odata/SysSchema?$filter=ManagerName eq 'EntitySchemaManager'

// Request headers.
ForceUseSession: true
BPMCSRF: authentication_cookie_value

object_id optional

Identifier of the database table record string (the identifier of the collection object instance).

object_field optional

Database table record field (the field of the collection object instance).

parameters optional

Optional OData 4 parameters you can use in the GET Creatio request string. Use the ? Operator to specify the parameters. Add the parameter name after the $ operator. Use the & operator to use two or more parameters.

Available parameters
$value   The field value.
$count $count=true The number of elements in the selection.
$skip $skip=n The first n elements that must be excluded from the selection.
$top $top=n The first n elements that must be included in the selection.
$select $select=field1,field2,... A set of fields that must be included in the selection.
$orderby $orderby=field asc or $orderby=field desc How to sort the field values in the selection.
$expand $expand=field1,field2,... Extension of the connected fields.
$filter $filter=field template 'field_value' How to filter the fields in the selection.

Request headers 

Accept application/json required

Data type to expect in the server response. Optional for GET requests.

Content-Type application/json; charset=utf-8; IEEE754Compatible=true required

Encoding and type of the resource passed in the request body. Optional for GET requests.

ForceUseSession true required

ForceUseSession header forces the use of an existing session.

BPMCSRF authentication_cookie_value required

Authentication cookie.

Request body 

field1, field2, ... required

The field names passed in the request body.

value1, value2, ... required

Values of the field1, field2, … fields passed in the request body.

HTTP status code 

code

Response status code.

Available status codes
200 OK A request that does not create a resource was completed successfully, and the resource's value does not equal 0. In this case, the response body should contain the value of the resource specified in the request URL. The information in the response depends on the request method:

GET – the resource was found and passed in the response body.

POST – the resource with the description of server actions caused by the request was passed in the response body.
201 Created A request that creates a resource successfully. The response body should contain the created resource. Used for POST requests that create a collection, create a multimedia object (e. g., a photo), or call an action through import.
202 Accepted Data request processing has started but has not finished yet. There is no guarantee that the request will be completed successfully (asynchronous request processing).
204 No content The request was processed successfully, but there is no need to return any data. The value of the requested resource is 0. The response will pass only the headers, the response body should be empty.
3xx Redirection Redirection means the client must take further actions to execute the request. The response should contain the Location header with the URL that can be used to retrieve the result. The response can also contain the Retry-After header that displays time, in seconds. The time specifies how long the client can wait before executing another request to the resource in the Location header.
304 Not modified The client executes a GET request with the If-None-Match header, and the content remains unchanged. The response should not contain any other headers.
403 Forbidden The request is correct, but the server refused to authorize it. This means the client lacks permissions to work with the resource. This may be caused by an invalid BPMCSRF cookie.
404 Not Found The server cannot find the resource specified in the URL. The response body may contain additional information.
405 Method Not Allowed The resource specified in the request URL does not support the specified request method. The response should contain the Allow header with the list of request methods the resource supports.
406 Not Acceptable The resource specified in the request URL does not have any current view that is acceptable for the client as per Accept, Accept-Charset, and Accept-Language request headers. The service does not provide a default view.
410 Gone The requested resource is no longer available. The resource had used the specified URL but was deleted and is no longer available.
412 Prediction Failed The client specified a request header condition the resource cannot process.
424 Failed Dependency The current request cannot be processed because the requested action depends on another action that could not be executed. The request has not been executed due to dependency failure.
501 Not Implemented The client is using a request method that is not implemented in OData 4 protocol and cannot be processed. The response body should contain the description of the unimplemented functionality.

Response body 

@odata.context

Information about the type of the returned data. Besides the data source path, the data_resource element can contain the $entity parameter. This parameter indicates that the response returned a single instance of the collection object. Available only for GET and POST requests.

value

Contains the object collection. Not available if the response contains a single collection object instance. Available only for GET requests.

[]

Object collection. Available only for GET requests.

{}

Collection object instances. Available only for GET and POST requests.

object1 field1, object1 field2, ..., object2 field1, object2 field2, ...

The names of the field1, field2, … fields in the object1, object2, … collection object instances. Available only for GET and POST requests.

object1 field_value1, object1 field_value2, ..., object2 field_value1, object2 field_value2, ...

The values of the field1, field2, … fields in the object1, object2, … collection object instances. Available only for GET and POST requests.

Resources
Creatio API documentation
OData 4 documentation (the description of request headers)
OData 4 documentation (the description of request parameters)