Skip to main content

JSON API

Table of Contents

Before you start calling endpoints 

Please check the following below:

Composer 

Install composer packages with

composer install

Generate private and public.key for OAUTH2 

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

First, open a terminal and go to {{suitecrm.root}base.url}}/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 

SuiteCRMHelloCloud Api allows two kind of grant types:

  • Client credential

  • Password

Table 1. Token request parameters
Parameter Description

Access Token URL

{{suitecrm.base.url}}/Api/access_token

Username

Only available for Password grants. Must be a valid SuiteCRMHelloCloud 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.base.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.base.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.base.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.base.url}}/V8/module/Accounts?fields[Accounts]=name,account_type&filter[operator]=and&filter[account_type][eq]=Customer

Example:

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

Result:

Endpoints 

Logout 

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

Get a module by ID 

GET {{suitecrm.base.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.base.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.base.url}}/V8/module

Example body:

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

Update a module record 

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

Example body:

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

Delete a module record 

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

Get relationship 

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

Example:

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

Create relationship 

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

Example body:

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

Delete relationship 

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

Example:

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