Verification API

Introduction

The ICONIC Board Verification API lets employers, insurers, and platform operators verify practitioner credentials in real-time. Search by credential number or practitioner name to confirm active status, tier information, and expiry dates.

How to get your API key

1. Register for an employer account at the Employer Verification Portal.
2. Upgrade your plan to Professional or Enterprise to unlock API access. Free-tier accounts do not include API keys.
3. Generate a key from your employer dashboard under Settings → API Keys. Keys are prefixed with ik_live_ for production and ik_test_ for sandbox.

Authentication

Authenticate every request using your API key. You can send it as a header (recommended) or as a query parameter.

Header authentication (recommended)

X-API-Key: ik_live_your_api_key_here

Query parameter authentication

GET /api/v1/verify?credential_number=HHC-2025-001&api_key=ik_live_your_api_key_here

Base URL

All API requests should be made to the following base URL:

https://iconic-board.polsia.app/api/v1

All endpoints described in this documentation are relative to this base URL. The API accepts and returns JSON exclusively. Set the Accept: application/json header on all requests.

Rate Limits

Rate limits are enforced per API key and reset at midnight UTC. Check the response headers to monitor your current usage.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994
X-RateLimit-Reset: 1735689600

API Endpoints

The verification API exposes two endpoints: a search endpoint for looking up credentials by name or number, and a direct-lookup endpoint for verifying a specific credential.

Status Values

The status field in the response indicates the current state of a credential. Use this to determine whether to accept a practitioner's credential.

Error Responses

When an error occurs, the API returns a JSON object with success: false and a descriptive message field.

Error response format

{
  "success": false,
  "message": "Invalid or missing API key",
  "code": "UNAUTHORIZED"
}

Code Examples

Copy-paste these examples to quickly integrate the verification API into your application.

// Verify a credential by number
const verifyCredential = async (credentialNumber) => {
  const response = await fetch(
    `https://iconic-board.polsia.app/api/v1/verify/${credentialNumber}`,
    {
      method: 'GET',
      headers: {
        'X-API-Key': process.env.ICONIC_API_KEY,
        'Accept': 'application/json',
      },
    }
  );

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const data = await response.json();

  if (data.found && data.results[0].status === 'active') {
    console.log('Credential is valid!');
  }

  return data;
};

// Search by practitioner name
const searchByName = async (name) => {
  const params = new URLSearchParams({ name });
  const response = await fetch(
    `https://iconic-board.polsia.app/api/v1/verify?${params}`,
    {
      headers: {
        'X-API-Key': process.env.ICONIC_API_KEY,
      },
    }
  );
  return response.json();
};

import requests
import os

API_KEY = os.environ["ICONIC_API_KEY"]
BASE_URL = "https://iconic-board.polsia.app/api/v1"

def verify_credential(credential_number):
    """Verify a single credential by its number."""
    response = requests.get(
        f"{BASE_URL}/verify/{credential_number}",
        headers={"X-API-Key": API_KEY},
    )
    response.raise_for_status()
    return response.json()

def search_by_name(name):
    """Search for credentials by practitioner name."""
    response = requests.get(
        f"{BASE_URL}/verify",
        headers={"X-API-Key": API_KEY},
        params={"name": name},
    )
    response.raise_for_status()
    return response.json()

# Example usage
result = verify_credential("HHC-2025-001")

if result["found"]:
    cred = result["results"][0]
    print(f"{cred['practitioner_name']} - {cred['status_display']}")
else:
    print("Credential not found")

# Verify by credential number (direct lookup)
curl -s -X GET \
  "https://iconic-board.polsia.app/api/v1/verify/HHC-2025-001" \
  -H "X-API-Key: ik_live_abc123xyz789" \
  -H "Accept: application/json" | jq '.'

# Search by practitioner name
curl -s -X GET \
  "https://iconic-board.polsia.app/api/v1/verify?name=Jane%20Smith" \
  -H "X-API-Key: ik_live_abc123xyz789" | jq '.'

# Search by credential number (partial match)
curl -s -X GET \
  "https://iconic-board.polsia.app/api/v1/verify?credential_number=HHC-2025" \
  -H "X-API-Key: ik_live_abc123xyz789" | jq '.'

# Using query parameter authentication
curl -s -X GET \
  "https://iconic-board.polsia.app/api/v1/verify/HHC-2025-001?api_key=ik_live_abc123xyz789" | jq '.'

Webhooks

Get notified in real-time when a practitioner's credential status changes. Webhooks are available exclusively on Enterprise plans and deliver a POST request to your configured endpoint whenever a status transition occurs.

Webhook events

Webhook payload format

{
  "event": "credential.status_changed",
  "timestamp": "2025-06-15T14:30:00.000Z",
  "data": {
    "credential_number": "HHC-2025-001",
    "practitioner_name": "Jane Smith",
    "previous_status": "active",
    "new_status": "grace_period",
    "changed_at": "2025-06-15T14:30:00.000Z",
    "verify_url": "/verify/abc123"
  }
}

Webhooks include a X-Iconic-Signature header for payload verification. Compute an HMAC-SHA256 of the raw request body using your webhook secret and compare it to the header value.

Pricing & Plans

Choose the plan that fits your verification needs. All plans include access to the verification search UI. API access requires Professional or higher.