API Documentation
The Ethical Crystals API provides programmatic access to certification data, trust scores, and directory information. Build applications that promote ethical sourcing and transparency in the crystal industry.
Secure & Reliable
REST API with OAuth 2.0 authentication and 99.9% uptime SLA
Real-time Data
Access up-to-date certification status and trust scores
Global Coverage
Worldwide seller database with comprehensive metadata
Quick Start
bash
# Get an API key
curl -X POST https://api.ethicalcrystals.com/v1/auth/api-keys \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "My Integration", "scopes": ["read:businesses"]}'
# Verify a business
curl -X GET https://api.ethicalcrystals.com/v1/businesses/12345 \
-H "Authorization: Bearer YOUR_API_KEY"Authentication
The API uses OAuth 2.0 for authentication. You'll need to obtain an access token to make API requests.
Getting an API Key
- Sign up for a developer account
- Create a new application in your dashboard
- Generate an API key with appropriate scopes
- Include the key in your request headers
http
Authorization: Bearer your_api_key_hereAvailable Scopes
| Scope | Description |
|---|---|
read:businesses |
Read business information and certification status |
read:trust-scores |
Access trust scores and detailed ratings |
read:directory |
Access the public directory of certified businesses |
write:reports |
Submit reports about unethical practices |
webhook:receive |
Receive webhook notifications |
Rate Limits
API requests are rate limited to ensure fair usage and system stability.
Free Tier
1,000 requests/hour
- Basic business verification
- Public directory access
- Email support
Pro Tier
10,000 requests/hour
- Full API access
- Webhook notifications
- Priority support
Enterprise
Custom limits
- Unlimited requests
- Custom integrations
- Dedicated support
http
Rate limit headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200Businesses
Access information about businesses in our certification system.
GET
/v1/businesses/{id}
Retrieve detailed information about a specific business.
Parameters
| Parameter | Type | Description |
|---|---|---|
id |
string | Unique business identifier |
include |
string | Comma-separated list: trust_score, certifications, reviews |
json
Response
{
"id": "biz_1234567890",
"name": "Crystal Clear Gems",
"type": "retailer",
"location": {
"city": "San Francisco",
"state": "CA",
"country": "US"
},
"certification": {
"status": "active",
"level": "gold",
"issued_date": "2024-01-15",
"expires_date": "2025-01-15",
"trust_score": 87
},
"contact": {
"website": "https://crystalcleargems.com",
"email": "info@crystalcleargems.com"
},
"categories": ["Fair Labor", "Environmental", "Transparency"],
"last_updated": "2024-03-01T10:00:00Z"
}
GET
/v1/businesses
Search and filter businesses in the directory.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
type |
string | Business type: retailer, wholesaler, mining, processor |
location |
string | City, state, or country |
min_trust_score |
integer | Minimum trust score (0-100) |
certification_level |
string | basic, silver, gold, platinum |
limit |
integer | Number of results (default: 50, max: 100) |
offset |
integer | Pagination offset |
Trust Scores
Access detailed trust score information and category breakdowns.
GET
/v1/trust-scores/{business_id}
Get comprehensive trust score data for a business.
json
Response
{
"business_id": "biz_1234567890",
"overall_score": 87,
"grade": "B+",
"last_updated": "2024-03-01T10:00:00Z",
"categories": {
"labor_practices": {
"score": 92,
"weight": 0.2,
"details": "Excellent worker safety and fair wage practices"
},
"environmental_impact": {
"score": 85,
"weight": 0.2,
"details": "Strong environmental protection measures"
},
"transparency": {
"score": 90,
"weight": 0.15,
"details": "Complete supply chain documentation"
},
"community_engagement": {
"score": 88,
"weight": 0.15,
"details": "Active community support programs"
},
"sustainability": {
"score": 82,
"weight": 0.15,
"details": "Renewable energy adoption in progress"
},
"small_scale_support": {
"score": 89,
"weight": 0.15,
"details": "Direct partnerships with artisanal miners"
}
},
"verification_status": "verified",
"next_review_date": "2024-09-01"
}Webhooks
Receive real-time notifications when certification statuses change or new businesses are verified.
Available Events
| Event | Description |
|---|---|
business.certified |
A business receives certification |
business.trust_score_updated |
Trust score changes significantly (±5 points) |
business.certification_expired |
A business certification expires |
business.flagged |
A business is flagged for review |
report.submitted |
A new report is submitted about a business |
json
Webhook payload example
{
"event": "business.trust_score_updated",
"timestamp": "2024-03-01T10:00:00Z",
"data": {
"business_id": "biz_1234567890",
"previous_score": 82,
"new_score": 87,
"change_reason": "Improved environmental practices"
},
"webhook_id": "wh_abcdef123456"
}SDKs & Libraries
Official SDKs and community libraries to integrate our API into your applications.
Error Handling
The API uses conventional HTTP response codes to indicate success or failure.
| Code | Description |
|---|---|
200 |
Success |
400 |
Bad Request - Invalid parameters |
401 |
Unauthorized - Invalid API key |
403 |
Forbidden - Insufficient permissions |
404 |
Not Found - Resource doesn't exist |
429 |
Too Many Requests - Rate limit exceeded |
500 |
Internal Server Error |
json
Error response format
{
"error": {
"code": "invalid_parameter",
"message": "The 'type' parameter must be one of: retailer, wholesaler, mining, processor",
"param": "type",
"request_id": "req_abc123"
}
}