Skip to main content
Version: 1.1beta2

API protocol (JSON RPC)

The Clarify API is using JSON RPC 2.0 as the API communication protocol. RPC stands for Remote Procedure Calls, and works very much like how you would call a function within a programming language: you call a named function with a set of input parameters, and may expect the return of a result. In JSON RPC though, we call them methods and not functions.

To call an RPC method in Clarify, you simply make a HTTP POST request with a JSON formatted body containing a single RPC Request. All requests are made against the exact same URL endpoint https://api.clarify.io/v1/rpc. For how to authenticate against the API see Authentication.

Alignment with JSON RPC 2.0 specification

In addition to absolute requirements, we align with most of the recommendations from the specification that could make writing a client easier. This includes allowing both named and positional parameters as well as sticking with recommendations for error formatting. We also allow the client to decide on the type to use for the id field.

However, we have chosen not to support JSON RPC batch requests for the time being. This is because we don't think there is a need for it with our current API design.

Request

Set the "id" field

If the "id" field in the request is omitted or set to null, the server will assume the client is not intending to wait for a response, and we won't return one. The JSON RPC spec calls this a "notification".

It's up to your client to decide on the data type and value to use for the ID field, as long as it's a valid JSON value. The same ID that is used in the request will be used in the response. However, if your client doesn't have any specific needs, we recommend that you just use 1 as it's a short and simple value. This is the value that is typically used by our SDKs.

type: object

FieldDescription
jsonrpc
string("2.0")
Version of JSON RPC protocol to use. Must be "2.0".
id
any
A client side request ID. Set to any value except null to request a response; the response will contain the same ID as the request.
method
string
Name of method to invoke.
params
array, object
Input parameters for the method, encoded either as positional parameters (array) or named parameters (object). We offer better backwards-compatibility for named parameters.

Example

request
{
"jsonrpc": "2.0",
"method": "<RPC METHOD>",
"id": 1,
"params": {}
}

Response

You will only get a JSON RPC response when you are able to reach the API. You will not be able to reach the API if you either select a non-existing version, your client fail to authenticate, or your client is rate-limited. In such cases, you will receive a transport layer error. If you are able to reach the API, but didn't set a request ID, then you will also not receive a JSON RPC response.

The JSON RPC 2.0 specification does not allow both result and error to be present in the response. The Clarify API defines that a result, when present, is always an object. The error, when present, follow our own Error schema.

type: object

NameDescription
jsonrpc
string("2.0")
Will always be "2.0".
id
any
The client-side ID used for the request.
result
object
The result of a successful method call, present on success.
error
Error
The result of a failed RPC method, present on error.

Examples

Response with result
{
"jsonrpc": "2.0",
"id": 1,
"result": {...}
}
Response with error
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32602,
"message": "Invalid params",
"data": {
"trace": "00000000000000000000",
"params": {
"integration": ["required"]
}
}
}
}

Error

Error describe the standardized JSON RPC 2.0 error format, as well as a Clarify specific data field and error codes. When an error is present, the result portion will be empty.

type: object

NameTypeRequireDescription
codeintegerYesA code describing the error type.
messagestringYesA textual description of the error.
dataError dataNoAn object describing more details related to the error. The structure of the ErrorData object is Clarify specific.

Error data

Error data is a Clarify specific format for embedding useful error information.

type: object

NameTypePresenceDescription
tracestringAlwaysA unique ID that can be supplied to the Clarify Support team to help us debug what happened for a particular failed request.
paramsmap of string => array of stringOptionalPresent when the error code and message can be traced back to specified parameters.

Error codes

Below is a list of the possible values for the code field. Codes written with a bold font are specific to Clarify, while the other codes are defined by the JSON RPC 2.0 specification.

CodeNameDescription
-32700ErrParseInvalidJSONIndicates invalid JSON is received by the server.
-32600ErrInvalidRequestIndicates the sent JSON is not a valid Request object.
-32601ErrMethodNotFoundIndicates the method does not exist / is not available.
-32602ErrInvalidParamsIndicates invalid method parameter(s).
-32603ErrInternalIndicates an internal JSON-RPC error.
-32000ErrServerIndicates a generic server error.
-32001ErrProduceInvalidResourcesProduce invalid resource(s) in Clarify.
-32002ErrFoundInvalidResourceFound invalid resource(s) or code issue in Clarify.
-32003ErrForbiddenIndicates that the requested operation is not permitted by your current access token, or that the input parameters are referencing a resource that isn't accessible / doesn't exist.
-32009ErrConflictIndicates a conflicts with current state of Clarify resource(s).
-32015TryAgainIndicates that the response should be called again later. Maybe returned in the case of temporal errors or rate limited requests.