Conversion Tracking API

The Conversion Tracking API is used to help enterprises accurately measure the actual conversion performance of OTP (One‑Time Password) SMS messages on the user side. Because international SMS delivery receipts are often affected by multiple factors such as Operator regulations and regional compliance, making accurate tracking difficult, enterprises can use this API to report in real-time whether a user has successfully converted (e.g., successful login or verification). This allows PaaSoo to better assist you in tracking SMS quality, optimizing communication channels, and enhancing the user experience.

1. Invocation Method

Invocation Method

HTTP Method: POST
Content-Type: application/json
Request URL: https://api.paasoo.com/conversion

2. Use Cases and Importance

After sending an OTP SMS to a user, international SMS delivery receipts often experience delays or inaccuracies. Enterprises can use this API to proactively inform PaaSoo of the actual verification result of the user's subsequent actions (for example, if the user entered the correct verification code within a specified time, it indicates the SMS was successfully converted). This helps to:

Assist in Quality Management: By combining the user's actual verification actions, it helps judge the actual performance across different countries/regions, Operators, or Carrier routes;
Cost Optimization: Identify Carrier routes with a low Conversion Rate and make timely adjustments to reduce overall costs;
Win-win Cooperation: PaaSoo can continuously optimize SMS sending quality and user experience based on actual conversion results.

3. Request Example

cURL
curl -X POST "https://api.paasoo.com/conversion" \ 
    -H "Content-Type: application/json" \ 
    -d '{ "key": "Abcdefgh", "secret": "Abc123EF", "messageid": "015bd4-d6dfa7-58w", "conversionTime": "2022-02-22T01:00:01.000Z", "conversion": 1 }'

Where:

Content-Type must be application/json
The request body is in JSON format, containing the required fields for this API.

4. Request Parameters

Parameter	Type	Required	Description	Example
key	string	Yes	API Key (composed of 8 alphanumeric characters), used to uniquely identify your account. Can be obtained in the PaaSoo client console.	Abcdefgh
secret	string	Yes	API Secret (composed of 8 alphanumeric characters), used in conjunction with `key` for authentication. Can be obtained in the PaaSoo client console.	Abc123EF
messageid	string	Yes	Message ID, the unique identifier for each SMS record. Enterprises can obtain this ID via the SMS API.	00018f-e4bf51-e002
conversionTime	string	No	Conversion time, using the ISO8601 standard format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z') in the UTC+0 timezone. Defaults to the UTC time when the API request reaches the server.	2022-02-22T01:00:01.000Z
conversion	integer	Yes	The conversion status of the message: 0 - Conversion failed; 1 - Conversion successful	1

Important Notes:

The conversion time must use the correct UTC timezone format, otherwise the system may experience a time discrepancy.
Since this API authenticates via key and secret, please make sure to call it from your server side and keep the credentials secure to avoid exposing them on the frontend.
If you cannot accurately capture the user's action time, you can choose not to pass conversionTime, and the system will automatically record it as the UTC time when the server received the request.

5. Response Parameters

After the conversion tracking request is submitted, the system will return a corresponding status code to confirm whether the request was successfully received and processed.

Parameter	Type	Description	Example
status	string	Response status. The status code submitted to the PaaSoo cloud communication platform. 0 - success: Success 2 - Missing parameters: Required parameters are missing 3 - Invalid parameters: Parameter format error 4 - Invalid credentials: API Key or API Secret error 11 - System error: System error	"0"
status_details	string	Status description, used to explain the error reason or detailed information.	Missing parameters

Below are common response examples:

5.1 Success Example

{ "status": "0", "status_details": "success"}

5.2 Failure Example

{ "status": "2", "status_details": "Missing parameters."}

6. Common Errors and Troubleshooting

2 - Missing parameters: Check if key, secret, messageid, or other required fields are missing.
3 - Invalid parameters: Parameter format error, such as conversion not being an integer, or the time format not complying with ISO8601.
4 - Invalid credentials: API Key or API Secret do not match, please verify the correctness of your credentials.
11 - System error: Internal server error, such as server processing exceptions or failure to parse the request. If this occurs multiple times, please contact technical support.

7. Code Examples

The following examples show how to call this API using common programming languages:

Python
Node.js
PHP
Java
Go

import requests

# API Endpoint
url = "https://api.paasoo.com/conversion"

# Request Payload
payload = {
    "key": "API_KEY",                             # Replace with your API Key
    "secret": "API_SECRET",                       # Replace with your API Secret
    "messageid": "015bd4-d6dfa7-58w",             # Message ID from the SMS API
    "conversionTime": "2022-02-22T01:00:01.000Z", # Optional: UTC time in ISO8601 format
    "conversion": 1                               # 1 for success, 0 for failure
}

# Request Headers
headers = {
    "Content-Type": "application/json"
}

try:
    # Send HTTP POST request
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    
    # Parse and print JSON response
    data = response.json()
    if data.get("status") == "0":
        print("Conversion reported successfully:", data.get("status_details"))
    else:
        print(f"Report failed, status: {data.get('status')}, details: {data.get('status_details')}")

except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

const axios = require('axios'); // Run: npm install axios

// API Endpoint
const url = 'https://api.paasoo.com/conversion';

// Request Payload
const data = {
    key: 'API_KEY',                             // Replace with your API Key
    secret: 'API_SECRET',                       // Replace with your API Secret
    messageid: '015bd4-d6dfa7-58w',             // Message ID from the SMS API
    conversionTime: '2022-02-22T01:00:01.000Z', // Optional: UTC time in ISO8601 format
    conversion: 1                               // 1 for success, 0 for failure
};

// Send HTTP POST request
axios.post(url, data, {
    headers: {
        'Content-Type': 'application/json'
    }
})
.then((response) => {
    const result = response.data;
    if (result.status === '0') {
        console.log('Conversion reported successfully:', result.status_details);
    } else {
        console.log('Report failed, status:', result.status, 'details:', result.status_details);
    }
})
.catch((error) => {
    console.error('Request failed:', error.message || error);
});

<?php

// API Endpoint
$url = "https://api.paasoo.com/conversion";

// Request Payload
$data = [
    "key" => "API_KEY",                             // Replace with your API Key
    "secret" => "API_SECRET",                       // Replace with your API Secret
    "messageid" => "015bd4-d6dfa7-58w",             // Message ID from the SMS API
    "conversionTime" => "2022-02-22T01:00:01.000Z", // Optional: UTC time in ISO8601 format
    "conversion" => 1                               // 1 for success, 0 for failure
];

$jsonData = json_encode($data);

// Initialize cURL session
$ch = curl_init($url);

// Set cURL options (POST and application/json)
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Content-Length: " . strlen($jsonData)
]);

// Execute request
$response = curl_exec($ch);

if($e = curl_error($ch)) {
    echo "Request failed: " . $e;
} else {
    $result = json_decode($response, true);
    if (isset($result['status']) && $result['status'] === "0") {
        echo "Conversion reported successfully: " . $result['status_details'] . "\n";
    } else {
        echo "Report failed, status: " . $result['status'] . ", details: " . $result['status_details'] . "\n";
    }
}

// Close cURL session
curl_close($ch);
?>

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.MediaType;
import okhttp3.Response;
import java.io.IOException;

// Make sure to add the OkHttp dependency in your pom.xml or build.gradle
public class ConversionApiExample {
    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient();

        // JSON Payload
        String jsonPayload = "{"
                + "\"key\": \"API_KEY\","
                + "\"secret\": \"API_SECRET\","
                + "\"messageid\": \"015bd4-d6dfa7-58w\","
                + "\"conversionTime\": \"2022-02-22T01:00:01.000Z\","
                + "\"conversion\": 1"
                + "}";

        // Create RequestBody
        MediaType JSON = MediaType.parse("application/json; charset=utf-8");
        RequestBody body = RequestBody.create(JSON, jsonPayload);

        // Build request
        Request request = new Request.Builder()
                .url("https://api.paasoo.com/conversion")
                .post(body)
                .addHeader("Content-Type", "application/json")
                .build();

        // Execute request
        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                System.out.println("Response: " + response.body().string());
            } else {
                System.out.println("Request failed, status code: " + response.code());
            }
        } catch (IOException e) {
            System.err.println("Request failed: " + e.getMessage());
        }
    }
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    apiURL := "https://api.paasoo.com/conversion"

    // Prepare JSON Payload
    payload := map[string]interface{}{
        "key":            "API_KEY",                    // Replace with your API Key
        "secret":         "API_SECRET",                 // Replace with your API Secret
        "messageid":      "015bd4-d6dfa7-58w",          // Message ID from the SMS API
        "conversionTime": "2022-02-22T01:00:01.000Z",   // Optional: UTC time in ISO8601 format
        "conversion":     1,                            // 1 for success, 0 for failure
    }

    jsonData, err := json.Marshal(payload)
    if err != nil {
        fmt.Println("Error encoding JSON:", err)
        return
    }

    // Send HTTP POST request
    req, err := http.NewRequest("POST", apiURL, bytes.NewBuffer(jsonData))
    if err != nil {
        fmt.Println("Error creating request:", err)
        return
    }
    req.Header.Add("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Request failed:", err)
        return
    }
    defer resp.Body.Close()

    // Read response body
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("Error reading response:", err)
        return
    }

    // Parse JSON
    var result map[string]interface{}
    if err := json.Unmarshal(body, &result); err != nil {
        fmt.Println("Error parsing JSON:", err)
        return
    }

    // Check status
    if status, ok := result["status"].(string); ok && status == "0" {
        fmt.Println("Conversion reported successfully:", result["status_details"])
    } else {
        fmt.Printf("Report failed, status: %v, details: %v\n", result["status"], result["status_details"])
    }
}

Note: The parameters in the above code are examples and should be replaced with your actual parameter values.

Any language or framework that supports HTTP/HTTPS and can send JSON formatted requests can easily integrate with this API. Simply submit the corresponding parameters using the same request method (POST + Content-Type: application/json).

8. Best Practices and Notes

Security Management:
- Never expose your API Key and API Secret on the client side (e.g., frontend browsers, frontend logic of mobile Apps); please call the API from your backend server.
Data Validity:
- Ensure the messageid matches the ID returned when the SMS was sent, in order to accurately establish the conversion association.
Time Format:
- Try to use the ISO8601 standard time format and ensure it is in the UTC+0 timezone.
Accuracy and Timeliness:
- If your system can only report after a certain period following a user's success or failure, you can record the local time and pass it as conversionTime. The more timely the report, the more helpful it is for SMS quality analysis.
Batch Updates:
- If you need to report massive amounts of conversion information in a high-concurrency environment, please reasonably plan the API invocation frequency and negotiate with PaaSoo to see if additional bandwidth or higher concurrency capabilities are needed.

9. FAQ

What if I cannot get the exact time of the user's action?

You can choose not to pass the conversionTime field, and the system will use the time the request arrives as the conversion time.

If I have a large number of conversion records to report at once, will it cause a timeout?

It is recommended to schedule them in batches to ensure network and server stability. If large-scale concurrency support is required, you can contact PaaSoo to negotiate a solution.

After reporting the conversion, how will PaaSoo process this data?

PaaSoo will aggregate and analyze this data to help you optimize SMS communication channels and costs, and may also include it in statistical reports.

Can conversion include more statuses?

Currently, it only distinguishes between success (1) and failure (0). If you have more detailed requirements, you can communicate with the PaaSoo support team.

How do I associate it with the messageid in the SMS API?

As long as the messageid is identical to the ID returned by the SMS API, a one-to-one association is completed. Please securely store the messageid from the response when sending the SMS.

Support

If you encounter any technical issues or have business inquiries during the API integration, please do not hesitate to contact our Support team at support@paasoo.com. We are always here to assist you.

1. Invocation Method​

2. Use Cases and Importance​

3. Request Example​

4. Request Parameters​

5. Response Parameters​

5.1 Success Example​

5.2 Failure Example​

6. Common Errors and Troubleshooting​

7. Code Examples​

8. Best Practices and Notes​

9. FAQ​