CRM API – Version 4

Making Requests

Making a request is simple, choose the record type you want and take a note of the object name, then simply send a GET, POST, PATCH, DELETE request to the servers.

The URL structure is the same for all type of requests, just the method changes.

e.g:

GET /accounts
GET /contacts
POST /accounts
PATCH /accounts/123456
DELETE /accounts/123456

Record Limits and Pagination

All GET requests are limited to 100 records at a time and defaulted to 10. You can change this limit by passing limit in the URL.

GET /accounts?limit=50

Due to the limits above, you can also pass a page number.

GET /accounts?page=2

This will return your accounts starting from the 2oth record by default. You can combine limits and pages together to get more results for a particular page.

GET /accounts?limit=100&page=4

This will return your accounts starting at the 400th record.

If the page cannot be found, no records will be returned.

Opportunity Lines

You can return the line items for an opportunity inline under the key of ‘lines’ by passing the request parameter of lines=true

GET /opportunities?lines=true

GET /opportunities/{id}?lines=true

The returned JSON will include the ‘lines’ key similar to below.

"lines": [
      {
        "id": 1,
        "opportunityid": 1,
        "product": "User Subscription",
        "quantity": 30,
        "unitprice": 420
      }
    ]

Filtering results

Filtering is as simple as sending a request with the query parameter set in the URL, the parameter consists of fields and operators in JSON format that make up a complete query. The field or fields you provide must match a field in the objects data dictionary.

Quick example

GET /accounts?q={"name": "Test"}

Which is the same as asking for all accounts with the name “Test”.

You can match on a single field. ?q={“name”: “Test”}

Or you can match on multiple fields. ?q={“name”: “Test”, “sector”: “Design”}

In addition to simple fields, you can use special operators to provide move complex queries.

Logic Operators

{"field": {"$not": val}}

{"field": {"$in": [value1, value2, ...]}}

{"field": {"$nin": [value1, value2, ...]}}

{"$or": [{"field": value}, {"field": value}]}

Conditional Operators

{"field": {"$gt": 1000}}

{"field": {"$gte": 1000}}

{"field": {"$lt": 1000}}

{"field": {"$lte": 1000}}

{"field": {"$bt": [1000, 2000]}}

{"field": {"$sw": "tes"}}

{"field": {"$ew": "tes"}}

{"field": {"$con": "tes"}}

Ordering

You can pass in the query parameter of ?order to order the results, this needs to be in JSON format and consist of a field and direction.

The direction can be either asc or desc.

Quick example:

GET /accounts?order={"field": "asc"}

You can order by many fields by passing multiple into the query.

GET /accounts?order={"field": "asc", "field2": "asc", ...}

GET Requests

This will only ever return information to you.

To get a list of all your records for a certain type, send a GET request for the record using the object name.

GET /{object_name}

Above will return a list of all your accounts based on your permission level.

GET /{object_name}/12345

Above will return the record which has the ID of 12345 or nothing. Refer to the example tab above to see what this would look like.

POST Requests

You can use POST request when you wish to create records. You POST a JSON encoded string to the servers and it will return a single instance of the record.

POST /{object_name}

If all the validation and subscription limit checks pass, the newly created record will be returned. Refer to the example tab above to see what this would look like.

N.B. It is required to include all mandatory fields, in an API Call which creates a new CRM record, via POST.

PATCH Requests

These are used to update records that already exist within your CRM system. It still requires a JSON encoded string to be submitted to the servers but the url must include the ID of the record to be updated.

PATCH /{object_name}/123456

Without the ID, the request will fail.

If the request is successful, a single instance of the record will be returned.

DELETE Requests

Similar to a PATCH request but this doesn’t need any content, it just needs the ID of the record you wish to delete.

DELETE /{object_name}/12345

The request will fail without the id.

If successful, it will also not return any content, just a status code of 200.

Error Responses

If bad request is made or there has been an error handling your request, you will get an error similar to below.

{
  "type": "Invalid Request error",
  "code": 500,
  "message": "Invalid record type (accountss)"
}

The code may be different and the message itself, but it will return a JSON object and always have a message index letting you know what has gone wrong.

If an error had been encountered you will received a status code higher then or equal to 3xx. A status code of 200 or 201 means your request was successful.

Response status codes

On a 422 error response, the JSON response will also contain validation information letting you know what went wrong.

{
  "type": "Validation error",
  "code": 422,
  "message": "The given data was invalid.",
  "validation": {
    "accountid": [
      {
        "Required": []
      }
    ]
  }
}

Quick Start

Enable your Users

Login to your CRM system and navigate to Settings / Integrations / API V4 then “Enable API Access to Users”.

Select the User you want to give access to and click Enable.

Get your Access Token

Navigate to Settings / Integrations / API V4 then “Manage API Keys and Alerts” and click the ‘generate new key’ button on the right.

In the popup window, select the User you want the Access Token for and click ‘generate’.

You will be presented with an Access Token. Make a note of this as it’s only shown to you once.

Make a GET Request

Visit: https://insomnia.rest/download and enter https://apiv4.reallysimplesystems.com/accounts into the ‘Curl Command URL’ field.

Click the add option button and select ‘–header (-H)’ and put the following into the ‘insert attributes’ field replacing {access_token} with your token:

Authorization: Bearer {access_token} and click ‘Start your curl’ below.

Results

Scroll to the bottom of the page and you should see a Response body section with the results of the test. If it starts with ‘{“metadata”:{“url”:”\/account”‘ then it was successful.

Examples

GET Your Accounts

Request URL (GET):

/accounts

Request Body:

Nothing is required

Response JSON:

{
    "metadata": {
        "url": "/account",
        "object_type": "list",
        "total_count": 100,
        "has_more": true
    },
    "list": [
        {
            "metadata": {
                "url": "/accounts/95920978",
                "list_url": "/accounts",
                "parent": "/",
                "object_type": "record",
                "record_type": "account"
            },
            "record": {
                "id": 95920978,
                "name": "test",
                "addressline": null,
                "addresscity": "",
                "addresscounty/state": "",
                "addresspostcode/zip": "",
                "addresscountry": "",
                "ownerid": 90505,
                "source": "",
                "notes": null,
                "phone": null,
                "website": null,
                "type": null,
                "sector": null,
                "createddate": "2018-09-17 11:29:59",
                "modifieddate": "2018-09-17 11:29:59"
            }
        },
        ...
    ]
}

Create a New Account

Request URL (POST):

/accounts

Request Body (JSON):

{
    "name": "testing API",
    "ownerid": 1
}

N.B. It is required to include all mandatory fields, in an API Call which creates a new CRM record, via POST. Please email us on support@spotlercrm.com for a current list of mandatory fields on the CRM.

Response (JSON):

{
    "metadata": {
        "url": "/accounts/95950731",
        "list_url": "/accounts",
        "parent": null,
        "object_type": "record",
        "record_type": "account"
    },
    "record": {
        "id": 95950731,
        "name": "testing API",
        "addressline": null,
        "addresscity": "",
        "addresscounty/state": "",
        "addresspostcode/zip": "",
        "addresscountry": "United Kingdom",
        "ownerid": 90505,
        "campaignid": 0,
        "source": "",
        "notes": null,
        "slaid": 125357,
        "phone": null,
        "website": null,
        "type": null,
        "sector": null,
        "createddate": "2018-09-27 08:48:22",
        "modifieddate": "2018-09-27 08:48:22"
    }
}

Update an Account

Request URL (PATCH):

/accounts/95950731

Request Body (JSON):

{
    "name": "testing API Updated"
}

Response (JSON):

{
    "metadata": {
        "url": "/accounts/95950731",
        "list_url": "/accounts",
        "parent": null,
        "object_type": "record",
        "record_type": "account"
    },
    "record": {
        "id": 95950731,
        "name": "testing API Updated",
        "addressline": null,
        "addresscity": "",
        "addresscounty/state": "",
        "addresspostcode/zip": "",
        "addresscountry": "United Kingdom",
        "ownerid": 90505,
        "campaignid": 0,
        "source": "",
        "notes": null,
        "slaid": 125357,
        "phone": null,
        "website": null,
        "type": null,
        "sector": null,
        "createddate": "2018-09-27 08:48:22",
        "modifieddate": "2018-09-27 08:55:38"
    }
}

DELETE an Account

Request URL (DELETE):

/accounts/95950731

Request Body:

Nothing is required

Response Body (JSON):

{}

Returned with a status code of 200

API Alerts

Usage Alerts

You can set Usage Alerts that send an email to your selected user when you have reached a given percentage of your call limit. In Settings/Integrations/API V4 select “Manage API keys and alerts”. Here, click the down arrow to open the “Usage Alert” box, then simply select the user and the usage limit percentage when you want to trigger the alert, then save. This will email the user when you have reached that level. You can also manually add an email address and name to be alerted.

Failed API Call Alerts

Similarly, you can set up alerts to trigger a message to a user should you encounter a failed API call. Click on the down arrow to open the “Failed API Call Alert” box and select the user from the dropdown list, or add their details manually, then save.