PVALines API Integration Guide: Getting Started in 10 Minutes

Integrating phone verification into your application doesn't have to be complicated. This guide will walk you through the entire process of implementing PVALines API.

Prerequisites

• PVALines account with API access enabled
• API key from your dashboard
• Node.js 14+ or Python 3.8+ (examples provided for both)
• Basic understanding of REST APIs

Step 1: Authentication

All API requests require authentication using your API key in the header:

// Initialize PVALines client
const PVALines = require('pvalines-sdk');

const client = new PVALines({
  apiKey: process.env.PVALINES_API_KEY,
  baseURL: 'https://api.pvalines.com/v1'
});

// Test authentication
const testAuth = async () => {
  try {
    const balance = await client.getBalance();
    console.log('Current balance:', balance);
  } catch (error) {
    console.error('Authentication failed:', error);
  }
};

Step 2: Request a Phone Number

// Request a phone number for a specific service
const getPhoneNumber = async () => {
  try {
    const response = await client.getNumber({
      service: 'google',  // Service name
      country: 'US',      // Country code
      type: 'non-voip'    // Number type
    });
    
    console.log('Phone number:', response.number);
    console.log('Number ID:', response.id);
    console.log('Expires at:', response.expiresAt);
    
    return response;
  } catch (error) {
    console.error('Failed to get number:', error);
  }
};

Step 3: Wait for SMS Code

After requesting a number, poll the API to check for incoming SMS messages:

// Poll for SMS code
const waitForSMS = async (numberId, timeout = 300000) => {
  const startTime = Date.now();
  
  while (Date.now() - startTime < timeout) {
    try {
      const status = await client.getNumberStatus(numberId);
      
      if (status.sms) {
        console.log('Received SMS:', status.sms.text);
        console.log('Code:', status.sms.code);
        return status.sms.code;
      }
      
      // Wait 3 seconds before next poll
      await new Promise(resolve => setTimeout(resolve, 3000));
    } catch (error) {
      console.error('Error checking status:', error);
    }
  }
  
  throw new Error('Timeout waiting for SMS');
};

Step 4: Complete Verification Flow

// Full verification workflow
const verifyWithPhone = async (userEmail) => {
  try {
    // 1. Get a phone number
    const phoneData = await getPhoneNumber();
    
    // 2. Use the number for your service signup
    await yourServiceSignup({
      email: userEmail,
      phone: phoneData.number
    });
    
    // 3. Wait for verification code
    const code = await waitForSMS(phoneData.id);
    
    // 4. Submit verification code
    await yourServiceVerify({
      email: userEmail,
      code: code
    });
    
    // 5. Mark number as complete
    await client.completeNumber(phoneData.id);
    
    return {
      success: true,
      phone: phoneData.number,
      code: code
    };
  } catch (error) {
    console.error('Verification failed:', error);
    return { success: false, error: error.message };
  }
};

Error Handling Best Practices

• Always implement timeout handling for SMS wait
• Catch and log all API errors for debugging
• Implement retry logic for network failures
• Validate responses before using the data
• Clean up resources even if verification fails

Rate Limiting

PVALines API has the following rate limits:

Python Example

import os
import time
from pvalines import PVALinesClient

# Initialize client
client = PVALinesClient(api_key=os.environ['PVALINES_API_KEY'])

# Get phone number
phone_data = client.get_number(
    service='google',
    country='US',
    type='non-voip'
)

print(f"Phone number: {phone_data['number']}")

# Wait for SMS
sms_code = client.wait_for_sms(
    number_id=phone_data['id'],
    timeout=300
)

print(f"Verification code: {sms_code}")

Need help with integration? Our developer support team is available 24/7. Check out our full API documentation at docs.pvalines.com