1CRM REST API

General

Welcome to 1CRM REST API documentation!

1CRM provides API (Application Programming Interface) for integrating with third-party applications such as accounting, ERP, e-commerce, self-service portals and others. With the 1CRM API, you can extract data in JSON format and develop new applications or integrate with your existing applications.

Connecting to 1CRM API

1CRM API calls are performed as HTTP requests to /1crm/api.php, with endpoint appended to it. Note that endpoints listed in this documentation do not include the base URI /1crm/api.php. For example, if the documentation says that to retrieve accounts list, one would send an HTTP GET request to /data/Account, actual request should be made to /1crm/api.php/data/Account.

Call parameters can be passed to API in various ways:

• in endpoint path. Such parameters are listed in this documentation with a colon prepended, for example /data/:model

• in query string, for example /data/Account?limit=10. Array and object parameters can be specified using square brackets:

  /data/Account?object[a][b]=1

  /data/Account?array[]=1&array[]=2

• in request body of POST and PUT requests, formatted as JSON object
• in HTTP headers. Note that actual header name is derived from param name by replacing undersores with hyphens. Header name is case insensitive. For example, CONTENT_TYPE header parameter should be passed in Content-Type HTTP header

Most API responses are formatted as JSON objects. A successful call result is indicated with 200 OK HTTP status code. Any response with status code different from 200 indicates an error, with detailed error information available in response body.

REST API is only available in Pro and Enterprise editions of 1CRM. Any attempt to make an API call to Startup or Startup+ edition will result in 403 Forbidden status code.

Note that the 1CRM API by default will reject any calls made over a non-SSL connection (http://). These connections may be enabled by an option in Admin - System Settings.

HTTP Method override

1CRM API uses different HTTP methods in API calls. Some client applications may only be able to perform HTTP requests using a limited number of HTTP methods. Also, 1CRM application server may be behind an HTTP proxy that does not accept HTTP methods other than GET and POST. To use 1CRM API in such situations, one can send POST requests instead of PUT, PATCH and DELETE, and add X-HTTP-Method-Override header.

POST /1crm/api.php/data/Account/123 HTTP/1.1
Host: portaldemo.1crmcloud.com
X-HTTP-Method-Override: DELETE

HTTP status codes

• 200 OK

  Requested action was executed. Response body may contain the requested data.

• 400 Bad request

  Returned if required parameters are missing, or parameters do not match expected data type. Response body contains additional information

• 401 Unauthorized

  Returned when client is not authenticated

• 403 Forbidden

  Returned when:

  • client is not authorized to access requested resource according to 1CRM ACLs
  • an API call is made to Startup or Startup+ edition

• 404 Not found

  Returned when requested endpoint does not exist, or when requested record does not exist.

• 500 Internal error

  Returned when an internal server error occurred. Response body may contain additional information

Endpoints may define additional response codes – see endpoint documentation for details.

Language

Some endpoints, especially metadata-related, may return data that is locale-dependent. To specify preferred language, use Accept-Language HTTP header. If that header is missing, default locale is used as configured in 1CRM settings. Note that even if Accept-Language header is present, formatting may be applied to some data according to authenticated user's locale preferences.

Legend

 Authentication required

Request methods

Required parameter

Parameter is located in endpoint path

Parameter is located in query string

Parameter is located in request body

Parameter is located in HTTP header

[1:] [:20] [1:100] numeric values limits, or limits for number of elements in arrays or string length

{String} Type constraint for values in an object, or valid values for Enum type

(123) default value

Extending 1CRM API

Client libraries

Although most programming lanuages provide tools for making HTTP requests, using a dedicated API client library can make a developer’s life easier, to ensure applications follow best practices when using the API, and to make any code using the API more robust.

Currently, 1CRM provides API client library for PHP. Client libraries for other programming languages are under development.

PHP

The 1CRM API Client library for PHP may be found here and its documentation is here.

Authentication

Vast majority of 1CRM API calls require authentication. Upon successful authentication, further API calls respect access rules defined by 1CRM administrator. This includes access to certain modules, access to records belonging to other users, permissions to edit and/or delete records, etc. Basically, any restrictions that apply to a user using 1CRM web UI, also apply to api calls when API client is authenticated on behalf of that user.

1CRM REST API supports 2 authentication mechanisms: Basic authentication and OAuth 2 authentication. OAuth 2 authentication should be preferred if possible.

Basic authentication

HTTP basic authentication is the simplest authentication method accepted by 1CRM API. Authentication is performed by adding Authorization header to all requests. No special authentication request is required.

To perform basic authentication, application should perform the following steps:

1. Concatenate user name and password with a colon: admin:password
2. Encode concatenated string as Base64 : YWRtaW46cGFzc3dvcmQ=
3. Add Authorization header to the HTTP request: Authorization: Basic YWRtaW46cGFzc3dvcmQ=

While Basic authentication is very simple to use, you should always prefer OAuth 2.0. Note that in 1CRM Implementation Guide, we highly recommend disabling Basic Authentication, and most administrators will do so

OAuth 2 authentication

1CRM API utilizes the industry-standard OAuth 2.0 protocol. You should always prefer OAuth to Basic authentication.

To use OAuth 2.0 authentication, you first need to obtain a token. After that, you should add Authorization header to HTTP requests when calling endpoints that require authentication : Authorization: Bearer access_token. Replace access_token with actual access token.

See OAuth 2.0 for details about obtaining access tokens.

Session authentication

Session authentication is an authentication method for embedded 1CRM applications. Authentication is performed by adding the Session ID from browser cookies to HTTP requests when calling endpoints that require authentication. The request would be automatically authenticated using the credentials from the current 1CRM session with all user's ACL rights.

Note that Session Authentication is disabled by default

Types

Bool

This type represents a boolean value. Strings yes, 1 and true are recognized as true, and no, 0 and false are recognized as false. When sending parameters of this type in request body, prefer using JSON values of true or false instead of strings.

Int

This type represents an integer value. Parameters of this type can have limits set for minumum and maximum accepted values

String

This type represents a generic string value. Parameters of this type can have limits set for minumum and maximum accepted string length and/or regular expression that the string should match

Enum

This type represents a string that can only take one of predefined values

Float

This type represents a floating point numeric value. Parameters of this type can have limits set for minumum and maximum accepted values

Array

This type represents an array of values. Parameters of this type can be either a generic array without a predefined element type, or a typed array that should have only values of specific type as array elements

Object

This type represents a data structure known in different programming languages as associative array, map, symbol table, or dictionary. Object keys are always strings. Parameters of this type can have schema to specify accepted keys and value types for those keys

Date

Inherits String

This type represents a date value. The value must conform to Y-m-d format as used by PHP date function

DateTime

Inherits String

This type represents a date/time value. The value must conform to Y-m-d H:i:s format as used by PHP date function. Use GMT timezone.

Filename

Inherits String

This type represents a file name. The value should not contain any path information.

OneOf

This is a polymorphic type that can be one of several predefined types.

WebhookFilter

Inherits Object

This type represents a webhook filter.

StringFilter

Inherits Object

This type represents a webhook filter by a string field.

filter can be one of the following:

• eq field value is equal to value
• not_eq field value is not equal to value
• prefix field value starts with value
• suffix field value ends with value
• like field value contains value
• not_like field value does not contain value
• empty field value is empty
• not_empty field value is not empty

NumberFilter

Inherits Object

This type represents a webhook filter by a numeric field.

filter can be one of the following:

• lt field value is less than value
• gt field value is greater than value
• lte field value is less than or equal to value
• gte field value is grater than or equal to value
• between field value is between value and value2, inclusive
• empty field value is not set
• not_empty field value is set
• eq field value is equal to value
• not_eq field value is not equal to value

DatetimeFilter

Inherits Object

This type represents a webhook filter by a date or datetime field.

filter can be one of the following:

• not_empty field value is not empty
• empty field value is empty
• before_date field value is before the date passed in value
• after_date field value is after the date passed in value
• on_date field value equals the date passed in value
• not_on_date field value does not equal the date passed in value
• yesterday field value is yesterday's date
• today field value is today's date
• tomorrow field value is tomorrow's date
• between_dates field value is between dates passed in value and value2, inclusive

You can also pass period_prev, period_current, or period_next in filter. In this case filed value will be checked against previous, current, or next period relative to current date. Period length is determined by value:

• day one day
• week calendar week
• month calendar month
• quarter calendar quarter
• year calendar year
• fiscal_quarter fiscal quarter
• fiscal_year fiscal year
• days_N N days

EnumFilter

Inherits Object

This type represents a webhook filter by a enum or multienum field.

filter can be one of the following:

• eq field value equals value; pass a string for enum field or an array of strings for multienum field
• not_eq field value not equals value; pass a string for enum field or an array of strings for multienum field
• any_of for enum fields, field value is contained in value array; for multienum fields, field value contains at least one element from array passed in value
• not_any_of for enum fields, field value is not contained in value array; for multienum fields, field value does not contain any of the elements from array passed in value
• all_of all elements passed in value array are contained in field value; applicable to multienum fields only
• empty field value is empty
• not_empty field value is not empty

BoolFilter

Inherits Object

This type represents a webhook filter by a boolean field.

WebhookWhen

Inherits Enum {changed, not_changed, changed_to, current_value, prev_value}

This type represents the type of change webhook filter reacts to.

• changed Field value was changed. Actual previous and new values are not important
• not_changed Field value was not changed.
• changed_to Field was changed to a value that matches the criteria defined by filter's operator
• current_value Field's current value matches the criteria defined by filter's operator, regardless of whether it was changed or not.
• prev_value Field was changed, and its previous value matches the criteria defined by filter's operator

TestComplex

Inherits Object

This type exists solely for testing purposes. Do not use

Authentication

Authorization request for contact

/auth/contact/authorize

See OAuth 2.0

Authorization request for user

/auth/user/authorize

See OAuth 2.0

Authorization grant for contact

/auth/contact/access_token

See OAuth 2.0

Authorization grant for user

/auth/user/access_token

See OAuth 2.0

List Filters

Apply

Two endpoints which return a list of records, Get list of records and Get list of related records, support two query parameters to get a specific data set.

1. filter_text - Generic search string. Fields involved in search depend on a model. Include this parameter to a query for filtering a list of records by Subject, Name, # (like Invoice #) etc.
   Examples: /api.php/data/Invoice?filter_text=2020-100 api.php/data/Task?filter_text=Send%20Contract
2. filters - A list of filters to apply. To get a list of available filters for a model, use metadata endpoint. Some filters differ from field names. Check a model metadata carefully to avoid mistakes. For example if you want filtering records by email you have to use any_email filter parameter instead of email1 or email2.
   Examples: /api.php/data/Account?filters[account_type]=Supplier&filters[any_email]=sales@1crm.com Also for some filters you can use a part of the value like this - api.php/data/Account?filters[any_email]=sales
   
   For Ref fields (e.g. Billing Account, Primary Contact etc.) there are two ways of filter applying:
   1. Using text value of Ref field, e.g. Account Name - /api.php/data/Invoice?filters[billing_account]=Microsoft
   2. Using ID. You can find the correct name of a filter for this case in a filter metadata, under id_name - /data/Invoice?filters[billing_account_id]=2e1a3464-47e0-5201-4a5c-5c9b25575447

3. Date Filters: filtering by date fields may require additional parameters. The most used second parameter for the date filter is operator. If you omit operator parameter the default value will be on_date.
   All possible operator parameter values:

   • not_empty field value is not empty (provided without date_field value)
   • empty field value is empty (provided without date_field value)
   • before_date field value is before the date passed in a query
   • after_date field value is after the date passed in a query
   • on_date field value equals the date passed in a query
   • not_on_date field value does not equal the date passed in w query
   • yesterday field value is yesterday's date (provided without date_field value)
   • today field value is today's date (provided without date_field value)
   • tomorrow field value is tomorrow's date (provided without date_field value)
   • between_dates field value is between dates passed query, inclusive (required end date value date_field-end)
     
     You can also pass period_prev, period_current, or period_next as operator value. In this case filed value will be checked against previous, current, or next period relative to current date. Period length is determined by date_field-period parameter:
   • day one day
   • week calendar week
   • month calendar month
   • quarter calendar quarter
   • year calendar year
   • fiscal_quarter fiscal quarter
   • fiscal_year fiscal year
   • days_N N days (dayes_7, days_14, days_30, etc)

   Examples:
   /api.php/data/Invoice?filters[due_date]=2020-01-01 - get all invoices with due_date = '2020-01-01' (due_date-operator = 'on_date' by default)
   /api.php/data/Invoice?filters[due_date]=2020-01-01&filters[due_date-operator]=before_date - get all invoices with due_date < '2020-01-01' /api.php/data/Invoice?filters[due_date-operator]=empty - get all invoices with empty due_date value
   /api.php/data/Invoice?filters[due_date]=2020-01-01&filters[due_date-end]=2020-02-01&filters[due_date-operator]=between_dates - get all invoices with due_date >= '2020-01-01' AND due_date <= '2020-02-01'
   /api.php/data/Invoice?filters[due_date-operator]=period_prev&filters[due_date-period]=week - get all invoices with due_date between start and end of previous week from today

Working with data

Add or remove a record from user's favorites

 /data/favorites/{model}/{id}

Get list of records

 /data/{model}

Retrieve list of records belonging to specified model

Returned objects do not have a predefined structure, it depends on model and requested fields. See Metadata

Create records

 /data/{model}

Create a record of specified model

Get single record

 /data/{model}/{id}

Retrieve single record belonging to specified model, identified by id

Returned object does not have a predefined structure, it depends on model and requested fields. See Metadata

Update a record

 /data/{model}/{id}

Update record belonging to specified model, identified by id

Delete a record

 /data/{model}/{id}

Delete record belonging to specified model, identified by id

Get list of related records

 /data/{model}/{id}/{link}

Retrieve list of related records belonging to specified model and id via specific link

Returned objects do not have a predefined structure, it depends on model and requested fields. See Metadata

Add related records

 /data/{model}/{id}/{link}

Add list of related records belonging to specified model and id via specific link.

You can specify related records in 2 ways:

1. Pass an array of related IDs in records parameter. This is suitable for most links, where you just want to set relationship between records, without specifying additional link data. Example: linking Contact to Account.

2. Pass an array of objects with additional data to be inserted into join table in records_with_data parameter. For example, when adding a product to assembly, you want to specify the quantity of products in the assembly. Imagine you want to add 5 products with ID 3d3e96d1-8d7c-acd6-e338-55b9b0cc5aae to assembly with ID 5121670a-9ddb-8330-195d-5979fc9a6906. Then you POST to /data/Assembly/5121670a-9ddb-8330-195d-5979fc9a6906/products, and pass the following JSON in request body:

   {
      "records_with_data": [
          {
              "id": "3d3e96d1-8d7c-acd6-e338-55b9b0cc5aae",
              "quantity" : 5
          }
      ]
   }

Remove relationship between records

 /data/{model}/{id}/{link}/{rel_id}

Get list of all related records

 /data/link/{model}/linked-records/{link}

Retrieve list of all related records belonging to specified model via specific link

Returned objects do not have a predefined structure, it depends on model and requested fields. See Metadata

Erase Personal Data

 /data/erase_personal/{model}/{id}

Erase Personal Data belonging to specified model, identified by id

Tally Objects

1CRM includes a set of modules that have a common property: each record from those modules contains a list of related line items. This includes records that represent financial transactions (Quotes, Invoices, Bills etc.) and moves of goods (Shipping, Receiving). Records from such modules are collectively referred to as Tally Objects. 1CRM API provides a set of endpoints for working with such objects that allow to treat the Tally objects as a whole, not as separate "parent" record (for example, invoice) and a set if line items.

Get a Tally Object

 /tally/{model}/{id}

Working with calendars

Get list of events

 /calendar/events

Retrieve list of events within specified dates range. Returned records are grouped by type, and within each type records are sorted by date. No more than 200 records of each type are returned.

Working with metadata

Get fields definition for a model

 /meta/fields/{model}

Get locale-related information

 /meta/locale

Retrieve information about how 1CRM is configured to format numbers, addresses and currency values

Date and time formats are as defined in the documentation of PHP date() function.

Name format can contain s, f and l placeholders, for salutation, first name and last name, respectively.

Address format can contain placeholders. A placeholder constist of a letter between curly braces:

• {s} for street address
• {c} for city
• {t} for state
• {o} for country
• {p} for postal code
• {a} for company name
• {n} for contact name
• {d} for department
• {h} for phone
• {f} for fax

| (pipe symbol) denotes a space, [ ] (a space in square bracket) is for new line.

Get list of available modules

 /meta/modules

Get ListView metadata for a model

 /meta/list_view/{model}

Retrieve ListView metadata belonging to specified model

Get Sub Panels metadata for a model

 /meta/sub_panels/{model}/{detail_layout}

Retrieve Sub Panels metadata belonging to specified model and detail_layout

Get DetailView metadata for a model

 /meta/detail_view/{model}/{layout}

Retrieve DetailView metadata belonging to specified model and layout

Get generic module metadata

 /meta/generic_module_layouts/{module}

Generic module metadata - default list, detail, popup layouts

Working with files

Upload a small file

 /files/upload/base64

Upload a file. Uploaded file will be saved to a temporary location. Returned file ID can be used as a value for fields having file_ref or image type when creating or updating records.

This endpoint is suitable for uploading relatively small files, such as contact or user photos. Request body length should not exceed 1048576 bytes.

Note that uploaded files will be kept on server for a limited amount of time if not linked in file_ref or image field after upload.

Upload a file

 /files/upload

Upload a file. Uploaded file will be saved to a temporary location. Returned file ID can be used as a value for fields having file_ref or image type when creating or updating records.

This endpoint is suitable for uploading larger files, compared to /files/upload/base64. File size limit depends on maximum post size defined in PHP configuration.

Note that uploaded files will be kept on server for a limited amount of time if not linked in file_ref or image field after upload.

Download a file

 /files/download/{model}/{id}

Download a file.

This endpoint is for downloading 1CRM Documents and Note attachments

File source is identified with model and id parameters:

• When model equals to Document, latest document revision will be downloaded. id is the Document ID
• When model equals to DocumentRevision, specific document revision will be downloaded. id is the Document Revision ID
• When model equals to Notes, note attachment will be downloaded, id is Note ID

On success, the response body contains raw file data. Additional information may be returned in Content-Type, Content-Length, Content-Disposition, and X-OneCRM-Filename response headers.

On failure, HTTP response code different from 200 will be returned, and response body contains additional information in JSON format.

Get information about a file

 /files/info/{model}/{id}

Get information about a file.

This endpoint is for Retrieving metadata for 1CRM Documents and Note attachments.

See /files/download/:model/:id for description of model and id parameters.

Webhooks

A Webhook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST.

In 1CRM, 3 types of webhooks are available create, update and create_update. Webhook type determines the event that triggers the notification. create webhooks are triggered when a new record is created. update webhooks are triggered when an existing record is updated. create_update webhooks are triggered for both new records and updated records.

When a webhook is triggered, a HTTP POST request is sent to specified URL. Content-Type header is set to application/json, and a JSON object is passed in request body. The object contains the values of record's fields after the update.

When a record is updated, first all webhooks with corresponding type and model are selected. Then each webhook is examined for the user that created it. If the user has no read access to the updated record, the webhook will be excluded from further examination. Next, for each webhook, each filter from filters is examined:

• if glue is and, and all conditions from filters are satisfied, the webhook triggers
• if glue is or, and at least one condition from filters is satisfied, the webhook triggers

Click here to see examples of webhook filters.

Get List of webhooks

 /webhooks

Get List of webhooks

Create a webhook

 /webhooks

Delete a webhook

 /webhooks/{id}

Delete webhook identified by id

Get a webhook

 /webhooks/{id}

Get data for webhook identified by id

Update a webhook

 /webhooks/{id}

Portal

Create access token for portal user

 /portal/auth

Create a new access token to be used for portal access. Returned access token allows access to a limited subset of data that is relevant for certain contact only.

Utility

Get information about authenticated user

 /me

Get server public key

/public_key

Get 1CRM version

/version

Returns 1CRM version. Can be used to validate login info

Print PDF

Print PDF

 /printer/pdf/{model}/{id}

Print Personal Data PDF

 /printer/pdf/personal/{model}/{id}

Audit

Get list of audit logs

 /audit/{model}

Retrieve list of audit logs belonging to specified model

Get parent record audit logs

 /audit/{model}/{id}

Retrieve list of audit logs belonging to specified model, identified by parent record id

Reports

Get list of reports

 /reports/{model}

Retrieve list of reports belonging to specified model

Get list of archived runs

 /reports/{model}/{id}

Retrieve list of archived runs belonging to specified model, identified by report id

Get report data

 /reports/data/{model}/{id}

Retrieve archived runs report data belonging to specified model, identified by run id

Working with list and detail layouts

Set ListView layout(tab) params for a model

 /layouts/list_view/{model}

Set ListView layout(tab) params belonging to specified model