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

Update encryption key

OAuth2’s AuthorizationServer needs to set an encryption key for security reasons. For doing this, please, go to Api/Core/Config/ApiConfig.php and find "const OAUTH2_ENCRYPTION_KEY".

Now update its value with generating a new one using base64_encode(random_bytes(32))

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

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}}/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}}/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}}/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}}/V8/module/Accounts?fields[Accounts]=name,account_type&filter[operator]=and&filter[account_type][eq]=Customer

Example:

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

Result:

Endpoints

Logout

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

Get a module by ID

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

Available parameters: fields

Example:

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

Get collection of modules

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

Available parameters: fields, page, sort, filter

Example:

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

Create a module record

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

Example body:

{
  "data": {
    "type": "Accounts",
    "id": "86ee02b3-96d2-47b3-bd6d-9e1035daff3a",
    "attributes": {
      "name": "Test account"
    }
  }
}

Update a module record

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

Example body:

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

Delete a module record

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

Get relationship

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

Example:

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

Create relationship

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

Example body:

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

Delete relationship

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

Example:

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