Publisher API Integration for Lead Generation

Publishers are often interested in sending leads via API. Swaarm has introduced this functionality to streamline the entire process, facilitating seamless automation from the publisher to the advertiser. Employing this method, publishers can efficiently transmit leads to Swaarm.

Lead API Request

The request can be made to the following using the POST method:

https://track.INSERT_DOMAIN_HERE.swaarm-clients.com/leads

JSON Request

The following JSON fields are available:

{
"details": {
  "email": "robert.jones1061843@outlook.com",
  "firstName": "Robert",
  "lastName": "Jones",
  "fullName": "Robert Jones",
  "phoneNumber": "+12694272403",
  "gender": "Prefer not to say",
  "dateOfBirth": "1991-07-21",
  "username": "robert909",
  "password": "Passnlt3hqii",
  "address": "2223 Oak Avenue, New York",
  "freeParameters": {
    "param1": "p1_2s68ok5u",
    "param2": "p2_er8b04pm",
    "param3": "p3_bksi2h00",
    "param4": "p4_ifwrlneg",
    "param5": "p5_1pg1zncv",
    "param6": "p6_cjeh70as",
    "param7": "p7_qswnm6jf",
    "param8": "p8_eueiv3i1",
    "param9": "p9_9nk15cgo",
    "param10": "p10_yzkqbp3k",
    "param11": "p11_7hqf6no5",
    "param12": "p12_naubfvbr",
    "param13": "p13_8958vnp6",
    "param14": "p14_gga0qfu8",
    "param15": "p15_aqr7j7lk",
    "param16": "p16_jjvvmo4u",
    "param17": "p17_wkq414v7",
    "param18": "p18_xjkdmvce",
    "param19": "p19_z94iwnzs"
 }
},
"offer": {
  "id": "123"
},
"publisher": {
  "id": "456",
  "subId": "sub_6866",
  "subSubId": "subsub_474",
  "site": "twitter",
  "app": "Web App"
 }
}

The data needs to be sent with Content-Type: application/json header using the HTTP POST method.

Here is a CURL example:

curl 'https://INSERT_TRACKING_DOMAIN_HERE/leads' \
-H 'user-agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36' \
--data-raw $'{"details":{"email":"robert.jones1061843@outlook.com","firstName":"Robert","lastName":"Jones","fullName":"Robert Jones","phoneNumber":"+12694272403","gender":"Prefer not to say","dateOfBirth":"1991-07-21","username":"robert909","password":"Passnlt3hqii\u0021","address":"2223 Oak Avenue, New York","freeParameters":{"param1":"p1_2s68ok5u","param2":"p2_er8b04pm","param3":"p3_bksi2h00","param4":"p4_ifwrlneg","param5":"p5_1pg1zncv","param6":"p6_cjeh70as","param7":"p7_qswnm6jf","param8":"p8_eueiv3i1","param9":"p9_9nk15cgo","param10":"p10_yzkqbp3k","param11":"p11_7hqf6no5","param12":"p12_naubfvbr","param13":"p13_8958vnp6","param14":"p14_gga0qfu8","param15":"p15_aqr7j7lk","param16":"p16_jjvvmo4u","param17":"p17_wkq414v7","param18":"p18_xjkdmvce","param19":"p19_z94iwnzs"}},"offer":{"id":"21836"},"publisher":{"id":"20865","subId":"sub_6866","subSubId":"subsub_474","site":"twitter","app":"Web App"}}'

GET REQUEST

The following parameters can be added to the query string:

Parameter	Definition	Example
details_fullName	User Full Name	James Robertson
details_firstName	User First Name	James
details_lastName	User Last Name	Robertson
details_email	User Email address	test320@swaarm.com
details_phoneNumber	User phone number	+49738862141
details_freeParameters_param1	Free Parameters 1	examplecode123
details_freeParameters_param2	Free Parameters 2	examplecode123
details_freeParameters_param3	Free Parameters 3	examplecode123
details_freeParameters_param4	Free Parameters 4	examplecode123
details_freeParameters_param5	Free Parameters 5	examplecode123
jsonData	Json Data
offer_id	Swaarm Offer ID	20
publisher_id	Swaarm Publisher ID	5
publisher_subId	Publisher sub source ID	xyz123
publisher_site	Publisher site ID/name	test_site
publisher_app	Publisher App	test_app
geo_country	Country name or Code	US
geo_city	City name or code	New York

Example of API Request for Incoming Lead

The following request is an example how the request should be sent by the publisher in order to create a lead:

https://track.INSERT_DOMAIN_HERE.swaarm-clients.com/leads?fullName=Full+Name+5787&details_email=test320%40swaarm.com&details_phone=%2B49738862141&details_freeParameters_param1=Free+Param1+1621&details_freeParameters_param2=Free+Param2+2287&details_freeParameters_param3=Free+Param3+5829&details_freeParameters_param4=Free+Param4+136&details_freeParameters_param5=Free+Param5+6373&details_freeParameters_param6=Free+Param6+9111&jsonData=&offer_id=16832&publisher_id=18&publisher_subId=subid+8150&publisher_subSubId=subsubid+1861&publisher_site=site+1214&publisher_app=app+5868&geo_country=usa&geo_city=new+york

Uploading Documents: Implementation Guide

If the leads you are sourcing also need to upload docs while submitting their information, the following example can be used as a guide to do so.

Example code:

Below is a simple HTML and JavaScript implementation of a file upload form. This form allows users to select a file, upload it to your designated endpoint, and retrieve the uploaded file URL.

html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>File Upload</title>
</head>
<body>
    <h2>Upload a File</h2>
    <input type="file" id="fileInput">
    <button onclick="uploadFile()">Upload</button>

    <h3>Uploaded File:</h3>
    <a id="fileLink" href="#" target="_blank" style="display:none;">View File</a>

    <script>
        async function uploadFile() {
            const fileInput = document.getElementById("fileInput");
            if (fileInput.files.length === 0) {
                alert("Please select a file!");
                return;
            }

            const formData = new FormData();
            formData.append("file", fileInput.files[0]);

            try {
                const response = await fetch("{INSERT_DOMAIN_HERE}/upload?key={YOUR_API_KEY}", {
                    method: "POST",
                    body: formData
                });

                if (response.ok) {
                    const fileUrl = await response.text();
                    console.log("Uploaded file URL:", fileUrl);

                    // Display file link
                    const fileLink = document.getElementById("fileLink");
                    fileLink.href = fileUrl;
                    fileLink.innerText = "View Uploaded File";
                    fileLink.style.display = "block";
                } else {
                    alert("Upload failed!");
                }
            } catch (error) {
                console.error("Error uploading file:", error);
                alert("An error occurred while uploading the file.");
            }
        }
    </script>
</body>
</html>

Instructions to use the above example:

The domain {INSERT_DOMAIN_HERE} should be replaced by the original domain. If you are working with a Advertiser using Swaarm, please contact them for the domain details
Replace {YOUR_API_KEY} with your publisher's feed API key provided to you by your Advertiser for authentication
Once the document is uploaded, the code implementation above returns a URL that is to be returned by the publisher in one of the above mentioned free parameters (details.freeParameters.param1, details.freeParameters.param2, ... , details.freeParameters.param20). Please check with your advertiser as to which free parameter should be used to send the doc url.

By following the above instructions, customers and publishers can successfully integrate the file upload feature into their systems while ensuring compliance with your tracking and reporting requirements.

✏️ Replace Domain

The domain INSERT_DOMAIN_HERE should be replaced by the original domain.

Publisher Tracking Details

Swaarm & Affise Integration (Both Advertiser and Publisher)

Publisher - Impression Tracking

Privacy-Aware Publisher Integration - Generic

Publisher Stats API Integration