USERDOCS

Firano

A tool and a separate service designated for working with offers, for which you can send applications to advertisers through API.

This service checks the contents of applications received from publishers and sends them to advertisers. Firano has an API designated for interaction with it.

Firano process

After an application receipt the advertiser reviews it and personally contacts the applicant. Firano does not participate in this process.

An application consists of the minimum set of personal data of a publisher’s website visitor that are necessary for the advertiser to make a decision on providing the applicant with a specific service.

The application must contain a minimum and compulsory data, based on which the initial validation by our system will be executed before sending the application to the advertiser.

See also

The minimum application requirements are provided in the Request section.

One application can be sent to different advertisers specified by the publisher. If the application complies with the parameters of at least one advertiser, it is added to the queue for sending to this advertiser. If the application simultaneously complies with the parameters of several advertisers, it will be sent to all these advertisers.

Application processing

Attention

Please note that currently Firano works only with traffic from Russia. Applications from any other country will be rejected.

Completed applications are sent to Firano, and the service processes them in accordance with a specific logic.

  1. First, the application passes an initial check at Firano. The service validates the application fields that were received in the request. If the fields are completed incorrectly or the data is insufficient, the application will not be transferred to the next stage.

  2. Next, Firano selects appropriate offers for this application.

    1. First, these offers must be approved by the publisher who sent the request.

      For example, the publisher can disable sending applications to certain advertisers.

    2. Secondly, the applicant data transferred to Firano must be sufficient to send the application to a specific advertiser.

      For example, the publisher selected an offer from a certain advertiser for sending applications, but a publisher’s website did not complete the required field, and the application was not sent to this advertiser.

      how Firano selects offers

Working with Firano

In order to start working with Firano, you shall set up request sending with the necessary application data.

Authentication

Attention

Please note that the Firano API token differs from the CityAds API token.

Firano uses unique tokens to authenticate publishers. A token is generated automatically and uses your wm_id from the system. This token must be obligatory passed in the request in the token parameter.

Receiving id and Firano API token

In order to get an identification number and a key, you need to enter Firano | Request Builder and press Generate.

Firano credentials

Request

The system allows to work with Firano in the test mode. In order to test the request, you can enable the test mode by checking the sandbox flag, or by specifying the sandbox GET-parameter:

  • sandbox = 1, test mode. The test mode allows to send test applications and receive responses from our server without sending applications to advertisers.
  • sandbox = 0, operational mode of the service.
``sandbox`` switch

The application data is transferred by the publisher via URL https://finance.cityads.com/api/rest/v2/applications.json

Mandatory fields

See also

Additional (optional) fields that can be processed by Firano are listed here.

After receipt of a request with application data, Firano performs an initial check of the transferred values. Before sending this application to advertisers, in order for the application to pass the initial check by Firano, the mandatory fields must be transferred correctly.

Parameter Type Description Value
surname string Surname Only Russian letters, hyphen and space
name string Name Only Russian letters, hyphen and space
mobile string Mobile phone Phone number in the format: +7(xxx)xxx-xx-xx
is_agree_personal boolean Consent to data processing  

Response

Response codes of the Firano service are listed below. If Firano sends error messages and you are unable to eliminate them using the instructions, please contact technical support.

Response Explanation
{
  "application": {
    "id": 4524772
  }
}

Application received successfully.

If the application was successful, Firano will return a response containing the application number after checking the data.

{
  "error": {
    "code": 401,
    "message": "Authorize Failed",
    "errors": {
      "token": "Publisher not found"
    }
  }
}

Incorrect token or wm_id.

This error indicates that you are transferring incorrect authentication data. Change your token (token) or id (wm_id).

For details see Authentication section.

{
  "error": {
    "code": 400,
    "message": "Validation Failed",
    "errors": {
      "surname": "Value must not be empty"
    }
  }
}

Data entry error.

This error indicates that application fields contain incorrect data.

Check the values in accordance with the table Mandatory fields.

Query builder

In order to work with the Query builder, the publisher must use the following algorithm:

  1. Open Firano | Query builder.

  2. Select types of products for which applications from website visitors will be sent to advertisers.

    Firano query builder
  3. Create a personal set of fields that will be sent to advertisers. When a publisher selects certain fields, the Query builder will display a list of offers for which this field set is suitable.

  4. Create a personalized list of offers, according to which applications from website visitors will be sent to advertisers.

    Firano query builder

Code example

When you select the product types, create a set of fields and a personalized list of offers, Firano will generate a sample request body in JSON format and a sample code for configuring the API on your site.

Firano code example
  1. In order to perform a quick copy of the sample request body in JSON, you can click Copy JSON.
  2. In order to perform a quick copy of the sample code, you can click Copy entire code.

Orders database

The Firano | Orders database section contains all your applications sent to various advertisers by Firano. In this section, you can view applications as “With grouping by request” and “No grouping”.

When viewing applications “With grouping by request”, the following information is displayed:

  1. Request ID – a unique number of the application that was transferred to Firano from the publisher.
  2. Offer – a name of the offer to which Firano sent the application.
  3. Status – a status of application delivery to advertisers from Firano: delivered for all offers, not delivered for all offers.
  4. Subaccount – a parameter transferred from the publisher.
  5. Creation date – a date of application sending to the advertiser
Firano orders with grouping

When viewing applications “No grouping”, the following information is displayed:

  1. Subscription ID – a unique number of the application that was transferred to Firano from the publisher.
  2. Offer – a name of the offer to which Firano sent the application.
  3. Bank status – an application status from the advertiser: received, loan denied, duplicate request, error, etc.
  4. Subaccount – a parameter transferred from the publisher.
  5. Creation date – a date of application sending to the advertiser
Firano orders without grouping