API Documentation
Complete API reference for integrating with DoNotContact.net's opt-out service
Documentation
API Overview
🚀 Quick Start Guide
Wait for Approval
24-48 hours review
Get API Key
Sent via email
Start Integrating
Check suppressions
Base URL
https://api.donotcontact.net/v1Campaign ID System
How Campaign IDs Work
- • Generated by us when you register via POST /v1/campaign/register
- • UUID format (e.g., 12345678-1234-5678-9012-123456789012)
- • Internal identifier - NOT from FEC data
- • Used in all API calls to identify your campaign
API Key System
API Key Management
- • Auto-generated during campaign registration
- • Format: dnc_ prefix + 32 random characters
- • Usage: Include in X-API-Key header
- • Status: Disabled until campaign approval (24-48 hours)
Response Format
All API responses are in JSON format with consistent structure:
{
"api_version": "1.0.0",
"request_id": "apigw-req-abc123",
"success": true,
"data": { ... },
"message": "Optional message"
}The request_id is included in both the response body and X-Request-ID header for request tracing.
Error Handling
Error responses include HTTP status codes and structured error details:
{
"api_version": "1.0.0",
"request_id": "apigw-req-abc123",
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email format",
"details": {
"field": "email",
"value": "invalid-email"
}
}
}Error Code Reference
| Error Code | HTTP Status | Description | Retry? |
|---|---|---|---|
VALIDATION_ERROR | 400 | Invalid input data | No |
MISSING_REQUIRED_FIELD | 400 | Required field missing | No |
UNAUTHORIZED | 401 | Invalid or missing API key | No |
FORBIDDEN | 403 | Access denied (key not approved) | No |
RESOURCE_NOT_FOUND | 404 | Resource doesn't exist | No |
RATE_LIMITED | 429 | Too many requests | Yes - after reset |
INVALID_CURSOR | 400 | Invalid pagination cursor | No |
INTERNAL_ERROR | 500 | Server error | Yes - exponential backoff |
Rate Limits
Consumer API
100 requests/day
Campaign API
10,000 requests/day
All responses include rate limit headers to help you manage your usage:
X-RateLimit-Limit: 10000 # Your daily limit X-RateLimit-Remaining: 9850 # Requests remaining X-RateLimit-Reset: 1705363200 # Unix timestamp when limit resets
Pagination
Collection endpoints support cursor-based pagination for efficient data retrieval:
# Request with pagination
GET /v1/campaigns/fec?limit=50&cursor=eyJwayI6ImNhbXBfMTIzIn0
# Response includes pagination metadata
{
"api_version": "1.0.0",
"request_id": "apigw-req-abc123",
"campaigns": [...],
"pagination": {
"next_cursor": "eyJwayI6ImNhbXBfMTc0In0",
"has_more": true
}
}Parameters:
limit- Number of results per page (default: 50, max: 100)cursor- Opaque cursor from previous response
Identifier Hashing
All identifiers (emails, phone numbers) must be SHA-256 hashed before sending to the API.
# Quick Reference:
1. Normalize: lowercase + trim whitespace
2. For phones: strip to 10 digits (remove country code)
3. Apply SHA-256 hash
4. Output as lowercase hexadecimal string
# Example (JavaScript):
const hash = crypto.createHash('sha256')
.update(email.toLowerCase().trim())
.digest('hex');For detailed normalization rules, phone number handling, code examples in Python/JavaScript/PHP, and test cases, see our comprehensive guide.
Core Endpoints Quick Reference
POST/v1/campaign/register
Register your campaign to get API access. Returns your campaign_id and api_key.
// Request
{
"company_name": "Example Campaign 2024",
"contact_email": "admin@campaign.com",
"contact_name": "Jane Smith",
"fec_committee_id": "C00123456", // Optional
"website": "https://campaign.com",
"terms_accepted": true
}
// Response (201 Created)
{
"api_version": "1.0.0",
"request_id": "req-abc123",
"success": true,
"campaign_id": "camp_12345678-1234-5678-9012-123456789012",
"api_key": "dnc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"status": "pending_approval",
"message": "Registration successful. API key will be activated after approval (24-48 hours)."
}GET/v1/lookupAuth Required
Check if an identifier should be suppressed. This is the primary endpoint for real-time compliance checking.
// Request
GET /v1/lookup?identifier_hash=abc123...&identifier_type=email
Headers: X-API-Key: dnc_your_api_key
// Response (200 OK)
{
"api_version": "1.0.0",
"request_id": "req-xyz789",
"suppressed": true,
"opt_out_date": "2024-01-10T15:30:00Z",
"request_type": "subscription"
}
// Response when not suppressed
{
"api_version": "1.0.0",
"request_id": "req-xyz789",
"suppressed": false
}