---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://yandex.com/dev/direct/doc/dg-v4/en/concepts/JSON.md
  - https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/JSON.md
  - href: en/concepts/JSON.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/en/llms.txt

# JSON format
Accessing the Yandex Direct API in JSON format.

The advantage of JSON is its considerable compactness in comparison with SOAP/XML, as well as the speed of analyzing requests on the Yandex Direct side.

Many programming languages have modules and libraries for working with JSON. The recommended modules and libraries for popular languages are listed below.

- **Perl**: [JSON](http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm) module.
- **PHP**: Built-in JSON support was added in version 5.2.0. For previous versions, you can use the [Services_JSON](http://pear.php.net/package/Services_JSON) library.
- **Python**: the [json](https://docs.python.org/library/json.html) module.

The document contains samples for working with JSON in [Perl](https://yandex.com/dev/direct/doc/dg-v4/en/examples/PerlSamples-json.md), [PHP](https://yandex.com/dev/direct/doc/dg-v4/en/examples/php-sample-json.md), and [Python](https://yandex.com/dev/direct/doc/dg-v4/en/examples/python-json.md).

## JSON requests {#json-request}

Requests in JSON format are sent to the following address using the HTTP POST method:

**Version 4**

 
:   ```httpget
    https://api.direct.yandex.ru/v4/json/ 
    ```

**Live 4 version**

 
:   ```httpget
    https://api.direct.yandex.ru/live/v4/json/
    ```

The request always contains the `method` key with the name of the invoked method, and in most cases, also includes the `param` key (see the example below). Some methods do not have any input parameters, so the `param` key is not required for them.

## Sample JSON request

This example demonstrates calling the `GetClientInfo` method. In the `param` key, an array is passed that consists of a single string, the username. The `locale` key sets the language for response messages. The `token` key is the access token issued by the Yandex OAuth server with the user's permission (for more information, see [Authorization tokens](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/auth-token.md)).

```javascript
POST /v4/json/ HTTP/1.1
Host: api.direct.yandex.ru
Content-Length: 204
Content-Type: application/json; charset=utf-8

{
    "method": "GetClientInfo",
    "param": ["agrom"],
    "locale": "ru",
    "token": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f"
}
```

## Language for responses {#locale}

The request may contain the `locale` key, specifying the language for response messages. The selected language is used for returning campaign statuses, the status of banners, and [error messages](https://yandex.com/dev/direct/doc/dg-v4/en/reference/ErrorCodes.md). The `locale` key may have the following values:

- ru — Russian
- uk — Ukrainian
- en — English

If the `locale` key is not specified, English is assumed.

## Accessing finance methods {#fin-method}

To access the finance methods [CreateInvoice](https://yandex.com/dev/direct/doc/dg-v4/en/reference/CreateInvoice.md), [TransferMoney](https://yandex.com/dev/direct/doc/dg-v4/en/reference/TransferMoney.md), [GetCreditLimits](https://yandex.com/dev/direct/doc/dg-v4/en/reference/GetCreditLimits.md), and [PayCampaigns](https://yandex.com/dev/direct/doc/dg-v4/en/reference/PayCampaigns.md), you must also specify the transaction number and the finance token in the `operation_num` and `finance_token` keys. To learn how they are generated, see [Accessing finance methods](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/finance-token.md).

## Example of calling a finance method

Calling the `GetCreditLimits` finance method.

```javascript
{
    "method": "GetCreditLimits",
    "finance_token": "07c2fbae9722634918bb00a70d2c467cf1bd07255012008ff249ba41b7a5cd6c",
    "operation_num": 123,
    "token": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f"
}
```

## Error messages {#errors}

When errors occur, request processing is terminated and an error message is returned in JSON format. An example of such a message is shown below.

```javascript
{
    "error_detail":"The POST method should be used for an HTTP request",
    "error_str":"Invalid request method",
    "error_code":512
}
```

The `error_code` parameter contains the error code, `error_str` contains a brief description of the error, and `error_detail` contains an additional explanation, if available. The brief description and additional explanation can be displayed in various languages; this is determined by the [locale](https://yandex.com/dev/direct/doc/dg-v4/en/concepts/JSON.md#locale) parameter that is specified when calling the method.

## Related information

- [Description of the JSON format](http://www.json.org/json-ru.html)