JSON API

Before you start calling endpoints

Please check the following below:

Composer

Install composer packages with

composer install

Generate private and public.key for OAUTH2

SuiteCRM Api uses OAuth2 protocol, which needs public and private keys.

First, open a terminal and go to {{suitecrm.root}}/Api/V8/OAuth2

Generate a private key:

openssl genrsa -out private.key 2048

Then a public key:

openssl rsa -in private.key -pubout -out public.key

If you need more information about generating, please visit this page.

The permission of the key files must be 600 or 660, so change it.

sudo chmod 600 private.key public.key

Also, you have to be sure that the config files are owned by PHP.

sudo chown www-data:www-data p*.key

OAuth2’s AuthorizationServer needs to set an encryption key for security reasons. This key has been generated during the SuiteCRM installation and stored in the config.php under "oauth2_encryption_key". If you would like to change its value you may generate a new one by running

php -r 'echo base64_encode(random_bytes(32)), PHP_EOL;'

and then store the output in the config.php

Current releases all use the value directly from config.php

Older versions updated the file /Api/Core/Config/Apiconfig.php with the value from config.php when running a repair and rebuild. If any issues arise and you are troubleshooting it may be worth taking a look there.

If you need more information about this issue, please visit this page.

Verify if rewrite module is installed and activated

It is necessary to verify if 'mod_rewrite' module of Apache server is enabled. Make sure to enable and activate it. This process depends on Operating System, installed versions of software etc. Please check this stackoverflow’s answers 1, 2 to get directions how to enable the module.

Also, for the SuiteCRM location (root{/var/www} or subdir{/var/www/subdir}) one should change AllowOverride directive inside Directory directive from None to All to assure that rewrite rules of .htaccess work:

<Directory /var/www/subdir>
	Options Indexes FollowSymLinks
	AllowOverride All
	Require all granted
</Directory>

Authentication

SuiteCRM Api allows two kind of grant types:

Client credential
Password

Table 1. Token request parameters
Parameter	Description
Access Token URL	{{suitecrm.url}}/Api/access_token
Username	Only available for Password grants. Must be a valid SuiteCRM user name.
Password	Only available for Password grants. Password for the selected user.
Client ID	Client ID exists in OAuth2Clients module’s ID. Must be a valid GUID.
Client Secret	Client secret is also in OAuth2Clients module as SHA256 generated value.
Scopes	Scopes haven’t implemented yet

Available parameters

According to JsonApi specification, the available parameters are the following depending on the GET endpoint:

Fields

Fields can filter on attribute object. Allowed keys are valid bean properties.

Example:

{{suitecrm.url}}/Api/V8/module/Accounts/11a71596-83e7-624d-c792-5ab9006dd493?fields[Accounts]=name,account_type

Result:

{
    "data": {
        "type": "Account",
        "id": "11a71596-83e7-624d-c792-5ab9006dd493",
        "attributes": {
            "name": "White Cross Co",
            "account_type": "Customer"
        },
        "relationships": {
            "AOS_Contracts": {
                "links": {
                    "related": "/V8/module/Accounts/11a71596-83e7-624d-c792-5ab9006dd493/relationships/aos_contracts"
                }
            }
        }
    }
}

Page

Page can filter beans and set pagination. Allowed key are number and size.

page[number] : number of the wanted page
page[size] : size of the result

Example:

{{suitecrm.url}}/Api/V8/module/Accounts?fields[Account]=name,account_type&page[number]=3&page[size]=1

Result:

{
    "meta": {
        "total-pages": 54
    },
    "data": [
        {
            "type": "Account",
            "id": "e6e0af95-4772-5773-ae70-5ae70f931feb",
            "attributes": {
                "name": "",
                "account_type": ""
            },
            "relationships": {
                "AOS_Contracts": {
                    "links": {
                        "related": "/V8/module/Accounts/e6e0af95-4772-5773-ae70-5ae70f931feb/relationships/aos_contracts"
                    }
                }
            }
        }
    ],
    "links": {
        "first": "/V8/module/Accounts?fields[Account]=name,account_type&page[number]=1&page[size]=1",
        "prev": "/V8/module/Accounts?fields[Account]=name,account_type&page[number]=2&page[size]=1",
        "next": "/V8/module/Accounts?fields[Account]=name,account_type&page[number]=4&page[size]=1",
        "last": "/V8/module/Accounts?fields[Account]=name,account_type&page[number]=54&page[size]=1"
    }
}

Sort

Sort is only available when collections wanted to be fetched. Sorting is set to ASC by default. If the property is prefixed with hyphen, the sort order changes to DESC.

Important notice: we only support single sorting right now!

Example:

{{suitecrm.url}}/Api/V8/module/Accounts?sort=-name

Result:

{
    "data": [
        {
            "type": "Account",
            "id": "e6e0af95-4772-5773-ae70-5ae70f931feb",
            "attributes": {
                "name": "White Cross Co",
                "account_type": "Customer"
            },
            "relationships": {
                "AOS_Contracts": {
                    "links": {
                        "related": "/V8/module/Accounts/1d125d2a-ac5a-3666-f771-5ab9008b606c/relationships/aos_contracts"
                    }
                }
            }
        },
        {
            "type": "Account",
            "id": "7831d361-2f3c-dee4-d36c-5ab900860cfb",
            "attributes": {
                "name": "Union Bank",
                "account_type": "Customer"
            },
            "relationships": {
                "AOS_Contracts": {
                    "links": {
                         "related": "/V8/module/Accounts/7831d361-2f3c-dee4-d36c-5ab900860cfb/relationships/aos_contracts"
                    }
                }
            }
        }
    ],
}

Filter

Our filter strategy is the following:

filter[operator]=and
filter[account_type][eq]=Customer

Important notice: we don’t support multiple level sorting right now!

Supported operators

Comparison

EQ = '=';
NEQ = '<>';
GT = '>';
GTE = '>=';
LT = '<';
LTE = '<=';

Logical

'AND', 'OR'

Example:

{{suitecrm.url}}/Api/V8/module/Accounts?fields[Accounts]=name,account_type&filter[operator]=and&filter[account_type][eq]=Customer

Example:

{{suitecrm.url}}/Api/V8/module/Accounts?filter[account_type][eq]=Customer

Result:

Endpoints

Logout

POST {{suiteCRM.url}}/Api/V8/logout

Modules

GET {{suiteCRM.url}}/Api/V8/meta/modules

Module Fields

GET {{suiteCRM.url}}/Api/V8/meta/fields/{moduleName}

Get a module by ID

GET {{suitecrm.url}}/Api/V8/module/{moduleName}/{id}

Available parameters: fields

Example:

Api/V8/module/Accounts/11a71596-83e7-624d-c792-5ab9006dd493?fields[Accounts]=name,account_type

Get collection of modules

GET {{suitecrm.url}}/Api/V8/module/{moduleName}

Available parameters: fields, page, sort, filter

Example:

Api/V8/module/Accounts?fields[Accounts]=name,account_type&page[size]=4&page[number]=4

Create a module record

POST {{suitecrm.url}}/Api/V8/module

Example body:

{
  "data": {
    "type": "Accounts",
    "attributes": {
      "name": "Test account"
    }
  }
}

Update a module record

PATCH {{suitecrm.url}}/Api/V8/module

Example body:

{
  "data": {
    "type": "Accounts",
    "id": "11a71596-83e7-624d-c792-5ab9006dd493",
    "attributes": {
      "name": "Updated name"
    }
  }
}

Delete a module record

DELETE {{suitecrm.url}}/Api/V8/module/{moduleName}/{id}

Get relationship

GET {{suitecrm.url}}/Api/V8/module/{moduleName}/{id}/relationships/{relatedModuleName}

Example:

Api/V8/module/Accounts/129a096c-5983-1d59-5ddf-5d95ec91c144/relationships/Accounts

Create relationship

POST {{suitecrm.url}}/Api/V8/module/{moduleName}/{id}/relationships

Example body:

{
  "data": {
    "type": "Contacts",
    "id": "129a096c-5983-1d59-5ddf-5d95ec91c144"
  }
}

Delete relationship

DELETE {{suitecrm.url}}/Api/V8/module/{moduleName}/{id}/relationships/{relatedModule}/{relatedBeanId}

Example:

/Api/V8/module/Accounts/129a096c-5983-1d59-5ddf-5d95ec91c144/relationships/Accounts/11a71596-83e7-624d-c792-5ab9006dd493