Verify Users

Send verification codes via SMS to phone numbers.

Endpoints

Send Verification Code

Endpoint: POST https://api.sapiom.ai/v1/services/verify/send

Sends a verification code to the specified phone number.

Request:

Parameter	Type	Required	Description
phoneNumber	string	Yes	Phone number in E.164 format (e.g., +15551234567)

Response:

{
  "verificationRequestId": "550e8400-e29b-41d4-a716-446655440000"
}

Check Verification Code

Endpoint: POST https://api.sapiom.ai/v1/services/verify/check

Validates a verification code entered by the user.

Request:

Parameter	Type	Required	Description
verificationRequestId	string	Yes	UUID returned from the send endpoint
code	string	Yes	4-8 digit verification code

Response:

{
  "status": "success"
}

Status Values:

Status	Description
success	Code is correct, verification complete
pending	Verification still in progress
failure	Code is incorrect

Python Example

Here’s a complete example using the requests library:

import requests
import os

API_KEY = os.environ.get("SAPIOM_API_KEY")
BASE_URL = "https://api.sapiom.ai/v1/services"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Send verification code
def send_verification(phone_number: str) -> str:
    """Send a verification code and return the request ID."""
    response = requests.post(
        f"{BASE_URL}/verify/send",
        headers=headers,
        json={"phoneNumber": phone_number}
    )
    response.raise_for_status()

    data = response.json()
    return data["verificationRequestId"]

# Check verification code
def check_verification(request_id: str, code: str) -> bool:
    """Check a verification code. Returns True if valid."""
    response = requests.post(
        f"{BASE_URL}/verify/check",
        headers=headers,
        json={
            "verificationRequestId": request_id,
            "code": code
        }
    )
    response.raise_for_status()

    data = response.json()
    return data["status"] == "success"

# Usage
if __name__ == "__main__":
    phone = "+15551234567"

    # Send the code
    request_id = send_verification(phone)
    print(f"Verification sent. Request ID: {request_id}")

    # In a real app, you'd get this from user input
    user_code = input("Enter the code you received: ")

    # Check the code
    if check_verification(request_id, user_code):
        print("Verification successful!")
    else:
        print("Invalid code.")

Error Handling

import requests

def send_verification_with_error_handling(phone_number: str) -> str | None:
    """Send verification with proper error handling."""
    try:
        response = requests.post(
            f"{BASE_URL}/verify/send",
            headers=headers,
            json={"phoneNumber": phone_number}
        )
        response.raise_for_status()
        return response.json()["verificationRequestId"]

    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 400:
            print(f"Invalid phone number format: {phone_number}")
        elif e.response.status_code == 401:
            print("Invalid API key")
        elif e.response.status_code == 429:
            print("Rate limited — try again later")
        else:
            print(f"Request failed: {e}")
        return None

Phone Number Format

Phone numbers must be in E.164 international format:

Format	Valid
+15551234567	Yes
+442071234567	Yes
555-123-4567	No
(415) 555-1234	No
15551234567	No

Pricing

Operation	Cost
Send verification	$0.015
Check verification	Free

Costs are automatically charged to your Sapiom account.