1. Introduction - what is API, when you should use it and requirements

API is server2server connection between you and Volsor. It is used when you have your own system with your own form and you want to send data from your system to Volsor. It allows you to send loan applications with user data directly to Volsor system through HTTP request.

Let's say you have a form for loan applications on your website. When anyone fills in the form, the data is saved on your server. The API is a bridge between your system and ours. It defines, how to send this data to our system. It defines name of the fields (keys), the content of the fields (values), the rules and formats in which the data should be received (validation) and URL where you should send this data (read more in 2.4. Set up format of data sending). It also defines our response format. When data is sent to us via API, we reply whether we accepted the lead successfully (together with URL of the page where you should redirect the client) or whether data failed (either because you missed something or did not use the proper data format). (read more in 2.2.5. Set up response handling).

1.1. Business-cases when you should consider using Volsor API

1. Proprietary website with online form for Loan applications
   
   • For example, you are running a financial website where users can apply for Payday loan or Consumer loans via online form that was NOT developed by Volsor.
2. Software managed by sales team for offline loan requests
   
   • For example, if in your business model people are asking for a loan offline, such as a call center, where application for a loan is created by your sales team and not by the customers themselves. Make sure the software you use is capable to send HTTP request via POST method in proper JSON format and you are able to send data in real-time to Volsor. (Volsor will NOT pay for the leads that are NOT interested in the loan at the moment when you send their data to Volsor Lead API).

1.2. When you should NOT consider using Volsor API (and use other marketing tools instead)

• You have neither proprietary website with a user form nor using any software for managing loan applications
• You want to monetize your existing database of customers who are NOT actively seeking for a loan
• You don't have development team capable to adapt your software according to this documentation requirements (See Chapter 2.2.How to integrate your system with Volsor Lead API). In this case we recommend you to consider alternative marketing tools that are easier and faster to set up, such as Landing Pages, Links, Banners or Iframe forms.
• When you cannot comply with Volsor requirements (see the next section).

1.3. Volsor requirements

In order to send traffic to Volsor, you need:

1. To have a proprietary GDPR-compliant website that targets users interested in Payday or Consumer loan products.
2. In accordance with GDPR, it's necessary that you include Volsor s.r.o. as one of the Data controllers in your Privacy terms.

In the following table you will find the links to all necessary legal documents per country that MUST be agreed by users whose lead data you send to Volsor via API:

Required document	Czech Republic	Spain	Poland
Personal data processing terms	https://financecdn.com/cms/release/landings/cs/conditions/terms-gdpr.html	https://financecdn.com/cms/release/landings/es/conditions/terms-gdpr.html	https://financecdn.com/cms/release/landings/pl/conditions/terms-gdpr.html
Persona data processing agreement	https://financecdn.com/cms/release/landings/cs/conditions/privacy-gdpr.html	https://financecdn.com/cms/release/landings/es/conditions/privacy-gdpr.html	https://financecdn.com/cms/release/landings/pl/conditions/privacy-gdpr.html
Remarketing agreement	https://financecdn.com/cms/release/landings/cs/conditions/remarketing-gdpr.html	https://financecdn.com/cms/release/landings/es/conditions/remarketing-gdpr.html	https://financecdn.com/cms/release/landings/pl/conditions/remarketing-gdpr.html

Leads sent to us from your system should be real people that are actively seeking for a loan at the moment when you send their data to us. We will NOT buy leads sent to us directly from database, if these people are NOT interested in getting a loan at the moment when your send their data to us.

2. How to start using Volsor's API?

1. Apply for using Volsor's Lead API
2. Integrate with our API
3. Test it together with affiliate manager
4. Send traffic

2.1. Apply for using Volsor's Lead API

• Re-check that you website and software complies with all Volsor requirements and make necessary changes before contacting Volsor.
• Contact Volsor Affiliate manager affiliate@volsor.com and provide the following information:
  • Explain your business case.
  • If you have a website, send its URL for revision.
  • Inform the IP address that you will use for sending traffic via API.
• Wait for Volsor's approval. We reserve up to 2 working days for the revision but in most cases we will reply to you on the same working day. If your application is approved we will provide you the valid API token that will enable you to send traffic directly via API.

2.2. How to integrate your system with Volsor Lead API

Under integration we mean that your software flawlessly sends us JSON-encoded data via POST and handles all Volsor's JSON-encoded responses without any problem.

The following steps are step-by-step instruction how to integrate your system with Volsor Lead API.

2.2.1. Select the target market and the product of promotion

Select the target country (CZ for Czech Republic, ES for Spain or PL for Poland) and the product of promotion (Payday or Consumer loan) to see the required and optional fields for the selected country / product combination.

2.2.2. Analyze which fields are needed

Analyze if you can send us all required fields for the selected country / product combination.

2.2.3. Translate fields in your system according to Volsor validation rules

When you send us lead, we validate it according to validation described in every field. If any field does not pass the validation, we will not buy the lead. Therefore, please pay close attention to proper validation of the fields.

2.2.4. Set up authentication and endpoints

Include the API-token provided to you by Volsor manager in the Authorization HTTP header. Make sure that the header is sent exactly as follows:

Authorization: Token <your_api_token>

Otherwise, you will either get HTTP 401 Unauthorized response (See chapter 2.2.5 a. for details) or your leads will NOT be recognized by our system as yours.

API endpoints for lead registration. Every request from your server must be in valid JSON format and have valid Content-Type (application/json) and authorization (described above) headers.

Endpoint	URL	Method
Production	https://api.volsor.com/leads/	POST
Test	https://api-test.volsor.com/leads/	POST

If sent data is valid you will get a JSON response that has a key status with OK value and key redirect_url with link where you need to redirect a lead for further processing. Also response will contain an id, which can be used to check lead status. (See chapter 2.2.5 for details)

2.2.5. Set up response handling

When you are sending lead data (name, amount, period etc.) to the address: https://api.volsor.com/leads/ by using POST method, the most relevant types of responses for you are:

1. Something is wrong with the token (authentication problem)
2. Something is wrong with the lead data (validation problem)
3. Everything is fine. The lead is accepted by the system.

a) Something is wrong with the token (authentication problem)

Example responses, its explanations and recommended actions:

Status code	Response	Explanation	To do for the Affiliate
401	{"detail":"Invalid token"}	API-token that affiliate used for authentication is not valid	Re-check if token is properly spelled in HTTP header while sending leads
401	{"detail":"Token inactive"}	Affiliate is not allowed to send traffic to Volsor	Contact Volsor manager to find out and negotiate conditions to allow sending traffic
401	{"detail":"Authentication credentials were not provided."}	The token is either missing or is not properly set-up	Re-check if correct token is properly placed in HTTP header according to the documentation: Authorization: Token <your_api_token>

All these error responses are returned as HTTP Error.

b) Something is wrong with the lead data (validation problem)

Example responses, their explanations and recommended actions:

Status code	Response	Explanation	To do for the Affiliate
400	{"status": "FAIL", "errors":{"email":["This field is required."]}}	The required field "email" was not sent. Lead is rejected by Volsor	Make sure you send leads that have all "Paid required fields"
400	{"status":"FAIL", "errors":{"identity_card_number":["Valor incorrecto"]}}	The field "identity_card_number" failed Volsor's validation. Lead is rejected	Send data according to Volsor's validation rules in Lead API documentation

In all these cases JSON response will contain the field "status" with "FAIL" value, compare to 1.1. value.

In case of wrong input from the end user (if you are using your own form) - you could display Volsor's error messages to the end users (which are in most cases are already translated into the language of the target country).

In case of data format problems, for example {"errors":{"birth_date":["Date has wrong format. Use one of these formats instead: DDMMYYYY."]... you should make changes in your software to send us data in the proper format according to the documentation. Error messages are localized according to your target country.

c) Everything is fine. The Lead was accepted.

In case of successfully accepted lead, the response will be the following:

Status code	Response	Explanation
201	{"redirect_url":"...", "id":"...", "status":"OK"}	redirect_url - URL of our resource, where the user MUST be redirected so that he could see Thank You Page after sell. id - Unique lead ID in Volsor's system; you should use it for checking lead status (See 2.2.6.) status - Status of the lead in this case will always be ok.

d) Other responses

In some rare cases, you can get the following response:

Status code	Response	Explanation	To do for the Affiliate
500	{"detail":"Internal service error"}	This might indicate one of the following: 1. Volsor is undergoing some routine maintenance on its servers 2. Volsor has some system issues (which in 99,9% cases are already known and being already worked upon)	Repeat your request in several minutes. If the problem persists longer than 60 minutes, you should inform your affiliate manager about the problem.

2.2.6. Set up conversion tracking via API UPDATED 06.02.2020

Please check Conversion tracking section

2.2.7. Set up redirect to thank you page

When Volsor successfully receives your lead and replies with the status OK (see chapter 2.2.5.c Everything is fine. The Lead was accepted) you should redirect the user to the redirect_url that you will find in the response.

2.3. Integration testing

Before sending leads to our production we recommend you to send dummy data to our test endpoint (see chapter 2.2.4)

Please, inform Volsor manager that you have started the test. The test can be considered successful if you:

1. Receive positive response status OK for your lead (see chapter 2.2.5.c)
2. status SOLD when you check the lead status (see chapter 2.2.6)

2.4. Traffic launch

Before launching the traffic, please contact your manager and launch the traffic together with him. In the beginning, it is needed to limit the leads and thoroughly control them. Make sure you change the endpoint to production (see chapter 2.2.4)

2.5. Measure your performance

As soon as your traffic is launched to production endpoint, you can see the performance of your leads in Reports. You can filter the traffic generated from form or API and compare the performance.

3. Troubleshooting

If you experience any problems with API integration, please inform Volsor affiliate manager affiliate@volsor.com by email. In order we could solve your problem as soon as possible, please provide:

1. Description of the problem: what is wrong, when it happens and what behavior would you expect instead.
2. The log of your request and our response as an example of the problem.

curl -H "Content-Type: application/json; charset=utf-8" -H "Authorization: Token <your_api_token>" -X POST -d '{ "agree": "1",  "cell_phone": "736276290",  "country": "CZ",  "email": "admin@volsor.com",  "period": "16",  "product": "payday",  "requested_amount": "2700",  "subaccounts": {"sub1": "FB23095", "sub2": "GGL_22", "sub3": "REF5"},"country": "CZ", "product": "payday"}' https://api-test.volsor.com/leads/

    

{"status":"OK","url":"https://api-test.volsor.com/v2/leads/get_lead_info/94490374-a4a1-48eb-84ae-2f2500671a31/","redirect_url":"https://onpujcka.cz/form.html?key=94490374-a4a1-48eb-84ae-2f2500671a31","id":"94490374-a4a1-48eb-84ae-2f2500671a31"}

$url = "https://api-test.volsor.com/leads/";

$fields = json_encode(array(
    "agree" => "1",
    "cell_phone" => "736276290",
    "country" => "CZ",
    "email" => "admin@volsor.com",
    "period" => "16",
    "product" => "payday",
    "requested_amount" => "2700",
    "subaccounts" => array(
        "sub1" => "FB23095",
        "sub2" => "GGL_22",
        "sub3" => "REF5",
),
));

$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'Authorization: Token <your_api_token>',
    'Content-Type: application/json; charset=utf-8'
));
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $fields);

$return = curl_exec($curl);
curl_close($curl);

$response = json_decode($return);

print_r($response);

    

{"status":"OK","url":"https://api-test.volsor.com/v2/leads/get_lead_info/94490374-a4a1-48eb-84ae-2f2500671a31/","redirect_url":"https://onpujcka.cz/form.html?key=94490374-a4a1-48eb-84ae-2f2500671a31","id":"94490374-a4a1-48eb-84ae-2f2500671a31"}

# coding: utf-8
import json
from urllib.request import Request, urlopen


url = 'https://api-test.volsor.com/leads/'

data = json.dumps({
     'agree': '1',
     'cell_phone': '736276290',
     'country': 'CZ',
     'email': 'admin@volsor.com',
     'period': '16',
     'product': 'payday',
     'requested_amount': '2700',
    'subaccounts': {
        'sub1': 'FB23095',
        'sub2': 'GGL_22',
        'sub3': 'REF5',
},
})
data = data.encode('utf-8')

request = Request(url, data, {'Authorization': 'Token <your_api_token>', 'Content-Type': 'application/json'})
response = urlopen(request)

print(response.read())

    

{"status":"OK","url":"https://api-test.volsor.com/v2/leads/get_lead_info/94490374-a4a1-48eb-84ae-2f2500671a31/","redirect_url":"https://onpujcka.cz/form.html?key=94490374-a4a1-48eb-84ae-2f2500671a31","id":"94490374-a4a1-48eb-84ae-2f2500671a31"}