Partners API

curl -X POST https://api.iconustech.com/v1/partners/register \
-H "Content-Type: application/json" \
-d '{
  "name": "Your Company Name",
  "email": "dev@yourcompany.com",
  "type": "CORPORATE",
  "tier": "FREE"
}'

{
"success": true,
"message": "Partner account created successfully",
"data": {
  "partnerId": "partner_abc123def456",
  "apiKey": "iconus_live_xyz789abc123",
  "apiSecret": "secret_abc123def456",
  "name": "Your Company Name",
  "email": "dev@yourcompany.com",
  "type": "CORPORATE",
  "tier": "FREE",
  "requestLimit": 1000,
  "requestCount": 0,
  "status": "PENDING_APPROVAL",
  "createdAt": "2025-11-12T10:30:00Z"
}
}

async function registerPartner(partnerData) {
const response = await fetch(
  'https://api.iconustech.com/v1/partners/register',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(partnerData),
  }
);
 
const result = await response.json();
 
if (result.success) {
  console.log('Partner registered!');
  console.log('API Key:', result.data.apiKey);
  console.log('Save this key securely!');
  
  // Store API key securely
  await storeApiKey(result.data.apiKey);
  
  return result.data;
}
 
throw new Error(result.message);
}
 
// Usage
const partner = await registerPartner({
name: 'Acme Corporation',
email: 'dev@acme.com',
type: 'CORPORATE',
tier: 'FREE',
});

curl https://api.iconustech.com/v1/partners/partner_abc123 \
-H "x-api-key: YOUR_API_KEY"

{
"success": true,
"data": {
  "partnerId": "partner_abc123",
  "name": "Your Company Name",
  "email": "dev@yourcompany.com",
  "type": "CORPORATE",
  "tier": "FREE",
  "requestLimit": 1000,
  "requestCount": 847,
  "status": "ACTIVE",
  "createdAt": "2025-11-01T10:30:00Z",
  "lastAccessedAt": "2025-11-12T14:22:00Z",
  "resetDate": "2025-12-01T00:00:00Z"
}
}

async function getPartnerDetails(partnerId) {
const response = await fetch(
  `https://api.iconustech.com/v1/partners/${partnerId}`,
  {
    headers: {
      'x-api-key': process.env.ICONUS_API_KEY,
    },
  }
);
 
const result = await response.json();
const { data } = result;
 
console.log('Partner:', data.name);
console.log('Tier:', data.tier);
console.log('Usage:', `${data.requestCount}/${data.requestLimit}`);
console.log('Status:', data.status);
 
return data;
}
 
// Usage
const partner = await getPartnerDetails('partner_abc123');

curl https://api.iconustech.com/v1/partners/partner_abc123/usage \
-H "x-api-key: YOUR_API_KEY"

{
"success": true,
"data": {
  "partnerId": "partner_abc123",
  "tier": "FREE",
  "currentPeriod": {
    "startDate": "2025-11-01T00:00:00Z",
    "endDate": "2025-12-01T00:00:00Z",
    "requestCount": 847,
    "requestLimit": 1000,
    "remaining": 153,
    "percentageUsed": 84.7
  },
  "breakdown": {
    "checksRegistered": 423,
    "checksVerified": 401,
    "checksRetrieved": 23
  },
  "dailyUsage": [
    { "date": "2025-11-12", "requests": 45 },
    { "date": "2025-11-11", "requests": 52 },
    { "date": "2025-11-10", "requests": 38 }
  ]
}
}

async function monitorUsage(partnerId) {
const response = await fetch(
  `https://api.iconustech.com/v1/partners/${partnerId}/usage`,
  {
    headers: {
      'x-api-key': process.env.ICONUS_API_KEY,
    },
  }
);
 
const result = await response.json();
const { currentPeriod, breakdown } = result.data;
 
// Check if approaching limit
if (currentPeriod.percentageUsed > 80) {
  console.warn('⚠️  Warning: 80% of API quota used');
  console.log(`Remaining: ${currentPeriod.remaining} requests`);
  
  // Consider upgrading
  if (currentPeriod.percentageUsed > 90) {
    console.error('🚨 Critical: 90% of quota used!');
    console.log('Upgrade at: https://iconustech.com/pricing');
  }
}
 
console.log('Usage Breakdown:');
console.log(`- Checks Registered: ${breakdown.checksRegistered}`);
console.log(`- Checks Verified: ${breakdown.checksVerified}`);
console.log(`- Checks Retrieved: ${breakdown.checksRetrieved}`);
 
return result.data;
}
 
// Usage
await monitorUsage('partner_abc123');

curl -X PATCH https://api.iconustech.com/v1/partners/partner_abc123 \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "name": "Updated Company Name",
  "email": "newemail@company.com"
}'

{
"success": true,
"message": "Partner updated successfully",
"data": {
  "partnerId": "partner_abc123",
  "name": "Updated Company Name",
  "email": "newemail@company.com",
  "updatedAt": "2025-11-12T15:30:00Z"
}
}

curl -X POST https://api.iconustech.com/v1/partners/partner_abc123/rotate-key \
-H "x-api-key: YOUR_CURRENT_API_KEY"

{
"success": true,
"message": "API key rotated successfully",
"data": {
  "partnerId": "partner_abc123",
  "newApiKey": "iconus_live_new123abc456",
  "oldApiKey": "iconus_live_xyz789abc123",
  "expiresAt": "2025-11-19T15:30:00Z"
},
"warning": "Old API key will expire in 7 days. Update your applications."
}

async function rotateApiKey(partnerId, currentApiKey) {
const response = await fetch(
  `https://api.iconustech.com/v1/partners/${partnerId}/rotate-key`,
  {
    method: 'POST',
    headers: {
      'x-api-key': currentApiKey,
    },
  }
);
 
const result = await response.json();
 
if (result.success) {
  console.log('✅ API Key Rotated');
  console.log('New Key:', result.data.newApiKey);
  console.log('Old Key Expires:', result.data.expiresAt);
  
  // Update environment variables
  await updateEnvironmentVariable('ICONUS_API_KEY', result.data.newApiKey);
  
  // Notify team
  await notifyTeam({
    subject: 'API Key Rotated',
    message: `Old key expires on ${result.data.expiresAt}`,
  });
  
  return result.data;
}
 
throw new Error(result.message);
}
 
// Usage
const newKey = await rotateApiKey(
'partner_abc123',
process.env.ICONUS_API_KEY
);

curl -X POST https://api.iconustech.com/v1/partners/partner_abc123/upgrade \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"tier": "PREMIUM"}'

{
"success": true,
"message": "Tier upgraded successfully",
"data": {
  "partnerId": "partner_abc123",
  "oldTier": "FREE",
  "newTier": "PREMIUM",
  "requestLimit": 100000,
  "effectiveDate": "2025-11-12T15:30:00Z"
}
}

curl -X POST https://api.iconustech.com/v1/partners/partner_abc123/webhooks \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "url": "https://yourapp.com/webhooks/iconus",
  "events": ["check.verified", "fraud.detected"]
}'

{
"success": true,
"message": "Webhook configured successfully",
"data": {
  "webhookId": "webhook_abc123",
  "url": "https://yourapp.com/webhooks/iconus",
  "events": ["check.verified", "fraud.detected"],
  "secret": "whsec_abc123def456",
  "status": "ACTIVE"
}
}

import os
import requests
from typing import Dict, Any, Optional
 
class PartnerManager:
  def __init__(self, api_key: str):
      self.api_key = api_key
      self.base_url = "https://api.iconustech.com/v1"
      self.headers = {
          "x-api-key": api_key,
          "Content-Type": "application/json"
      }
  
  def get_details(self, partner_id: str) -> Dict[str, Any]:
      """Get partner account details"""
      response = requests.get(
          f"{self.base_url}/partners/{partner_id}",
          headers=self.headers
      )
      return response.json()
  
  def get_usage(self, partner_id: str) -> Dict[str, Any]:
      """Get usage statistics"""
      response = requests.get(
          f"{self.base_url}/partners/{partner_id}/usage",
          headers=self.headers
      )
      return response.json()
  
  def check_quota(self, partner_id: str) -> bool:
      """Check if approaching quota limit"""
      usage = self.get_usage(partner_id)
      current = usage['data']['currentPeriod']
      
      if current['percentageUsed'] > 80:
          print(f"⚠️  Warning: {current['percentageUsed']}% quota used")
          print(f"Remaining: {current['remaining']} requests")
          return False
      
      return True
  
  def rotate_key(self, partner_id: str) -> str:
      """Rotate API key"""
      response = requests.post(
          f"{self.base_url}/partners/{partner_id}/rotate-key",
          headers=self.headers
      )
      result = response.json()
      
      if result['success']:
          new_key = result['data']['newApiKey']
          print(f"✅ New API Key: {new_key}")
          return new_key
      
      raise Exception(result['message'])
 
# Usage
manager = PartnerManager(os.getenv('ICONUS_API_KEY'))
 
# Check usage
usage = manager.get_usage('partner_abc123')
print(f"Usage: {usage['data']['currentPeriod']['percentageUsed']}%")
 
# Check quota
if not manager.check_quota('partner_abc123'):
  print("Consider upgrading your plan")
 
# Rotate key (every 90 days)
# new_key = manager.rotate_key('partner_abc123')

// Check usage daily
async function dailyUsageCheck() {
const usage = await getPartnerUsage('partner_abc123');
const { percentageUsed, remaining } = usage.currentPeriod;
 
if (percentageUsed > 90) {
  await sendAlert({
    level: 'CRITICAL',
    message: `Only ${remaining} requests remaining`,
  });
} else if (percentageUsed > 75) {
  await sendAlert({
    level: 'WARNING',
    message: `${percentageUsed}% of quota used`,
  });
}
}
 
// Run daily
setInterval(dailyUsageCheck, 24 * 60 * 60 * 1000);

// Automated key rotation
async function scheduleKeyRotation(partnerId) {
const NINETY_DAYS = 90 * 24 * 60 * 60 * 1000;
 
setInterval(async () => {
  console.log('Rotating API key...');
  
  try {
    const result = await rotateApiKey(partnerId);
    
    // Update all services with new key
    await updateAllServices(result.newApiKey);
    
    console.log('✅ Key rotation complete');
  } catch (error) {
    console.error('❌ Key rotation failed:', error);
    await notifyAdmins(error);
  }
}, NINETY_DAYS);
}

async function makeRequestWithRetry(endpoint, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
  try {
    const response = await fetch(endpoint, options);
    
    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitTime = new Date(resetTime) - new Date();
      
      console.log(`Rate limited. Waiting ${waitTime}ms...`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }
    
    return response.json();
  } catch (error) {
    if (i === maxRetries - 1) throw error;
  }
}
}