Webhook events for phone number lookups and searches
The Telco API generates events when phone number lookups and searches are performed. These events are delivered through the unified do.dev webhook system.
| Event Type | Trigger | Description |
|---|---|---|
telco.lookup.completed | GET /v1/telco/lookup/{tn} | Phone number lookup completed |
telco.search.completed | GET /v1/telco/search | Number search query completed |
Fired after a successful phone number lookup.
{
"eventId": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "telco.lookup.completed",
"service": "telco",
"data": {
"tn": "2125551234",
"npa": "212",
"nxx": "555",
"hasCarrier": true,
"hasInventory": false
},
"livemode": true,
"createdAt": 1700000000000
}| Field | Type | Description |
|---|---|---|
data.tn | string | The 10-digit phone number that was looked up |
data.npa | string | Area code (first 3 digits) |
data.nxx | string | Exchange (digits 4-6) |
data.hasCarrier | boolean | Whether carrier data was found |
data.hasInventory | boolean | Whether the number exists in your inventory |
Fired after a search query against the NPA-NXX or inventory databases.
{
"eventId": "evt_b2c3d4e5-f6a7-8901-bcde-f12345678901",
"type": "telco.search.completed",
"service": "telco",
"data": {
"source": "npanxx",
"filters": {
"state": "NY",
"npa": "212",
"rateCenter": null,
"ocn": null
}
},
"livemode": true,
"createdAt": 1700000000000
}| Field | Type | Description |
|---|---|---|
data.source | string | "npanxx" or "inventory" |
data.filters | object | The search filters that were applied |
Create a webhook endpoint that listens to telco events:
curl -X POST https://api.do.dev/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks",
"enabled_events": ["telco.*"]
}'Or subscribe to only lookups:
{
"enabled_events": ["telco.lookup.completed"]
}