2.2.1 REST API Endpoints

Requests and Responses

• Our API is a REST API.
• We use json for all request and response bodies.
• Rate limit applied to all inbound requests. (Soon the detail will be provided)

HTTP Response Codes

When calling VerifySpeed endpoints and facing HTTP errors, the following HTTP response codes may be returned based on errors during request processing:

• 400: Missing or invalid input data.
  • Example: Requesting for creating verification with an inactive method.
• 401: Authentication failure.
  • Example: Missing or invalid server-key in the request.
• 403: Authorization failure.
  • Example: Attempting to access another user's data.
• 404: Resource not found.
  • Example: Using a non-existent method name.

For non-success HTTP responses (e. g., status codes outside 200-299), the response body follows the format defined by RFC 9457.

Possible Error Responses:

When provided server key is invalid server key

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Application not found",
  "status": 404,
  "errors": [
    "server-key": ["Invalid server key"]
  ]
}

When something goes wrong during verification process

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Invalid request, please contact support. (error code: VF0001)",
  "status": 400,
  "errors": []
}

Creating Phone Number Verification

Initialization

Endpoint: GET https://api.verifyspeed.com/v1/verifications/initialize

Request Headers:

• server-key: Server key obtained from the [dashboard].
• client-ipv4-address: The client’s IPv4 address.

cURL

curl -X GET "https://api.verifyspeed.com/v1/verifications/initialize" \
  -H "server-key: YOUR_SERVER_KEY" \
  -H "client-ipv4-address: 192.168.1.1"

C#

using System.Net.Http;
using System.Threading.Tasks;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("server-key", "YOUR_SERVER_KEY");
client.DefaultRequestHeaders.Add("client-ipv4-address", "192.168.1.1");

var response = await client.GetAsync("https://api.verifyspeed.com/v1/verifications/initialize");
var content = await response.Content.ReadAsStringAsync();

Go

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, err := http.NewRequest("GET", "https://api.verifyspeed.com/v1/verifications/initialize", nil)
    if err != nil {
        panic(err)
    }
    
    req.Header.Set("server-key", "YOUR_SERVER_KEY")
    req.Header.Set("client-ipv4-address", "192.168.1.1")
    
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }
    
    fmt.Println(string(body))
}

Node.js

const axios = require('axios');

const response = await axios.get('https://api.verifyspeed.com/v1/verifications/initialize', {
  headers: {
    'server-key': 'YOUR_SERVER_KEY',
    'client-ipv4-address': '192.168.1.1'
  }
});

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.verifyspeed.com/v1/verifications/initialize");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "server-key: YOUR_SERVER_KEY",
    "client-ipv4-address: 192.168.1.1"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>

Python

import requests

headers = {
    'server-key': 'YOUR_SERVER_KEY',
    'client-ipv4-address': '192.168.1.1'
}

response = requests.get('https://api.verifyspeed.com/v1/verifications/initialize', headers=headers)

Response (200 OK):

{
  "availableMethods": [
    {
      "methodName": "string",
      "displayName": "string"
    }
  ]
}

• availableMethods: A list of available verification methods for the client. (See Verification Methods for more details)
  • methodName: Identifier for the verification method (e.g., whatsapp-messege).
  • displayName: Display name of the method (e.g., WhatsApp Message).

---

Creating the Verification

Endpoint: Post https://api.verifyspeed.com/v1/verifications/create

Request Headers:

• server-key: Server key obtained from the [dashboard].
• client-ipv4-address: The client’s IPv4 address.

cURL

curl -X POST "https://api.verifyspeed.com/v1/verifications/create" \
  -H "server-key: YOUR_SERVER_KEY" \
  -H "client-ipv4-address: 192.168.1.1" \
  -H "Content-Type: application/json" \
  -d '{
    "methodName": "whatsapp-message",
    "language": "en"
  }'

C#

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("server-key", "YOUR_SERVER_KEY");
client.DefaultRequestHeaders.Add("client-ipv4-address", "192.168.1.1");

var requestBody = new { methodName = "whatsapp-message", language = "en" };
var json = JsonSerializer.Serialize(requestBody);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync("https://api.verifyspeed.com/v1/verifications/create", content);

Go

package main

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

func main() {
    client := &http.Client{}
    
    requestBody := map[string]string{
        "methodName": "whatsapp-message",
        "language":  "en",
    }
    
    jsonData, err := json.Marshal(requestBody)
    if err != nil {
        panic(err)
    }
    
    req, err := http.NewRequest("POST", "https://api.verifyspeed.com/v1/verifications/create", bytes.NewBuffer(jsonData))
    if err != nil {
        panic(err)
    }
    
    req.Header.Set("server-key", "YOUR_SERVER_KEY")
    req.Header.Set("client-ipv4-address", "192.168.1.1")
    req.Header.Set("Content-Type", "application/json")
    
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }
    
    fmt.Println(string(body))
}

Node.js

const axios = require('axios');

const response = await axios.post('https://api.verifyspeed.com/v1/verifications/create', {
  methodName: 'whatsapp-message',
  language: 'en'
}, {
  headers: {
    'server-key': 'YOUR_SERVER_KEY',
    'client-ipv4-address': '192.168.1.1'
  }
});

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.verifyspeed.com/v1/verifications/create");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "server-key: YOUR_SERVER_KEY",
    "client-ipv4-address: 192.168.1.1",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'methodName' => 'whatsapp-message',
    'language' => 'en'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>

Python

import requests
import json

headers = {
    'server-key': 'YOUR_SERVER_KEY',
    'client-ipv4-address': '192.168.1.1'
}

data = {
    'methodName': 'whatsapp-message',
    'language': 'en'
}

response = requests.post('https://api.verifyspeed.com/v1/verifications/create', 
                        headers=headers, 
                        json=data)

• methodName: The selected verification method (required) (e.g., whatsapp-messege). (See Verification Methods for more details)
• language: The language to be used (Optional) (e.g., en).

Notes:

• The phone number must be in E.164 format (e.g. +14255552673 (1 is country code))
• Supported languages for now:
  • en for English (Default)
  • ar for Arabic
  • ckb for Central Kurdish

Response (200 OK)

{
  "methodName": "string",
  "verificationKey": "string",
  "deepLink": "string"
}

• methodName: Method name of the used verification method.
• verificationKey: The key that identifies the verification.
• deepLink (nullable): URL to complete verification by deep linking. Not null if methodName is whatsapp-messege or telegram-message.

---

Verification Result

Recommended Approach: Client-side Token Decryption

Instead of calling the verification result endpoint, we recommend that your server decrypts the verification token directly using your server key. This approach is more efficient, secure, and eliminates the need for an additional API call.

How It Works:

1. Client receives encrypted token after completing verification
2. Client sends token to your server (not to VerifySpeed)
3. Your server decrypts the token using your server key
4. Extract verification details directly from the decrypted token

Benefits:

• Faster: No additional API calls to VerifySpeed
• More Secure: Token decryption happens on your server
• Cost Effective: Reduces API usage
• Real-time: Immediate access to verification data

Implementation:

For detailed implementation examples, see Verification Result Documentation which includes:

• Official Packages: Ready-to-use decryption tools for each language
• Manual Implementation: Complete code examples for custom implementations
• Security Best Practices: Token expiry validation and error handling
• Multi-language Support: C#, Node.js, PHP, Python, and Go examples

Alternative: API Endpoint (Not Recommended)

If you still need to use the API endpoint for legacy reasons, here's the implementation:

Endpoint: GET https://api.verifyspeed.com/v1/verifications/result

Request Headers:

• server-key: Server key obtained from the [dashboard].
• token: The verification token received from the client.

cURL

curl -X GET "https://api.verifyspeed.com/v1/verifications/result" \
  -H "server-key: YOUR_SERVER_KEY" \
  -H "token: YOUR_VERIFICATION_TOKEN"

C#

using System.Net.Http;
using System.Threading.Tasks;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("server-key", "YOUR_SERVER_KEY");
client.DefaultRequestHeaders.Add("token", "YOUR_VERIFICATION_TOKEN");

var response = await client.GetAsync("https://api.verifyspeed.com/v1/verifications/result");
var content = await response.Content.ReadAsStringAsync();

Go

package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    client := &http.Client{}
    req, err := http.NewRequest("GET", "https://api.verifyspeed.com/v1/verifications/result", nil)
    if err != nil {
        panic(err)
    }
    
    req.Header.Set("server-key", "YOUR_SERVER_KEY")
    req.Header.Set("token", "YOUR_VERIFICATION_TOKEN")
    
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    body, err := io.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }
    
    fmt.Println(string(body))
}

Node.js

const axios = require('axios');

const response = await axios.get('https://api.verifyspeed.com/v1/verifications/result', {
  headers: {
    'server-key': 'YOUR_SERVER_KEY',
    'token': 'YOUR_VERIFICATION_TOKEN'
  }
});

PHP

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.verifyspeed.com/v1/verifications/result");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "server-key: YOUR_SERVER_KEY",
    "token": "YOUR_VERIFICATION_TOKEN"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>

Python

import requests

headers = {
    'server-key': 'YOUR_SERVER_KEY',
    'token': 'YOUR_VERIFICATION_TOKEN'
}

response = requests.get('https://api.verifyspeed.com/v1/verifications/result', headers=headers)

Response (200 OK):

{
  "methodName": "string",
  "dateOfVerification": "2024-06-24T14:51:02.877Z",
  "phoneNumber": "+12223334455"
}

Response Fields:

• methodName: The method name (e.g., whatsapp-messege) of the verification method used to verify the phone number.
• dateOfVerification: The date and time (in UTC) when the phone number was verified.
• phoneNumber: The verified phone number in E.164 format (e.g. +14255552673 (1 is country code)).