ATS CRM - VICIdial Integration API

📡 Base URL

http://YOUR_SERVER_IP:3001/api/integration

Replace YOUR_SERVER_IP with your actual server IP address.

🔐 Authentication

All webhook endpoints require an API Key:

Authorization: Bearer {YOUR_API_KEY}

Where to find: CRM Admin → Integration Servers → Select server → Copy API Key

⚠️ Security: The API key determines which company's data is accessed. Never pass company_id in payload.

📨 Create/Update Lead Webhook

POST /api/integration/leads

Request Headers

Header	Value	Required
`Authorization`	Bearer {API_KEY}	Yes
`Content-Type`	application/json	Yes

Request Body

Field	Type	Required	Description
`customer_name`	string	Yes	Customer full name
`phone`	string	Yes	Phone number (7-20 digits)
`status`	string	No	NEW, CONTACTED, INTERESTED, SALE, NOT_INTERESTED, CALLBACK, NO_ANSWER (defaults to NEW)
`email`	string	No	Email address
`external_lead_id`	string	No	VICIdial lead ID for deduplication
`campaign_id`	string	No	VICIdial campaign name
`nickname`	string	No	Integration Code (e.g., ATS0006) for auto-assignment
`agent_id`	string	No	VICIdial agent ID (fallback)
`any_other_field`	any	No	Auto-stored in custom_data

Example cURL

curl -X POST http://YOUR_SERVER_IP:3001/api/integration/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_lead_id": "VICI_12345",
    "phone": "9876543210",
    "customer_name": "Rahul Sharma",
    "email": "rahul@example.com",
    "status": "SALE",
    "campaign_id": "MAIN_CAMPAIGN",
    "nickname": "ATS0006",
    "agent_id": "1002",
    "city": "Mumbai",
    "loan_amount": "500000"
  }'

Success Response (201)

{
    "success": true,
    "data": {
        "action": "created",
        "lead_id": 1217,
        "assigned_to": 6,
        "assigned_user_name": "Mansi Patekar",
        "integration_code": "ATS0006"
    }
}

Warning Response (unassigned)

{
    "success": true,
    "data": {
        "action": "created",
        "lead_id": 1218,
        "assigned_to": null,
        "warnings": [
            {
                "type": "INVALID_USER_MAPPING",
                "message": "Integration Code \"ATS9999\" invalid",
                "code": "ATS9999"
            }
        ]
    }
}

Important: Even with invalid code, webhook returns 200 OK and lead IS created (just unassigned).

🔄 Duplicate Detection

Priority	Method	Action
1	external_lead_id + Company	UPDATE existing
2	phone + Company	UPDATE existing
3	No match	CREATE new

👤 User Assignment via Integration Code

Setup:
1. CRM → Users → Copy Integration Code (e.g., ATS0006)
2. VICIdial → Users → Paste into Nickname field
3. Webhook sends nickname → CRM auto-assigns to that user

Security: Cross-company assignment is blocked. Lead created but left unassigned.

🔍 Search Leads

GET /api/integration/leads/search

Parameter	Description
`phone`	Search by phone
`external_lead_id`	Search by VICIdial ID
`email`	Search by email
`integration_code`	Search by assigned code

curl -H "Authorization: Bearer {API_KEY}" \
  "http://YOUR_SERVER_IP:3001/api/integration/leads/search?phone=9876543210"

💚 Health Check

GET /api/integration/health (no auth)

curl http://YOUR_SERVER_IP:3001/api/integration/health

⚙️ VICIdial Configuration

In VICIdial Admin:

1. ADMIN → System Settings → VICIdial Configuration
2. Find "Post to URL on SALE" or "Webhook URL"
3. Set URL: http://YOUR_SERVER_IP:3001/api/integration/leads
4. Set Method: POST
5. Set Headers:
   Authorization: Bearer YOUR_API_KEY
   Content-Type: application/json
6. Payload variables:
   $lead_id → external_lead_id
   $phone_number → phone
   $first_name $last_name → customer_name
   $email → email
   $campaign_id → campaign_id
   $user → agent_id
   $user_nickname → nickname ← CRITICAL!

Key: nickname must contain Integration Code (ATS0006) for auto-assignment.

❌ Error Codes

Code	HTTP	Description
AUTH_FAILED	401	Missing/invalid API key
COMPANY_DISABLED	403	Company account disabled
SERVER_INACTIVE	403	Integration server inactive
VALIDATION_ERROR	400	Missing required fields

🔗 VICIdial Integration API