Introduction

Premise and basic concepts

The following documentation is intended to illustrate the functionalities related to the API REST exposed by the system.
In order to easily use the API REST, it is necessary to have some basic notions about core concepts and objects.
If you already have these competencies, you can skip this chapter and proceed further.

Web API Controllers

The API REST communication functionalities are implemented through special Web API Controllers.

Each Controller contains a set of features called Actions.

Each Action constitutes an end-point of the system, and can be invoked via HTTP via a URL unique and a specific set of HTTP verbs

The section on Routing illustrates the ways in which it is possible to invoke the Actions of Controller

Business Objects

The objects that represent the entities of the system (companies, contacts, leads, opportunities, activities, etc.) are called "Business Objects" (indicated for brevity with the acronym "BO")

The complete list of Business Objects is formalized in the appropriate enum "BusinessObjectType"

Each element of the enum BusinessObjectType matches a specific Business Object

Business Objects Controllers

Business Objects are the heart of the system's business logic, and expose their functions through special API REST end-points called "Web API controllers "

In order to interact with a Business Object, it is therefore necessary to identify the corresponding end-point. The Controllers section contains the list of all available controllers, indicating the type for each one.

The Controllers related to a specific Business Object are marked with the icon

The section on Routing illustrates the ways in which it is possible to invoke the Actions of the Controller

DTO (Data Transfer Objects)

Business Objects are very complex entities, rich in information and functions.

It would be impractical to directly manipulate them via the Actions of Controllers (for the obvious reason that objects and services are programmatic entities with very different usage semantics)

To facilitate their usage (and in particular, to simplify their JSON representation), for each Business Object there is a correspondent DTO, a "Data Transfer Object".
The purpose of a DTO is to represent, serialize and transport the data of a Business Object.

The Actions of the Controllers receive (parameters) and returns JSON data of the DTO objects

As previously indicated, the complete list of Business Objects is formalized in the appropriate enum "BusinessObjectType"

Each element of the enum BusinessObjectType matches the DTO of a specific Business Object

The JSON⇄DTO⇄BO "transformation chain"

As previously said, the BOs are manipulated via JSON through the "mediation" of the DTOs.
The following diagrams illustrate (in a very simplified way) the pipeline "connecting" the invoking client (on the left) to the database of the backend (on the right) through the JSON⇄DTO⇄BO "transformation chain"

Serialization (JSON←DTO←BO)

Deserialization (JSON→DTO→BO)


Authentication

JWT Token

In order to invoke the REST API, it is necessary to obtain an authentication token via the appropriate service /Auth/Login, to which a JSON package must be sent in the following form:


{
    "grant_type": "password",
    "username": "admin@admin.com",
    "password": "admin"
}

The service will return a JWT token (access_token property) to be used in all subsequent calls using Bearer Authentication


{
    "access_token": "my_jwt_token",
    "expires_in": 1200,
    "refresh_token": "5fc87399-413d-44de-8976-dc3d15e4b0bc",
    "result": 0,
    "token_type": "bearer"
}

The communication flow is as follows:

Bearer Authentication

Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens.
The name “Bearer authentication” can be understood as “give access to the bearer of this token.”
The bearer token is a cryptic string or hash, usually generated by the server in response to a login request.
The client must send this token in the Authorization header when making requests to protected endpoints/resources:

The Bearer authentication scheme was originally created as part of OAuth 2.0 in RFC 6750, but is sometimes also used on its own. Similarly to Basic authentication, Bearer authentication should only be used over HTTPS (SSL).

A typical HTTP GET invocation of a protected REST API endpoint/resource is similiar to this:

GET https://myhost.com/api/latest/Company/Get/1 HTTP/1.1
Host: myhost.com
Connection: keep-alive
Accept: application/json, text/plain, */*
Origin: null
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
Authorization: Bearer my_jwt_token
Accept-Encoding: gzip, deflate, br
Accept-Language: en,en-US;q=0.9,it-IT;q=0.8,it;q=0.7

API Key

API keys are a simple encrypted string that can be used when calling certain API for authentication.

To generate an API key token, go to SETUP => USERS => USER.
Open the TAB "Web API Keys" and click the button Add Web API Key to generate a new token.

Each token can have a specific security to limit the actions on the main object.

For example, to allow new leads creation only, we recommend disabling all features except the flag "create" on the lead line.

Pass the API key into a REST API call as a header or query parameter with the following format. Replace API_KEY with your API key,

apikey=API_KEY

For example, to pass an API key for a Lead's new Instance request:

GET http://api.crmincloud.it/api/latest/lead/GetNewInstance?apikey=API_KEY

Identification of the calling application

Some of the REST API functions can only be used if (in addition to proper user authentication) a declaration of the calling application is also performed.

The name of the calling application is sent to the server via a special HTTP header:

Crm-ApplicationName

If you have this "Application Name", use it in all calls to the server.

GET https://myhost.com/api/latest/Company/Get/1 HTTP/1.1
Host: myhost.com
Connection: keep-alive
Accept: application/json, text/plain, */*
Origin: null
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
Authorization: Bearer my_jwt_token
Accept-Encoding: gzip, deflate, br
Accept-Language: en,en-US;q=0.9,it-IT;q=0.8,it;q=0.7
Crm-ApplicationName: MyApplication


Controllers

The following list contains all the available Web API controllers


Errors

The controllers actions will generate errors for the following cases:

  • Status 400: Badly formed queries e.g. filter parameters that are not correctly encoded
  • Status 401: Authentication failures e.g. unrecognised keys
  • Status 403: Forbidden. The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort.
  • Status 404: Not found. Unknown resources e.g. data which is not public
  • Status 409: Conflict. Indicates that the request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates.
  • Status 500: Server errors e.g. where something has gone

Errors are formatted in JSON


Versioning

It is possible to select the web services version using the {version} token

/api/{version}/{controller}/{details}/{action}/{id}?{querystring}

The token {version} can contain both "exact" values ​​and the special "latest" alias, which identifies the most recent version among those existing in the system.

In general, the use of the special "latest" alias is strongly recommended.

If you want to be particularly "conservative" and adherent to a specific version, specify the name explicitly (eg "v1").


Routing

The system use the following routing syntax, consisting of a sequence of "path-tokens" (the request parameters):

{schema}://{host}/api/{version}/{controller}/{details}/{action}/{id}?{querystring}

The tokens identify respectively:

  • {host} -> HOST of the URL
  • {version} -> version of web services
  • {controller} -> name of the service (controller) you want to invoke
  • {details} -> optional detail level of the returned JSON (if applicable)
  • {action} -> optional action (method) invoked in the controller
  • {id} -> single optional argument (parameter) of the method in the controller, if it so requires
  • {querystring} -> additional parameters and possible "modifiers" of the processing and serialization process


Options

The REST API functions implemented in CRM in Cloud include a vast set of options that allow you to adapt the structure and shape of JSON packages according to your needs and preferences.

Unlike the parameters, which are specified in the URL route (through tokens and queriestring), the options must instead be passed through the HTTP headers of the request.

As from RFC6648 all the options passed through HTTP headers have in their name the custom prefix Crm-.

If a certain option is not specified, the system will use the default value specific to the {version} indicated in the URL.

The available options are listed below, and the related accepted values ​​are briefly described.

Global formatting options

The global formatting options allow a high level control on the behavior of the serializer/deserializer, determining the general characteristics of the returned/accepted JSON.

  • Crm-TypeNameHandling

    • None: the JSON does not contain any type name for the objects represented
    • Objects: the JSON contains the type names for the represented objects
    • RootOnly: the JSON contains the type name of the represented object at root level
  • Crm-NullValueHandling

    • Ignore: do not serialize the properties with NULL value
    • Includes: also serialize the properties with NULL value
  • Crm-NamingStrategy

    • AsIs: the properties are serialized with the same name as the source code
    • UpperCamelCase: the naming convention "Pascal Case" is applied
    • LowerCamelCase: the naming convention "Camel Case" is applied
    • SnakeCase: the naming convention "Snake Case" is applied
    • KebabCase: the naming convention "Kebab Case" is applied
  • Crm-Formatting

    • None: the JSON is not indented, and results on a single line of text
    • Indented: The JSON is indented (tabbing = 1)
  • Crm-WebApiRules is a comma-separated list of rules to activate. The currently supported values are:

    • LeadMustBeUniqueByEmail=VALUE: When VALUE is true, the created Lead must be unique by email address. When VALUE is false (or the rule is not specified) the rule is ignored


Polymorphic Serialization

As already illustrated into the Options section, the REST API functions implemented in CRM in Cloud include a vast set of functions that allow you to adapt the structure and shape of JSON packages according to your needs and preferences.

See the Options section to get all the details related to their use

Polymorphic serialization options

The polymorphic serialization options act at a highly granular level, allowing a more "surgical" customization than is possible with the formatting options.

Click on an option in the table below to see how to use it (the "Crm-" prefix is omitted for the sake of brevity)

Note on enums: enum-typed properties are covered in a specific section

Option nameSupported stylesApplies to
AnagraphicCompanyTypeIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
AnagraphicIndustryIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
AnagraphicSourceIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
BusinessRolesStyle
  • AdaptiveCsv
  • AdaptiveExternalReference
  • AdaptiveName
  • AdaptiveStringOnlyName
  • Csv
  • CsvOfIds
  • CsvOfNames
  • Id
CommercialZoneStyle
  • AdaptiveCode
  • AdaptiveDescription
  • AdaptiveExternalReference
  • AdaptiveStringOnlyCode
  • AdaptiveStringOnlyDescription
  • Id
CompanyCategoriesStyle
  • AdaptiveCsv
  • AdaptiveExternalReference
  • AdaptiveName
  • AdaptiveStringOnlyName
  • CsvOfIds
  • CsvOfNames
  • Id
CompanyIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
ContactCategoriesStyle
  • AdaptiveCsv
  • AdaptiveExternalReference
  • AdaptiveName
  • AdaptiveStringOnlyName
  • CsvOfIds
  • CsvOfNames
  • Id
ContactIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
EmailStyle
  • Compact
  • Csv
  • FlattenedExpansion
  • Full
  • Tiny
  • ValueOnly
FreeFieldsStyle
  • AsValueOnlyParentProperties
  • Full
GeoLocalizationStyle
  • Full
  • GeoJSON
ImplicitConsentStyle
  • Compact
  • Full
LeadCategoriesStyle
  • AdaptiveCsv
  • AdaptiveExternalReference
  • AdaptiveName
  • AdaptiveStringOnlyName
  • CsvOfIds
  • CsvOfNames
  • Id
LeadIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
LeadPriorityIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
LeadProductInterestIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
LeadRatingIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
LeadStatusIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
OpportunityCategoryStyle
  • AdaptiveDescription
  • AdaptiveExternalReference
  • AdaptiveStringOnlyDescription
  • FlattenedExpansion
  • Id
OpportunityIdStyle
  • AdaptiveDescription
  • AdaptiveStringOnlyDescription
  • Description
  • FlattenedExpansion
  • Id
OpportunityPhaseStyle
  • AdaptiveDescription
  • AdaptiveExternalReference
  • AdaptiveStringOnlyDescription
  • FlattenedExpansion
  • Id
OwnerIdStyle
  • AdaptiveExternalReference
  • AdaptiveStringOnlyUserAccount
  • AdaptiveUserAccount
  • FlattenedExpansion
  • Id
  • StrictEmail
PhoneStyle
  • Compact
  • Csv
  • FlattenedExpansion
  • Full
  • Tiny
  • ValueOnly
PrivacySettingsStyle
  • Compact
  • Full
PrivacyTypeManagementIdStyle
  • AdaptiveCode
  • AdaptiveDescription
  • AdaptiveStringOnlyCode
  • AdaptiveStringOnlyDescription
  • AdaptiveStringOnlyTitle
  • AdaptiveTitle
  • Id
SalesPersonsStyle
  • AdaptiveCsv
  • AdaptiveExternalReference
  • AdaptiveStringOnlyUserAccount
  • AdaptiveUserAccount
  • Csv
  • CsvOfIds
  • CsvOfNames
  • Id
TagsStyle
  • AdaptiveCsv
  • AdaptiveExternalReference
  • AdaptiveName
  • AdaptiveStringOnlyName
  • Csv
  • CsvOfIds
  • CsvOfNames
  • Id


Polymorphic Enums

Many DTO properties are enum-typed.

In order to simplify their polymorphic serialization, a unified set of (optional) styles is available for each property:

  • AdaptiveString: serialize the enum as string.
  • AdaptiveInteger: serialize the enum as the equivalent numeric value

For more details about the polymorphic serialization of enums, please refer to the appropriate documentation


External References

Many Business Objects (and related DTO) of CRM in Cloud can be associated with an "external reference", ie the corresponding entity of another third party system.

The "external references" are therefore logical relationships between a native entity of CRM in Cloud and the corresponding entity of an external system.
They are to be seen as purely descriptive meta-data, and exist only for the benefit of the mappings made by the synchronization systems.
Typically "external references" are not involved in any internal CRM in Cloud process.

Example: companies and accounts

As an example, assume that CRM in Cloud is synchronized (via plugins or other mechanisms based on the REST API) with other N systems.
Each of these N systems will be discriminated by CRM in Cloud through an identifier specified in the Crm-ApplicationName parameter.
Each account (or any other Business Object) of CRM in Cloud may therefore have a "counterpart" for each of the N external systems.
The CompanyDTO.ownerId property represents the owner (an account of CRM in Cloud) of the company.

The following diagram illustrates the relationships described:

Polymorphic serialization of properties representing external references

The property CompanyDTO.ownerId can be serialized through various styles (see specific section on the polymorphic serialization of the "ownerId" field).

One of these serialization styles is AdaptiveExternalReference.

Using the style AdaptiveExternalReference, each "owner" (account) is represented by a string containing the username of the corresponding account in the calling client's database.
As previously mentioned, the correct value to return is determined using what is specified in Crm-ApplicationName.

GET

When making a GET request for a DTO, the property (supporting the AdaptiveExternalReference style) for which a polymorphic serialization option is specified, takes the following value:

  • the string in the "External Reference Value" field (see previous diagram), if it is not null and not empty
  • The name/code of the Business Object of CRM in Cloud in case "External Reference Value" (see previous diagram) is empty or null (or in the case no associations are present)

PUT / POST

When executing a PUT/POST request of a DTO, the property (supporting the AdaptiveExternalReference style) for which a polymorphic serialization option is specified, treats the received values ​​as follows:

  • If a string value is sent, it is used to resolve (in the "External Reference Value" field of the previous diagram) the relative integer value of the ID/PK of the "External Reference Table" record (associated with the table of the Business Object correspondent). If there is no record with the given string, an error is returned.
  • If an integer is sent, it will be considered as the numeric ID previously mentioned (ID/PK of the "External References Table" of the previous diagram).


Emulation

As already illustrated into the Options section, the REST API functions implemented in CRM in Cloud include a vast set of functions that allow you to adapt the structure and shape of JSON packages according to your needs and preferences.

See the Options section to get all the details related to their use

Emulation options

If it is necessary to emulate the behavior of the previous version of the REST API (Tustena 17), it is possible (although not recommended) to use the following option.

  • Crm-EmulateWebApiVersion
    • Not specified: No emulation is activated
    • v9: emulates the behavior of the previous generation REST API (Tustena 17)


OData

The REST APIs are internally based on the Microsoft WebAPI technology, and are largely compliant with the REST specifications, OData v3 and OData v4.

OData compliancy

There are several research methods based on OData.
The current implementation supports a significant portion of the OData v3 URL conventions and some OData v4 URL conventions and functions

OData criteria

In all OData-based search URLs, you can specify the following set of criteria:

  • top
  • skip
  • orderby
  • filter
  • select

ID Search via OData

The following URL returns the IDs of the BOs found based on the specified criteria.

GET: /api/{version}/{controller}/SearchIds ?

  • $filter = filter &
  • $orderby = order criteria &
  • $skip = items to skip &
  • $top = max items to return

If invoked via POST, this URL allows you to specify the OData criteria by means of a JSON instead of using URL parameters (useful for avoiding data escaping).

Example:



    "filter": "id eq 1 or (id gt 3 and id lt 10)",
    "orderby": "id asc",
    "top": "100",
    "skip": "0",
    "select": "id,companyName,billed"


Search for BO/DTO via OData

The following URL returns the DTOs in JSON format of the BOs found.

GET: /api/{version}/{controller}/Search ?

  • $filter = filter &
  • $orderby = order criteria &
  • $skip = items to skip &
  • $top = max items to return

If invoked via POST, this URL allows you to specify the OData criteria by means of a JSON instead of using URL parameters (useful for avoiding data escaping).

Example:



    "filter": "id eq 1 or (id gt 3 and id lt 10)",
    "orderby": "id asc",
    "top": "100",
    "skip": "0",
    "select": "id,companyName,billed"


OData criteria diagnostics

The following URL allows you to test the OData parser, obtaining a JSON representing the OData parameter values ​​passed in the querystring or POST.

GET: /api/{version}/{controller}/GetODataQueryParameters

$filter - logical operators

The expressions of the $filter parameter support the following logical operators:

  • eq -> Equal
  • ne -> Not Equal
  • gt -> Greater Than
  • ge -> Greater Than or Equal
  • lt -> Less Than
  • le -> Less Than or Equal
  • and -> Logical And
  • or -> Logical Or

For more details refer to the related OData v3 specifications

$filter - arithmetic operators

The expressions of the $filterparameter support the following arithmetic operators:

  • add -> sum
  • sub -> subtraction
  • mul -> multiplication
  • div -> division
  • mod -> module

For more details refer to the related OData v3 specifications

Examples

  • add -> /api/latest/Company/Search?$filter=Billed+add+5+eq+15
  • sub -> /api/latest/Company/Search?$filter=Billed+sub+5+eq+25
  • mul -> /api/latest/Company/Search?$filter=Billed+mul+5+eq+100
  • div -> /api/latest/Company/Search?$filter=Billed+div+5+eq+5
  • mod -> /api/latest/Company/Search?$filter=Billed+mod+5+eq+0

$filter - canonical functions

The expressions of the $filter parameter support the following canonical functions:

  • startswith
  • endswith
  • length
  • indexof
  • replace
  • substring
  • substringof
  • tolower
  • toupper
  • trim
  • concat

For more details refer to the related OData v3 specifications

Examples

  • startswith: /api/latest/Company/Search?$filter=startswith(companyName,'ACME')+eq+10
  • endswith: /api/latest/Company/Search?$filter=endswith(companyName,'srl')+eq+10
  • contains: /api/latest/Company/Search?$filter=contains(companyName,'srl')
  • length: /api/latest/Company/Search?$filter=length(companyName)+eq+10
  • indexof: /api/latest/Company/Search?$filter=indexof(companyName,'S')+eq+7
  • replace: /api/latest/Company/Search?$filter= replace(companyName,'srl','s.r.l.')+eq+'acme+s.r.l.'&$top=10&$skip=0
  • substring (1 argument): /api/latest/Company/Search?$filter=substring(companyName,1)+eq+'do'
  • substring (2 arguments): /api/latest/Company/Search?$filter=substring(companyName,1,2)+eq+'do'
  • substringof: /api/latest/Company/Search?$filter=substringof('srl',companyName)
  • tolower: /api/latest/Company/Search?$filter=tolower(companyName)+eq+'my+company+name'
  • toupper: /api/latest/Company/Search?$filter=toupper(companyName)+eq+'MY+COMPANY'
  • trim: /api/latest/Company/Search?$filter=trim(companyName,1)+eq+'my+company'
  • concat: /api/latest/Company/Search?$filter=concat(companyName,Code)+eq+'My+companyABC'

Related items

The WebApi controllers are able to detect OData parameters if they are specified in the URLs of requests for related items/children.

The current implementation supports:

  • Top
  • Skip
  • OrderBy
  • Filter
  • Select

Here are some examples of applying OData to web services

Related items - top

Template URL -> GET: /api/{version}/{controller}/{id}/{SubItems}?$top=10

Esempio -> GET: /api/{version}/Company/1/Contacts?$top=10

Related items - skip

Template URL -> GET: /api/{version}/{controller}/{id}/{SubItems}?$skip=10

Esempio -> GET: /api/{version}/Company/1/Contacts?$skip=10

Related items - pagination

By combining $top and $skip it is possible to paginate the resultset

Template URL -> GET: /api/{version}/{controller}/{id}/{SubItems}?$top=10&$skip=50

Esempio -> GET: /api/{version}/Company/1/Contacts?$top=10&$skip=50

Related items - orderby

Template URL -> GET: /api/{version}/{controller}/{id}/{SubItems}?$orderby=criteria

Esempio -> GET: /api/{version}/Company/1/Contacts?$orderby=Id%20desc

Related items - filter

Template URL -> GET: /api/{version}/{controller}/{id}/{SubItems}?$filter=criteria

Esempio -> GET: /api/{version}/Company/1/Contacts?$filter=CompanyId%20eq%201

Related items - select

Template URL -> GET: /api/{version}/{controller}/{id}/{SubItems}?$select=csv

Esempio -> GET: /api/{version}/Company/1/Contacts?$select=id,companyName

Related items - other examples

GET:
/api/{version}/Company/1/Activities?$filter=Subject%20eq'Appuntamento'&$top=10&$skip=5&$orderby=Description%20desc

GET:
/api/{version}/Company/1/Contacts?$filter=Name%20eq%20'Damiano'

Primitive data types supported by OData

The OData parser supports the following primitive data types:

  • integer numbers
  • non integers
  • strings
  • bool
  • date/time (see paragraph below)

Specifically, the supported MS.NET types are:

  • System.Byte
  • System.SByte
  • System.UInt16
  • System.Int16
  • System.UInt32
  • System.Int32
  • System.Int64
  • System.UInt64
  • System.Single
  • System.Double
  • System.Decimal
  • System.String
  • System.DateTime (vedi paragrafo a seguire)

OData and the enum-typed properties

The OData parser supports several enum types, but remember that they must be expressed via the equivalent string value, not the native numeric value.

Examples:

GET:
/api/{version}/Company/1/Opportunities?$filter=status eq 'Suspended'

GET:
/api/{version}/Opportunity/SearchIds?$filter=status eq 'Suspended'

OData and the date/time properties

The OData parser supports date/time fields (System.DateTime).

It is possible to express a date/time in different ways (both in OData v3 and OData v4 format).

Here are some correct examples, and some incorrect examples.

Correct examples in OData v3 format:

  • $filter=myDateTimeField eq datetime'2015-07-28T10:23:00Z'
  • $filter=myDateTimeField eq datetime'2015-07-28T10:23:00.1Z'
  • $filter=myDateTimeField gt datetime'2015-07-28T10:23:00.12Z'
  • $filter=myDateTimeField lt datetime'2015-07-28T10:23:00.123Z'
  • $filter=myDateTimeField eq datetime'2015-07-28T10:23:00.1234Z'
  • $filter=myDateTimeField gt datetime'2015-07-28T10:23:00.12345Z'
  • $filter=myDateTimeField eq datetime'2015-07-28T10:23:00.123456Z'
  • $filter=myDateTimeField lt datetime'2015-07-28T10:23:00.1234567Z'

Correct examples in OData v4 format:

  • $filter=myDateTimeField eq 2015-07-28T10:23:00Z
  • $filter=myDateTimeField eq 2015-07-28T10:23:00.1Z
  • $filter=myDateTimeField gt 2015-07-28T10:23:00.12Z
  • $filter=myDateTimeField lt 2015-07-28T10:23:00.123Z
  • $filter=myDateTimeField eq 2015-07-28T10:23:00.1234Z
  • $filter=myDateTimeField gt 2015-07-28T10:23:00.12345Z
  • $filter=myDateTimeField eq 2015-07-28T10:23:00.123456Z
  • $filter=myDateTimeField lt 2015-07-28T10:23:00.1234567Z

Wrong examples:

  • $filter=myDateTimeField eq '2015-07-28T10:23:00.1Z'
  • $filter=myDateTimeField eq cast(2015-07-28T10:23:00Z)

Searchable and not searchable properties

Not all DTO properties are searchable via OData.

To check if a particular property is searchable, visit the specific documentation reference and check what is indicated under "Is Searchable".

NameValue
...
Is Searchable YES
...

Examples:

IMPORTANT NOTE

THE RESULT OF COMPARISONS BETWEEN STRINGS ARE DETERMINED BY THE COALESCE SETTINGS AT THE DATABASE LEVEL OF SQL SERVER.

IT FOLLOWS THAT, EVEN IF SOME FUNCTIONS OF ODATA ARE IMPLEMENTED, THEIR BEHAVIOR IS INFLUENCED BY SUCH SETTINGS AND MAY GENERATE UNINTENDED RESULTS.

IT IS NECESSARY THEREFORE TO CONSIDER THIS ASPECT WHEN EXECUTING OPERATIONS IN WHICH THE CASE-SENSITIVITY IS RELEVANT.


Free Fields

Many Business Objects (and related DTO) are customizable, and it is therefore possible to define for each a different set of custom fields.
These custom fields are called Free Fields.

Free Fields are user-definable custom fields, and can contain data of various kinds.

Each Free Field has a specific data type (selected during configuration), and on the basis of this type, the field data follow certain validation rules.

Free Field and polymorphism

As with many other fields, Free Fields also implement polymorphic serialization capabilities, and it is therefore possible to select multiple serialization/deserialization styles.
For more details, refer to the specific descriptive paragraph on the serialization of the Free Fields

Free Field and OData

Free Fields can be used in OData searches as field selectors ($select criterion).
In order to be able to discriminate them from the other standard fields of the Business Object, it is necessary to specify the prefix "FF_"

Example:

GET: /api/{version}/Company/Search?$select=id,companyName,FF_MyCustomFreeField1,FF_AnotherFreeField

Business Objects supporting Free Fields

The list below contains all the controllers related to Business Objects that support the definition and usage of Free Fields.


Glossary

Glossary of terms

Below is a list of the terms most used in these documents

  • Business Object -> The objects representing system entities (companies, contacts, leads, opportunities, activities, etc.) are called "Business Objects" (indicated for brevity with the acronym "BO"). For more details refer to the introductory section

  • BO -> Acronym used to refer to "Business Objects". For more details refer to the introductory section

  • DTO -> Acronym of Data Transfer Objects. For each Business Object there is a corresponding DTO. The purpose of DTO is to represent, serialize and transport the data of a Business Object. For more details refer to the introductory section

  • Controller -> Portion of the URL of routing of an end-point API REST. See also "routing". For more details refer to the introductory section

  • Action -> RPC functionality of a controller, invocable via the routing URL of an endpoint API REST. See also "routing". For more details refer to the introductory section

  • Polymorphic Serialization -> The polymorphic serialization options act at a highly granular level, allowing a more "surgical" customization than is possible with the formatting options. Some properties of DTOs are marked as "polymorphic". For these properties it is possible to specify a serialization style, which changes its JSON form and structure. For more details, refer to the options section

  • Logical Primitive -> Some properties of DTOs are marked as "Logical Primitive". The following data types are considered "Logical Primitive":

    • Strings
    • Numbers (both integers and decimals)
    • Dates (and time intervals)
    • Boolean
    • Enums (both in integer an string format)
  • Business Object Type -> the complete list of Business Objects is formalized in the appropriate enum "BusinessObjectType". For more details refer to the introductory section

  • Foreign Key -> Foreign key, or "foreign key". Some properties of DTOs are marked as "Foreign key". These properties are used to contain the association value (typically a numeric ID) between an object/DTO/BO "master" and a related object "detail".

  • List -> Some properties of DTOs are marked as "Foreign key". These properties are used to contain the association value (typically a numeric ID) between an object/DTO/BO "master" and a related object "detail". Some "Foreign keys" may contain a link to a list of objects/DTO/BO

  • Virtual Property / Aliased Property -> An alias for a physical property of a DTO/BO. I.e., the property "NormalizedEmail" of CompanyDTO is serialized as "emails"