DirConnect API Documentation

Integrate DirConnect's business directory into your applications. Access listings, search endpoints, webhooks, and more via RESTful JSON APIs.

https://api.dirconnect.com/v2

All requests and responses use JSON. The API follows standard HTTP status codes and requires authentication via API keys.

Authentication

🔑 API Key Required

Include your API key in the request header: Authorization: Bearer YOUR_API_KEY. Keys can be generated from the Developer Dashboard.

Invalid or expired keys will return a 401 Unauthorized response. Keep your keys secure and never expose them in client-side code.

Endpoints

GET /listings Retrieve paginated business listings

Fetches a list of businesses filtered by category, location, or rating. Supports pagination and sorting.

Query Parameters

ParameterTypeDescription
categorystringFilter by category slug
locationstringCity or zip code
limitintegerResults per page (default: 20, max: 100)
offsetintegerPagination offset

Example Request

cURL
JavaScript
Python
curl -X GET "https://api.dirconnect.com/v2/listings?category=restaurants&limit=10" \ -H "Authorization: Bearer sk_live_abc123..."
// JavaScript (fetch) fetch('https://api.dirconnect.com/v2/listings?category=restaurants&limit=10', { headers: { 'Authorization': 'Bearer sk_live_abc123...' } }).then(res => res.json());
# Python (requests) import requests headers = {"Authorization": "Bearer sk_live_abc123..."} requests.get("https://api.dirconnect.com/v2/listings?category=restaurants&limit=10", headers=headers)
POST /listings Create a new business listing

Submit a new business to the directory. Requires business owner verification.

Request Body (JSON)

FieldTypeRequiredDescription
namestringYesBusiness legal name
categorystringYesCategory slug
locationobjectYesAddress, city, state, zip
contactobjectYesPhone, email, website
descriptionstringNoBusiness overview
POST /search Advanced directory search

Full-text search across business names, descriptions, tags, and locations. Supports geolocation filtering and fuzzy matching.

Request Body

{ "query": "plumber near downtown", "filters": { "rating_min": 4.0, "open_now": true, "max_distance_km": 15 }, "sort_by": "relevance" }

Error Handling

The API uses standard HTTP status codes:

  • 200 OK - Request succeeded
  • 400 Bad Request - Invalid parameters or JSON
  • 401 Unauthorized - Missing or invalid API key
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource does not exist
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Something went wrong on our end

Error responses follow this format:

{ "error": { "code": "VALIDATION_ERROR", "message": "Missing required field: name", "details": ["location.city is invalid"] } }

Rate Limits

API requests are limited to 1,000 requests per minute per API key. Burst limits allow up to 20 requests per second. Rate limit headers are included in every response:

X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 942 X-RateLimit-Reset: 1698765432