A screen pop opens the relevant contact alongside an incoming call. Use the IllyVoIP SDK’s incoming-call event to start a backend Contacts lookup, then show the authorized result without delaying Answer or Decline. A matching caller number is useful context; it does not authenticate the person calling.
This guide extends a custom application using IllyVoIP Webphone SDK 1.4.2. Begin with one managed SDK instance, HTTPS, an eligible SIP identity and a short-lived token issued by your authorized backend. Follow the SDK setup guide for registration and audio controls.
1. Keep the contact lookup separate from call control
Attach listeners before making the phone available. The call:incoming event contains a call object. Keep its exact id and obtain the presented identity with call.remoteIdentity(), which returns displayName and uri. There is no guaranteed standalone phone-number property on this object.
- Render the display name as text, never HTML.
- Send the URI to your authenticated backend for controlled parsing. Do not navigate to it or treat it as a contact URL.
- Accept only the telephone identity forms your integration deliberately supports. Treat anonymous, malformed or non-telephone identities as unavailable.
- Normalize complete international numbers using established number handling and a known country context. Do not match the last few digits.
2. Search through the authorized account backend
Use a backend with authorized account API access and keep X-Api-Key out of browser code. The API base is https://api.illyvoip.com. Check HTTP status and the JSON result. Examples below are request templates, not records of completed transactions.
The Contacts API is account-owner scoped. Your application must separately enforce which contacts the signed-in operator may see; possession of the account’s API key does not grant every agent access to every returned record. Keep raw account-wide results on the backend.
Use GET /api/v1/contacts with URL-encoded q, page and limit. Normal reads exclude deleted contacts. The search covers several fields and can return substring matches, so it is only a candidate search. Compare each returned contact’s complete normalized phone with the parsed caller number and apply your operator-access rules.
Read the returned pagination.total_pages. If you intentionally stop at a latency or page limit, label the lookup incomplete; one match on the first page does not prove uniqueness. For larger contact sets, maintain an authorized local mirror using the established Contacts sync workflow, including deletion handling and periodic reconciliation.
3. Give each call its own lookup state
Keep a map keyed by SDK call ID. Each entry should contain the lookup generation, current state and permitted result. Your backend endpoint belongs to your application; do not present it as an IllyVoIP screen-pop API. Use these visible states:
- Looking up contact: incoming controls remain usable.
- One exact permitted match: show a compact summary and an explicit Open contact action.
- Several exact matches: show permitted choices and let the operator choose.
- No match: show the caller context without creating a contact automatically.
- Unavailable or incomplete: explain that lookup could not finish; do not label this as no matching contact.
Open only an application-generated contact route bound to the authorized record ID. Recheck access when that route loads. Caller display text and contact fields must not become arbitrary navigation targets.
4. Ignore results that arrive too late
- Before starting a lookup, create a new generation for that call and clear any previous contact summary.
- When a result arrives, confirm the account, SDK owner, call ID and generation still match.
- On
call:ended, invalidate that call’s generation and remove its lookup state. - On account change or logout, invalidate every lookup and clear private results.
- If the user selects another call, render that call’s own state rather than whichever lookup finished most recently.
Aborting an HTTP request can reduce unnecessary work, but generation checks are still needed when cancellation races with completion. Answering the call may keep the same authorized contact panel visible; ending it must not allow a late response to reopen it. Reuse the existing incoming-controls guide for exact-call Answer and Decline behavior.
5. Verify matching and races before release
Test an exact match, a substring-only match, two contacts sharing a number, a restricted contact, an anonymous caller and a lookup error. Delay call A’s lookup until after call B arrives, then end A before its result returns. Confirm A cannot replace B’s panel. Repeat after logout. Finally, arrange an authorized incoming-call check for routing, ringing and UI timing; local fixtures do not prove real caller identity or audio quality.
Related guides
- Use IllyVoIP calling inside your CRM
- Build incoming-call Answer and Decline controls with the Webphone SDK
- Sync CRM contacts into IllyVoIP with the Contacts API
- Add browser calling with the Webphone SDK
Reference
Current instructions and technical reference: IllyVoIP API documentation.
Reviewed 13 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.