Reference

NumDetect API reference

Every endpoint shares one API key and one balance.

Item	Value
Base URL	https://numdetect.com
Auth header	X-API-Key: sk_your_api_key
Response envelope	{ code, msg, data }

Prices are not listed here; every product is billed per successful check. See pricing

Authentication

Use an API key created in Settings and send it with every request.

Auth header

X-API-Key: sk_your_api_key

Keep your API key secret　Always call this endpoint from your server. Anyone holding the key can spend your balance.

Asynchronous checks

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Upload a file and get a task id straight away, then check that id until it succeeds. The successful response carries result_url, the result download link. Only two actions exist: submit and check. Poll no more often than once every 30 seconds.

Parameters

Field	Type	Description
`service_type`	string	Bulk product code, one of the products listed below.
`country`	string	ISO 3166-1 code such as `US`. Required for number tasks: every number must include its country code and belong to this country (numbers that do not are left out and not charged); it also selects routing. In multipart it must come before `file`.
`file`	file	A `.txt` or `.csv` with one identifier per line, up to `max_file_bytes` (20MB by default).
`Idempotency-Key`	header	Optional, up to 128 characters. Replaying the same key returns the original task instead of creating a second one.

Products in this group

Phone Number Validation

number_validation_batchphone500–500,000 per task

A clean list is the start of the next campaign. Check validity and activation signals to find records worth reviewing, then feed the structured result into list cleaning, CRM updates and pre-outreach checks so every action starts with clearer data.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_validation_batch \
  -F country=US \
  -F [email protected]

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591) and the stable key for matching results to a customer, lead or CRM record. Keep it to trace the source list and write results back in bulk; the field alone does not establish that a number can be contacted.
`activated`	true	The activation signal returned by this check. Use it to find records worth review before outreach, organise cleaning queues and support CRM segmentation; combine it with consent, source and interaction data rather than treating it as a connection or delivery guarantee. Values are true or false.

Number Activity

number_activity_batchphone500–500,000 per task

Let the next follow-up start with an activity signal. Find recent activity across a full number list, separate dormant records from numbers worth reviewing, and use the result to plan reactivation, segmentation and outreach priorities.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_activity_batch \
  -F country=US \
  -F [email protected]

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591), used to write the activity result back to a list, customer or lead record. It provides matching and traceability only; it does not include activity time, frequency or interaction details.
`activated`	true	An available activity signal that can help teams prioritise review, build audience labels and plan reactivation cadence. It is not an active-day count, frequency or specific observation time; a missing signal does not mean someone will never respond. Values are true or false.

High-Value Users

number_high_value_batchphone500–500,000 per task

Find the records worth reviewing first. Combine high-end device characteristics with recent network activity to return a true/false potential high-value-user signal for service, membership and campaign prioritization; it is a detection signal, not proof of income or purchase.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_high_value_batch \
  -F country=US \
  -F [email protected]

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code (e.g. 12017200001), used to match the high-value signal back to the uploaded record and follow it through a CRM or review queue. It does not provide identity, device model or other personal-profile data.
`activated`	true	A true/false supporting signal derived from high-end device characteristics and recent network activity. It can help membership, service and marketing teams set review priorities, but does not confirm income, assets, purchasing capacity or actual spend.

E-commerce Active

number_ecommerce_batchphone500–500,000 per task

Start the next commerce campaign with a more focused audience. Find available e-commerce activity signals, shape audience and remarketing segments around records worth review, and keep the boundary clear: the result is not an order, purchase intent or platform-activity record.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=number_ecommerce_batch \
  -F country=US \
  -F [email protected]

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591), used to connect the commerce activity signal with customer, lead or audience records. It lets marketing teams join the result with their own consent, browsing, order and membership data; it does not contain order or product information.
`activated`	true	An available commerce activity signal that can focus audience review, remarketing-list preparation and content-test planning. It does not represent an order, transaction value, purchase intent or a specific platform activity. Values are true or false.

Global carrier lookup

carrier_batchphone500–500,000 per task

Turn a phone list into routing-ready context. Append carrier, underlying carrier, line type, country, region and city to international records, then use the enriched result for routing, regional analysis, segmentation and CRM updates.

Submit a task

POST/api/v1/bulk-tasks

Request

curl -X POST "https://numdetect.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=carrier_batch \
  -F country=US \
  -F [email protected]

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Check the task

GET/api/v1/bulk-tasks/{id}

Request

curl "https://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Result columns

Field	example:	Description
`identifier`	17253100591	The submitted number as plain digits with the country code, no plus sign or spaces (e.g. 17253100591) and the matching key for writing carrier, line and geographic context back to the source list. Keep your own source columns alongside it so routing, service and CRM teams can trace the check, handle duplicates and update the correct customer or lead. It identifies a record; it does not prove that the number is reachable.
`carrier`	T-Mobile	The customer-facing carrier name when identifiable. It can enrich CRM records, support service routing, help review number composition and show how a list is distributed across carriers. Use it as operational context rather than proof of reachability or current usage. An empty value means no usable name was returned for this check; it does not prove that no carrier exists.
`underlying_carrier`		The underlying network carrier when identifiable, useful for understanding reseller, virtual-operator and ported-number contexts. It may differ from the customer-facing carrier, and that difference can help teams investigate routing or ownership questions. It is not a live cell-network status or a real-time connection signal.
`number_type`	Fixed Line or Mobile	The returned line type, such as mobile, fixed line or another identifiable category. Use it to separate mobile and fixed-line records, plan service routing, check channel fit and add a useful CRM segment. It is not a connection result; retain an empty or unknown value for review instead of treating it as a failure.
`country_code`	US	The returned country or territory code for grouping international lists, applying country-level routing and business rules, and building regional reports. It describes the numbering context, not a person’s current country, physical location or nationality. Cross-border use and virtual-number cases should be checked against your own customer data.
`region`	CA	The region, state or province context when available. It can support market-coverage analysis, regional list grouping, service assignment and operations reporting. It comes from number and network context rather than live location, so it should not be read as the user’s current area; missing or cross-region values need normal business review.
`city`	LOS ANGELES	The city-level context when available. It can improve regional reporting, reveal list composition, support localized operations and fill a missing CRM field. Number allocation, portability, virtual numbers and source differences can affect city-level precision, so important decisions should be checked against user-provided or existing business records.

Balance

GET/api/v1/balance

Read the current account balance in USD micros. Read-only: it creates no check record and charges nothing.

Balance

GET/api/v1/balance

Request

curl "https://numdetect.com/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"

Response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Concurrency, timeouts, and retry behavior

Bulk task submissions are accepted before work starts. Use the returned task status to decide whether to keep polling or handle a failure.

Field	Description
`5 requests in flight per user`	A task submission uses one request slot. If the account has no slot available, the API returns 42901 with Retry-After; wait and submit the file again.
`Poll instead of waiting`	Submitting a task returns immediately. Poll its status no more than once every 30 seconds while it is processing.
`Task size follows the product`	Each product has its own minimum and maximum file size, shown in the task section.

Error codes

Code	Description
`40000`	Unsupported service type or conflicting request fields
`40001`	Invalid JSON body
`40002`	Invalid number
`40100`	Missing or invalid API key
`40200`	Insufficient balance
`42200`	The submitted task could not be accepted in its current form
`42900`	A usage quota is exhausted, or there are too many unfinished orders
`42901`	All request slots are occupied; submit after an in-flight request finishes. The rejected request is not charged and carries a Retry-After header
`50303`	The service is at capacity right now; not charged. Wait for the Retry-After seconds and resubmit the same request
`50400`	The request did not finish within its timeout and is not charged; retry it
`50300`	Validation service maintenance