Skip to content

Sync-Numbers Documentation

🚀 REST API Gateway for AI Contact Transfer Integration

A secure, production-ready FastAPI service for seamless contact synchronization with AI

🌟 What is Sync-Numbers?

Sync-Numbers is a robust API gateway that bridges your systems with our AI models, providing enterprise-grade contact transfer capabilities with built-in validation, idempotency, and observability.

Key Features

✅ Phone Validation & Normalization - Validates and normalizes phone numbers to E.164 format
✅ Idempotency - Prevents duplicate processing with 72h TTL
✅ Authentication - Bearer token + optional HMAC signatures
✅ Automatic Chunking - Splits large batches (max 1000 contacts per chunk)
✅ Smart Retry Logic - Exponential backoff for 429/5xx errors
✅ Dry-Run Mode - Test validation without sending data
✅ Full Observability - Structured logging, Prometheus metrics, correlation IDs
✅ Security First - PII masking, IP allowlists, HTTPS-only

📚 Documentation

  • API Reference

    Complete API documentation with authentication, endpoints, and examples

    API Guide

  • Code Examples

    Practical examples in Python, JavaScript, and cURL

    Examples

🚀 Quick Example

import httpx
import uuid

async def import_contacts():
    headers = {
        "Authorization": "Bearer demo_api_key_12345",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    }

    contacts = [{
        "phone": "+79001234567",
        "tags": ["lead", "website"],
        "additionalFields": {
            "source": "landing",
            "campaign": "summer2024"
        }
    }]

    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://import-api.liddex.ru/v1/contacts/import",
            json=contacts,
            headers=headers,
        )
        return response.json()

🏗️ Architecture

graph LR
    A[Partner System] -->|HTTPS/JSON| B[Sync API]
    B -->|HTTPS/JSON| C[AI Webhook]
    B -->|Store| D[(PostgreSQL)]
    style B fill:#4051b5,stroke:#fff,color:#fff

📖 Available Languages

This documentation is available in multiple languages:

🆘 Support

Need help? Here's how to get support:

  1. Check the API Guide for common issues
  2. Review the Integration Guide for technical details
  3. Include correlation_id when reporting issues
  4. Contact your integration support team

Made with ❤️ for seamless contact transfer integration