---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.2
alternate:
  - https://yandex.com/dev/direct/doc/dg-v4/en/concepts/SOAP.md
  - https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/SOAP.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/en/llms.txt

# SOAP protocol
Accessing the Yandex Direct API over the SOAP protocol.

The Yandex Direct API supports SOAP (Simple Object Access Protocol) version 1.1. This protocol uses XML messages to exchange information.

There are many libraries that implement SOAP. Some of them are listed below:

- **Perl:** [SOAP::Lite](https://metacpan.org/pod/SOAP::Lite) and [XML::Compile](http://search.cpan.org/dist/XML-Compile/)
- **PHP:** [nuSOAP](https://sourceforge.net/projects/nusoap/) and [SOAPClient](http://php.net/manual/ref.soap.php)
- **Python:** [suds](https://pypi.python.org/pypi/suds)

## WSDL {#wsdl}

WSDL (Web Services Description Language) is an XML language for describing web services. It describes methods, input and output data structures, data types, network addresses for accessing the service, and more.

There is a WSDL description of the Yandex Direct API at:

**Version 4**

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

**Live 4 version**

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

WSDL was first developed by IBM, Microsoft and Ariba for use in conjunction with SOAP. The most functional SOAP libraries use WSDL to query services and verify transmissions. These libraries download the WSDL description, analyze it, and form the necessary data structures for making method calls. The application only needs to add data to the structures and send the query. In the same way, the XML response message is output as a structure inherent to the programming language. This frees the application from having to process XML.


{% note info %}

The application can form SOAP queries in XML format by itself, but this is a tedious task that isn't worth the effort, when there are fully-functional SOAP libraries available.

{% endnote %}


## Requests in SOAP format {#soap-req}

Data in SOAP format is passed using the HTTP POST method. SOAP requests are sent to the address Yandex Direct API:

**Version 4**

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

**Live 4 version**

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

The method for sending requests depends on the SOAP library. If the library supports WSDL, it is sufficient to specify the address of the WSDL file. The library will use it to get the address of the Yandex Direct API and perform whatever operations are necessary for sending the request. If the library does not support WSDL, the API address must be stated explicitly.

A SOAP message consists of a header, the `SOAP-ENV:Header` element (see the sample below) and a body, the `SOAP-ENV:Body` element. The header can contain metadata related to the message as a whole. The message body passes the `params` element with input parameters for the method. The format of the `params` element differs for various methods.

## Sample request in SOAP format

Calling the `GetClientInfo` method to get information about the user “agrom”. The header contains the `locale` element, which sets Russian as the response language, and the `token` element, which 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)).

```xml
POST /v4/soap/ HTTP/1.1
Content-Length: 686
Content-Type: text/xml; charset=utf-8
SOAPAction: "API#GetClientInfo"
Host: api.direct.yandex.ru

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:ns0="API"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Header>
    <locale>ru</locale>
    <token>0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f</token>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <ns0:GetClientInfo SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <params soapenc:arrayType="xsd:string[]">
        <xsd:string>agrom</xsd:string>
        <Login>agrom</Login>
      </params>
    </ns0:GetClientInfo>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

## Sample response in SOAP format

```xml
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:namesp2="http://namespaces.soaplite.com/perl"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <namesp3:GetClientInfoResponse xmlns:namesp3="API">
      <SOAP-ENC:Array xsi:type="namesp2:ArrayOfClientInfo" SOAP-ENC:arrayType="namesp2:ClientInfo[1]">
        <item xsi:type="namesp2:ClientInfo">
          <SendAccNews xsi:type="xsd:string">Yes</SendAccNews>
          <Discount xsi:nil="true" xsi:type="xsd:float"/>
          <Login xsi:type="xsd:string">agrom</Login>
          <Email xsi:type="xsd:string">agrom@yandex.ru</Email>
          <Role xsi:type="xsd:string">Client</Role>
          <FIO xsi:type="xsd:string">Andrew Smith</FIO>
          <DateCreate xsi:type="xsd:date">2011-01-06</DateCreate>
          <StatusArch xsi:type="xsd:string">No</StatusArch>
          <SendNews xsi:type="xsd:string">Yes</SendNews>
          <Phone xsi:nil="true" xsi:type="xsd:string"/>
          <NonResident xsi:type="xsd:string">No</NonResident>
          <SendWarn xsi:type="xsd:string">Yes</SendWarn>
        </item>
      </SOAP-ENC:Array>
    </namesp3:GetClientInfoResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

## Language for responses {#locale}

The SOAP message header can contain the `locale` element, which sets the language for response messages. The selected language is used for displaying 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` element is not specified, English is used.

## Accessing finance methods {#fin-method}

To call 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 additionally indicate the transaction number and finance token in the `operation_num` and `finance_token` elements respectively, as shown in the following example. 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. The finance token and transaction number are indicated in the message header.

```xml
POST /v4/soap/ HTTP/1.1
Content-Length: 686
Content-Type: text/xml; charset=utf-8
SOAPAction: "API#GetCreditLimits"
Host: api.direct.yandex.ru

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:ns0="API"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Header>
    <finance_token>07c2fbae9722634918bb00a70d2c467cf1bd07255012008ff249ba41b7a5cd6c</finance_token>
    <operation_num>123<operation_num>
    <token>0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f</token>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <ns0:GetCreditLimits SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <params/>
    </ns0:GetCreditLimits>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

## Error messages {#errors}

If an error occurs, request processing is terminated and an error message is returned in SOAP format. An example of such a message is shown below.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:namesp8="http://xml.apache.org/xml-soap"
                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                   xmlns:namesp4="http://namespaces.soaplite.com/perl"
                   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <SOAP-ENV:Fault>
      <faultcode xsi:type="xsd:string">SOAP-ENV:53</faultcode>
      <faultstring xsi:type="xsd:string">Authorization error</faultstring>
      <detail xsi:type="xsd:string"/>
    </SOAP-ENV:Fault>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
```

The `faultcode` element contains the error code, `faultstring` contains a brief description of the error, and `detail` provides 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/SOAP.md#locale) parameter.

## Related information

- [Simple Object Access Protocol (SOAP) 1.1](http://www.w3.org/TR/soap11/)
- [Web Services Description Language (WSDL) 1.1](http://www.w3.org/TR/wsdl/)