API interaction

tip

You can download the Altcraft API collection for Postman using this link.

Requests format

Requests are sent by POST method using HTTP/1.1 protocol. The method is also mentioned on each request description page.

Request parameters are placed in the sent structure. Some parameters can be sent in URL (API key, format).

The input data format must be indicated in the Content-Type HTTP header.

Possible header values:

• application/json — JSON format

Symbols must have UTF-8 coding.

POST https://example.com/api/v1.1/<method name>

If you use an Altcraft Platform Cloud account, send API requests to the URL ru.altkraft.com. In the case of deploying the platform on your hardware (On-Premises), use your own URL.

A description of the JSON format can be found in RFC 7159: http://tools.ietf.org/html/rfc7159.

Don't forget to encode characters that cannot be directly written in JSON.

Authorization

For authorization when sending a request, you need to pass a token to the platform. There are several ways to do this, for example, by specifying it in the body of the request:

{
	"token": "bfc505684d774e52b188fa1f003cd5ed",
	"db_id": 1,
	"resource_id": 1,
	"matching": "email",
	"email": "example@example.com",
	"data": {
		"_status": 0,
		"_fname": "Jim",
		"_lname": "Jones",
		"email": "example@example.com",
		"phones": ["+79000000000"]
	}
}

You can also pass the token in one of the request headers. To do this, create a header with the Authorization key, and in its value specify Bearer <token>, where instead of <token> insert your token.

API token can be created in the user panel, in section "Settings" — "Tokens". Master user rights are necessary to create a token:

API token is automatically generated after saving. You can also select a token name and configure access rights (in roles) and groups of objects available for this token.

caution

We do not recommend passing a token in the URL of your request. This method is insecure and will not be supported by the platform in the future.

Response format

The response format can be selected in the request header or parameters.

Response example (Successful operation):

{
	"error": 0,
	"error_text": "Successful operation",
	"profile_id": "5f4fa1a5ce9448665fef548e"
}

The following parameters are given in responses:

• error — error code;
• error_text — error description;
• profile_id — profile identifier (for successful operation).

info

Code 200 is the success status code in HTTP transport. However, if there is information about an error within the HTTP transport, additional details about the error are provided in a JSON object in the error field with explanations in error_text.

Response codes

Code	Description
0	Operation is successful
400	Incorrect request
401	API token required
402	Tariff limit reached
403	No rights for this action
404	The object is not found in the token vision zone
409	Another record with the same unique attributes already exists
413	The database is not available in the selected resource
415	Requested Content-Type is not supported
429	The number of requests set in the configuration file has been exceeded (API_MAX_REQUESTS_COUNT)
435	Ambiguous search, there are several objects with given attributes
441	The object belongs to another group
450	Request validation error
500	Internal service error
501	The method does not exist

XML tags attributes

XML queries are built on top of JSON queries, so in some situations it is necessary to write additional attributes inside tags:

• array='true' - an attribute indicating that the tag is an array. Used when there is either 1 element inside the array or no elements at all.
• string='true' - attribute is used to indicate that the value used has a string data type. Required when the string contains a number or the word "true"/"false".
• json='true' - attribute needed when we need to pass json request inside xml request (for example, selection parameters when requesting data on several profiles).

Request deduplication

If the connection fails at the moment of receiving the data, a second request may be sent. The platform will not accept a repeated request if it modifies the data in order to avoid duplicate events. Read more about repeated requests in this article.