Phone Number (PII) Protection Endpoint


METHOD: POST
ENDPOINT: https://dev.qupass.in/api/phone

Description

The Phone Number endpoint enables the protection and unprotection of telecommunication identifiers while preserving their numeric character domain.

The returned token consists exclusively of decimal digits (0–9), ensuring compatibility with systems that operate on numeric-only representations, while allowing for an expanded length to accommodate secure, high-entropy token generation.

By maintaining the same encoding space — specifically the decimal digit domain — the endpoint ensures that protected values remain syntactically valid within numeric processing environments, even though the original formatting (e.g., country codes, plus signs, spaces, or hyphen-separated groupings such as “+91 756-6453546”) and length constraints are not retained.

This approach enables strong protection guarantees without introducing non-numeric characters, while supporting storage, indexing, and processing workflows that rely on numeric-only data representations.

Examples

  • Input: +91 756-6453546 (Numeric)
    • QuFold_Token: 75112492314185636 234458932644155226
      • ✅ Character set preserved (Numeric block)
      • ✅ Encoding compatibility is maintained
    • FPE_Token: +71 672-9741424
      • ✅ Length and Character set preserved (Numeric block)
      • ✅ Encoding compatibility is maintained


Request Payload


  • HEADER PARAMETERS
    • x-api-key (required) Provides access to one or more functions in the API Playground.
    • Authorization (required) The JWT token issued upon successful authentication.
    • qu-token (required) QU token that you revceive at the time of login.

  • PAYLOAD DETAILS
    • id (required) Integer identifier for the request.
    • operation (required) Specifies the protection operation. Available: [protect | unprotect].
    • data (required) Array of values to be transformed.
    • options:
      • method - Transformation method; Available: [tokenise | fpe | mask | redact | passthrough].
        • Defaults to tokenise
      • scope - User-defined context string; differentiates tokens across applications or datasets. (e.g., app1, azure+app1).
        • Defaults to no-scope
      • noise - Adds controlled randomness.
        • Defaults to 0, ensures deterministic tokenization within scope
        • Non-zero values produce possible distinct tokens for the repeated inputs


Sample Request


    curl --location 'https://dev.qupass.in/api/phone' \
    --header 'x-api-key: <API_Key>' \
    --header 'Authorization: <JWT_TOKEN>' \
    --header 'qu-token: <QU_TOKEN>' \
    --header 'Content-Type: application/json' \
    --data '{
      "id": 1,
      "operation": "protect",
      "data": [
          "+91 756-6453546",
          "+97 756-6453547",
          "+01 775-3948593"
      ],
      "options": {
        "method": "tokenise",
        "scope": "App1"
      }
    }'
    package main

    import ( 
      "io" 
      "fmt"
      "strings" 
      "net/http" 
      )
      
    func main() { 
      API_Key := "<API_Key>"
      JWT_Token := "<JWT_TOKEN>"
      QU_Token := "<QU_TOKEN>"
      
      url := "https://dev.qupass.in/api/phone"
      data := strings.NewReader(`{ 
          "id":1,
          "operation": "protect", 
          "data": [
              "+91 756-6453546",
              "+97 756-6453547",
              "+01 775-3948593"
          ],
          "options": {
            "method": "tokenise",
            "scope": "App1"
          } 
      }`)

      req, err := http.NewRequest("POST", url, data)
      if err != nil {
        fmt.Println(err)
        return
      }

      req.Header.Set("x-api-key", API_Key)
      req.Header.Set("Authorization", JWT_Token)
      req.Header.Set("qu-token", QU_Token)
      req.Header.Set("Content-Type", "application/json")

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

      body, err := io.ReadAll(resp.Body)
      if err != nil {
        fmt.Println(err)
        return
      }

      fmt.Println(string(body))
    }
    import java.net.HttpURLConnection;
    import java.net.URI;
    import java.net.URL;
    import java.io.OutputStream;
    import java.io.InputStreamReader;
    import java.io.BufferedReader;
    import java.nio.charset.StandardCharsets;

    public class APIRequest {
        public static void main(String[] args) {
            try {
                String API_Key = "<API_Key>";
                String JWT_Token = "<JWT_TOKEN>";
                String QU_Token = "<QU_TOKEN>";

                URI uri = new URI("https://dev.qupass.in/api/phone");

                String data = "{"
                        + "\"id\": 1,"
                        + "\"operation\": \"protect\","
                        + "\"data\": ["
                        + "\"+91 756-6453546\","
                        + "\"+97 756-6453547\","
                        + "\"+01 775-3948593\""
                        + "],"
                        + "\"options\": {"
                        + "\"method\": \"tokenise\","
                        + "\"scope\": \"App1\""
                        + "}"
                        + "}";

                URL url = uri.toURL();
                HttpURLConnection conn = (HttpURLConnection) url.openConnection();

                conn.setRequestMethod("POST");
                conn.setRequestProperty("x-api-key", API_Key);
                conn.setRequestProperty("Authorization", JWT_Token);
                conn.setRequestProperty("qu-token", QU_Token);
                conn.setRequestProperty("Content-Type", "application/json");
                conn.setDoOutput(true);

                // Send request body
                try (OutputStream os = conn.getOutputStream()) {
                    byte[] input = data.getBytes(StandardCharsets.UTF_8);
                    os.write(input, 0, input.length);
                }

                int statusCode = conn.getResponseCode();

                BufferedReader br;
                if (statusCode >= 200 && statusCode < 300) {
                    br = new BufferedReader(new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8));
                } else {
                    br = new BufferedReader(new InputStreamReader(conn.getErrorStream(), StandardCharsets.UTF_8));
                }

                StringBuilder response = new StringBuilder();
                String line;
                while ((line = br.readLine()) != null) {
                    response.append(line.trim());
                }

                System.out.println(response.toString());

            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    }
    const API_Key = "<API_Key>";
    const JWT_Token = "<JWT_TOKEN>";
    const QU_Token = "<QU_TOKEN>";

    const url = "https://dev.qupass.in/api/phone";

    const data = {
      id: 1,
      operation: "protect",
      data: [
        "+91 756-6453546",
        "+97 756-6453547",
        "+01 775-3948593"
      ],
      options: {
        method: "tokenise",
        scope: "App1"
      }
    };

    fetch(url, {
      method: "POST",
      headers: {
        "x-api-key": API_Key,
        "Authorization": JWT_Token,
        "qu-token": QU_Token,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(data)
    })
      .then(async (response) => {
        const text = await response.text(); // raw response like Python's response.text
        if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${text}`);
        }
        console.log(text);
      })
      .catch((error) => {
        console.error("Error:", error.message);
      });
    <?php

    $API_Key = "<API_Key>";
    $JWT_Token = "<JWT_TOKEN>";
    $QU_Token = "<QU_TOKEN>";

    $url = "https://dev.qupass.in/api/phone";

    $headers = [
        "x-api-key: $API_Key",
        "Authorization: $JWT_Token",
        "qu-token: $QU_Token",
        "Content-Type: application/json"
    ];

    $data = [
        "id" => 1,
        "operation" => "protect",
        "data" => [
            "+91 756-6453546",
            "+97 756-6453547",
            "+01 775-3948593"
        ],
        "options" => [
            "method" => "tokenise",
            "scope" => "App1"
        ]
    ];

    $ch = curl_init($url);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

    $response = curl_exec($ch);

    if (curl_errno($ch)) {
        echo 'Error:' . curl_error($ch);
    } else {
        echo $response;
    }

    curl_close($ch);
    ?>
    import requests
    import json

    API_Key = "<API_Key>"
    JWT_Token = "<JWT_TOKEN>"
    QU_Token = "<QU_TOKEN>"

    url = 'https://dev.qupass.in/api/phone'
    headers = {
      'x-api-key': API_Key,
      'Authorization': JWT_Token,
      'qu-token': QU_Token,
      'Content-Type': 'application/json'
    }

    data = {
      "id": 1,
      "operation": "protect",
      "data": [
        "+91 756-6453546",
        "+97 756-6453547",
        "+01 775-3948593"
      ],
      "options": {
        "method": "tokenise",
        "scope": "App1"
      }
    }

    response = requests.post(url, headers=headers, data=json.dumps(data))
    print(response.text)


Sample Data Payload and Output


PROTECTION SCENARIOS:

InputOutput
  {
    "operation": "protect",
    "data": [
        "+91 756-6453546",
        "+91 756-6453546",
        "+97 756-6453547",
        "+01 775-3948593"
    ],
    "method": "*" // [tokenise, fpe, .,]
  }
    {
      "operation": "protect",  
      "result": [
          "48709622775688399 364334564433077442",
          "48709622775688399 364334564433077442",
          "53043844289832802 692564720029292662",
          "568064924248448872 900886007620828883"
      ],
      "method": "tokenise"
    }
    {
      "operation": "protect",  
      "result": [
          "8558523628996675409489 3782266288724092923944",
          "8558523628996675409489 3782266288724092923944",
          "0559388084735635984645 4925948425923579309436",
          "4757536243446350698280 80489829900666485452036"
      ],
      "method": "tokenise",
      "scope": "App1" //SCOPE
    }
    {
      "operation": "protect",  
      "result": [
          "676588230703858885 7840250677786956036",
          "590725666435253709 6856698069072779976",
          "775996909568495373 8483499225746835576",
          "5586757424855399429 6607760343830552394"
      ],
      "method": "tokenise",
      "noise": "2" //NOISE
    }
    {
      "operation": "protect",  
      "result": [
          "85809608536606060300558 57824332655586898245577",
          "85809608536606060300558 57824332655586898245577",
          "4840907672875480622687 74985726028328933904932",
          "96023525923222786232998 922802552755954663025035"
      ],
      "method": "tokenise",
      "scope": "App1", //SCOPE
      "noise": "2" //NOISE
    }
    {
      "operation": "protect",  
      "result": [
          "+71 672-9741424",
          "+71 672-9741424",
          "+24 778-2618397",
          "+78 666-1548743"
      ],
      "method": "fpe" // FPE
    }

UNPROTECTION SCENARIOS:

InputOutput
  {
    "operation": "unprotect",
    "data": [
        "48709622775688399 364334564433077442",
        "48709622775688399 364334564433077442",
        "53043844289832802 692564720029292662",
        "568064924248448872 900886007620828883"
    ],
    "method": "tokenise"
  }
    {
      "operation": "unprotect",  
      "result": [
          "+91 756-6453546",
          "+91 756-6453546",
          "+97 756-6453547",
          "+01 775-3948593"
      ]
    }
  {
    "operation": "unprotect",
    "data": [
        "48709622775688399 364334564433077442",
        "4870962277588399 364334564433077442",
        "53043844289832802 692564720029292662",
        "568064924248448872 900886007620828883"
    ],
    "method": "tokenise"
  }
    {
      "operation": "unprotect",  
      "result": [
          "+91 756-6453546",
          "4870962277588399 364334564433077442", //INVALID
          "+97 756-6453547",
          "+01 775-3948593"
      ],
      "discrepancy": {
        "invalid_token": [ //INVALID
          1 // INDEX
        ]
      }
    }
  {
    "operation": "unprotect",
    "data": [
        "48709622775688399 364334564433077442",
        "48709622775688399 364334564433077442",
        "53043844289832802 692564720029292662",
        "568064924248448872 900886007620828883"
    ],
    "scope":"App2", //INVALID
    "method": "tokenise"
  }
    {
      "operation": "unprotect",  
      "result": [
          "48709622775688399 364334564433077442",
          "48709622775688399 364334564433077442",
          "53043844289832802 692564720029292662",
          "568064924248448872 900886007620828883"
      ],
      "discrepancy": {
        "invalid_scope": [ // INVALID
          0, // INDEX
          1,
          2,
          3
        ]
      }
    }
  {
    "operation": "unprotect",
    "data": [
        "+71 672-9741424",
        "+71 672-9741424",
        "+24 778-2618397",
        "+78 666-1548743"
    ],
    "method": "fpe"
  }
    {
      "operation": "unprotect",  
      "result": [
          "+91 756-6453546",
          "+91 756-6453546",
          "+97 756-6453547",
          "+01 775-3948593"
      ]
    }