Authenticate Callers with PIN Verification

Overview

Some calls need more than just routing — they need identity verification. A caller’s phone number alone isn’t always enough: the same SIM card may be used by multiple people, or you need to confirm the caller is who they claim to be.

This guide shows how to use External Management to build a PIN-based authentication IVR. When a call arrives, Hipcall prompts the caller to enter a personal PIN. Your server verifies it against the caller’s phone number and tells Hipcall where to route the call — to the customer support team on success, or to sales if the PIN does not match.

How It Works

Hipcall sends each step of the call to your server as a JSON sequence. On the first request (no PIN entered yet), your server responds with a gather action to collect digits. On the second request (PIN provided), your server validates it and responds with play and connect actions.

Architecture

flowchart TD
    A[Caller dials in] --> B[External Management POSTs to your server]
    B --> C[Server returns gather action]
    C --> D[Caller enters 1-4 digit PIN]
    D --> E[External Management POSTs again with PIN]
    E --> F{Phone found AND PIN correct?}
    F -- Yes --> G[Play success audio\nConnect to ext 1091]
    F -- No --> H[Play failure audio\nConnect to ext 1092]

Step 1: Configure External Management in Hipcall

1. Go to Settings > Developer > External Managements in your Hipcall dashboard.
2. Create a new External Management entry with:

Field	Value
Name	PIN Authentication
Target URL	https://your-server.example.com/api/external/hipcall-ingress

3. Attach this External Management to the desired IVR step or call flow in your Hipcall account.

Local development: Use ngrok to expose your local server. Run ngrok http 5000 and use the generated URL as the Target URL.

Step 2: Handle the Initial Request

When a call first hits your External Management endpoint, Hipcall sends a POST with the caller’s phone number but no PIN yet:

{
  "caller": "+905060508169",
  "data": {}
}

Respond with a gather action to prompt the caller for their PIN:

@app.route('/api/external/hipcall-ingress', methods=['POST'])
def hipcall_ingress():
    data = request.json
    caller = data.get('caller')
    gather_data = data.get('data', {})

    if 'pin_code' not in gather_data:
        return jsonify({
            "version": "1",
            "seq": [
                {
                    "action": "gather",
                    "args": {
                        "min_digits": 1,
                        "max_digits": 4,
                        "ask": "https://your-server.example.com/static/audio/pin_prompt.mp3",
                        "variable_name": "pin_code"
                    }
                }
            ]
        })

The ask field is an MP3 URL played to the caller (e.g. “Please enter your PIN.”). Hipcall collects between min_digits and max_digits key presses and stores them under variable_name.

Step 3: Verify the PIN and Route the Call

After the caller enters their PIN, Hipcall sends a second POST with the collected digits:

{
  "caller": "+905060508169",
  "data": {
    "pin_code": "1234"
  }
}

Look up the caller in your database and compare PINs. Normalize the phone number before querying — Hipcall may send it with a country prefix:

def normalize_phone(phone):
    if not phone:
        return phone
    phone = phone.strip()
    if phone.startswith('+90'):
        phone = phone[3:]
    elif phone.startswith('90') and len(phone) == 12:
        phone = phone[2:]
    elif phone.startswith('0') and len(phone) == 11:
        phone = phone[1:]
    return phone

Then verify the PIN and respond with the appropriate routing:

    # Continuing hipcall_ingress() from Step 2 ...
    normalized_caller = normalize_phone(caller)
    user = db.execute(
        'SELECT * FROM users WHERE phone = ?', (normalized_caller,)
    ).fetchone()

    entered_pin = gather_data.get('pin_code')

    if user and entered_pin == user['pin_code']:
        return jsonify({
            "version": "1",
            "seq": [
                {
                    "action": "play",
                    "args": {
                        "url": "https://your-server.example.com/static/audio/success.mp3"
                    }
                },
                {
                    "action": "connect",
                    "args": {"destination": "1091"}
                }
            ]
        })
    else:
        return jsonify({
            "version": "1",
            "seq": [
                {
                    "action": "play",
                    "args": {
                        "url": "https://your-server.example.com/static/audio/failure.mp3"
                    }
                },
                {
                    "action": "connect",
                    "args": {"destination": "1092"}
                }
            ]
        })

On success: Hipcall plays the success audio and connects the caller to extension 1091 (customer support).

On failure: Hipcall plays the failure audio and connects the caller to extension 1092 (sales team), where an agent can assist further.

Step 4: Log Requests for Debugging

During development, log every incoming request and outgoing response so you can trace PIN verification in real time:

@app.after_request
def log_request_response(response):
    if request.path == '/api/external/hipcall-ingress':
        req_body = request.get_data(as_text=True)
        res_body = response.get_data(as_text=True)
        db.execute(
            "INSERT INTO logs (method, path, request_body, response_body) VALUES (?, ?, ?, ?)",
            (request.method, request.path, req_body, res_body)
        )
        db.commit()
    return response

Tools Used

Tool	Purpose
External Management	Drives the two-step IVR sequence — collect PIN, then route the call

Next Steps

• External Management documentation — Learn the full action sequence reference (gather, play, connect, hangup)
• Webhooks documentation — Combine with call_hangup events to audit authentication attempts
• REST API authentication — Secure your endpoint with Basic Auth or API key verification