Authentication

Our API uses API keys for authentication. You can obtain an API key from your dashboard.

Using Your API Key

Include your API key in the headers of all requests:

curl -H "Authorization: Bearer YOUR_API_KEY"      -H "Content-Type: application/json"      https://api.example.com/v1/endpoint

API Endpoints

GET /users

Retrieve a list of users.

GET /users HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY

Create a Case

Use this endpoint to create a new case. You can provide either a business email, URL, or business legal name with country.

POST /api/v1/cases

POST /api/v1/cases HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "type": "email", // or "url" or "business_name"
  "value": "business@example.com", // or "https://example.com" or "Acme Inc."
  "country": "United States" // required if type is "business_name"
}

Case CRUD API

Complete API reference for managing cases. All endpoints require authentication using your API key.

List Cases

Retrieve a paginated list of cases with optional filtering.

GET /api/v1/cases HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY

Query Parameters:
- page (optional): Page number for pagination (default: 1)
- limit (optional): Items per page (default: 20)
- status (optional): Filter by status (pending, in_review, completed)
- from_date (optional): Filter by creation date (ISO 8601)
- to_date (optional): Filter by creation date (ISO 8601)
- search (optional): Search in title and description

Get Case Details

Retrieve detailed information about a specific case.

GET /api/v1/cases/{caseId} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY

Update Case

Update an existing case with new information.

PATCH /api/v1/cases/{caseId} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "status": "completed",
  "priority": "medium",
  "assigned_to": "jane.smith@example.com",
  "notes": [
    {
      "content": "Case review completed, no further action needed"
    }
  ]
}

Delete Case

Permanently delete a case. This action cannot be undone.

DELETE /api/v1/cases/{caseId} HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY

Error Responses

Possible error responses for case operations.

{
  "error": {
    "code": "case_not_found",
    "message": "The specified case could not be found",
    "status": 404
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "status": 400,
    "details": {
      "status": ["Invalid status value. Allowed values are: pending, in_review, completed"]
    }
  }
}

{
  "error": {
    "code": "permission_denied",
    "message": "You don't have permission to perform this action",
    "status": 403
  }
}

Review a Case

Use this endpoint to retrieve details of an existing case.

GET /api/v1/cases/:caseId

GET /api/v1/cases/CASE-12345 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY

Generate Category

Use this endpoint to generate a category for a business based on provided information.

POST /api/v1/generate/category

POST /api/v1/generate/category HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "type": "email", // or "url" or "business_name"
  "value": "business@example.com", // or "https://example.com" or "Acme Inc."
  "country": "United States" // required if type is "business_name"
}

Generate Summary

Use this endpoint to generate a summary of a business based on provided information.

POST /api/v1/generate/summary

POST /api/v1/generate/summary HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "type": "email", // or "url" or "business_name"
  "value": "business@example.com", // or "https://example.com" or "Acme Inc."
  "country": "United States" // required if type is "business_name"
}

Get Web Presence Details

Use this endpoint to retrieve web presence details for a business.

GET /api/v1/web-presence

GET /api/v1/web-presence?type=url&value=https://example.com HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY

Rate Limiting

Our API implements rate limiting to ensure fair usage and maintain service stability.

• Free tier: 100 requests per hour
• Pro tier: 1000 requests per hour
• Enterprise tier: Custom limits

Rate limit information is included in the response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1623423728

Error Handling

Our API uses conventional HTTP response codes to indicate the success or failure of an API request.

• 2xx: Success
• 4xx: Client errors
• 5xx: Server errors

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The request was unacceptable, often due to missing a required parameter.",
    "details": {
      "missing_param": "user_id"
    }
  }
}