EasyDNC API – Developer Guide

Integrate Do-Not-Call lookups and account data into your applications. All responses are JSON unless noted.

Authentication

Provide your API key in either the Authorization header or the key query parameter.

Authorization: Bearer <API_KEY>

GET /api/check_dnc.php?key=<API_KEY>&number=3055550123

Throughput & Fair Use

There is no enforced hard rate limit on the DNC Lookup endpoint at this time. Please use reasonable throughput and backoff on transient errors.

• We may temporarily throttle abusive traffic to protect service availability.
• If formal limits are introduced later, they will be documented here and surfaced via 429 with a Retry-After header.

Errors

Non-2xx responses include a JSON error:

{
  "error": "❌ Invalid request. Provide key and 10-digit number."
}

Endpoint: DNC Lookup

GETPOST /api/check_dnc.php

Query Parameters (GET)

• key (string, required) – API key.
• number (string, required) – Phone number; any format. We normalize to 10 digits and drop leading 1.

curl 'https://www.easydnc.org/api/check_dnc.php?key=YOUR_KEY&number=+1-305-555-0123'

JSON Body (POST)

curl -X POST 'https://www.easydnc.org/api/check_dnc.php' \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "number": "+1 (305) 555-0123" }'

Successful Response 200

{
  "number": "3055550123",
  "dnc": false,
  "charged": 0.025,
  "balance": 19.975,
  "status": "✅ NOT on DNC"
}

# 400 Bad Request
{ "error": "❌ Invalid request. Provide key and 10-digit number." }

# 402 Payment Required
{ "error": "❌ Insufficient balance.", "balance": 0.0 }

# 403 Forbidden
{ "error": "❌ Invalid API key." }

# 500 Server Error
{ "error": "❌ DB connection failed." }

Billing

• Each successful lookup debits your account by your configured per-lookup cost (default $0.025).
• Debits are recorded in your ledger with type debit and method api.

Best Practices

• Cache results you recently queried to reduce cost/latency.
• Use POST + Authorization header for server-to-server calls.
• Retry with exponential backoff on transient errors (5xx).
• Rotate API keys periodically; keep least privilege.

Support

Email support@easydnc.org with your account email, timestamp, and request details.

Contents

Need an API key?

Contact support to enable API access on your account.