Credential Verification API — ICONIC Board for Organizations

Overview

The ICONIC Board Verification API provides real-time access to practitioner credential records. Query by credential number and receive live status, tier details, expiration dates, and endorsements in a single response.

Base URL: https://iconicboard.health
All requests are served over HTTPS. HTTP requests are not supported.

Who Should Use This API?

HR Departments & Employers — Automate background checks for holistic health hires
Insurance Carriers — Verify credentials before processing claims or issuing policies
Staffing Agencies — Confirm practitioner standing during placement
Credentialing Services — Integrate ICONIC Board status into your existing verification workflow
ATS Providers — Add live credential verification to applicant profiles

Looking for a no-code option? The Employer Verification Portal provides the same data in a web interface — including printable PDF verification letters. No API key or technical setup required.

Authentication

All API requests require an API key. Pass your key in the X-API-Key request header. API keys are issued upon approval of your registration request.

HTTP Header

X-API-Key: ibc_your_api_key_here

Keep your API key secret. Do not expose it in client-side code, public repositories, or logs. If your key is compromised, contact credentials@iconicboard.health for immediate revocation and reissuance.

Alternatively, you may pass the key as a query parameter (not recommended for production):

                        Query Parameter (not recommended)
                    
GET /api/verify/{credentialId}?api_key=ibc_your_key

Rate Limits

API keys are rate-limited on a rolling 24-hour basis. Limits reset at midnight UTC.

Standard

100 requests / day

Default for all approved API keys. Sufficient for most HR verification workflows.

High-Volume
Custom
For insurance carriers, staffing platforms, or credentialing services with higher volume needs. Contact us to discuss.

When your rate limit is exceeded, the API returns a 429 Too Many Requests response. The X-RateLimit-Reset header indicates when your quota resets (UTC epoch seconds).

                        429 Response Headers
                    
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
Content-Type: application/json

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Daily request limit of 100 exceeded. Resets at midnight UTC."
}

Error Codes

Status	error field	Meaning
`401`	`api_key_required`	No API key provided
`403`	`invalid_api_key`	Key not found, inactive, or pending approval
`404`	`not_found`	Credential number not found in registry
`429`	`rate_limit_exceeded`	Daily request quota exceeded
`500`	`server_error`	Internal error — retry with exponential backoff

Endpoints

GET /api/verify/{credentialId}

Verify a practitioner's credential by credential number (e.g., IBC-HHA-2026-001). Returns live status, tier details, expiration, and endorsements. Requires a valid, approved API key.

Path Parameters

Parameter	Type	Required	Description
`credentialId`	`string`	Required	Practitioner credential number. Case-insensitive. Example: `IBC-HHA-2026-001`

Example Request

curl -X GET \
  https://iconicboard.health/api/verify/IBC-HHA-2026-001 \
  -H "X-API-Key: ibc_your_api_key_here"

                        Response (200 — Verified)
                    
{
  "success": true,
  "verified": true,
  "practitioner": {
    "name": "Jane Smith",
    "credential_number": "IBC-HHA-2026-001",
    "credential_tier": "IBC-HHA",
    "credential_title": "ICONIC Board Certified Holistic Health Advisor",
    "status": "active",
    "issued_date": "2026-01-15",
    "expiry_date": "2028-01-15",
    "specialties": ["Nutrition", "Stress Management"]
  },
  "board": {
    "name": "ICONIC Board of Holistic Health",
    "verification_url": "https://iconicboard.health/verify/IBC-HHA-2026-001",
    "verified_at": "2026-04-08T23:38:00Z"
  }
}

                        Response (200 — Not Verified / Lapsed)
                    
{
  "success": true,
  "verified": false,
  "practitioner": {
    "name": "John Doe",
    "credential_number": "IBC-HHA-2024-100",
    "credential_tier": "IBC-HHA",
    "credential_title": "ICONIC Board Certified Holistic Health Advisor",
    "status": "expired",
    "issued_date": "2024-03-01",
    "expiry_date": "2026-03-01",
    "specialties": []
  },
  "board": {
    "name": "ICONIC Board of Holistic Health",
    "verification_url": "https://iconicboard.health/verify/IBC-HHA-2024-100",
    "verified_at": "2026-04-08T23:38:00Z"
  }
}

                        Response (404 — Not Found)
                    
{
  "success": false,
  "verified": false,
  "error": "not_found",
  "practitioner": null,
  "board": {
    "name": "ICONIC Board of Holistic Health",
    "verified_at": "2026-04-08T23:38:00Z"
  }
}

GET /api/api-keys/my-key

Returns metadata for the authenticated API key — rate limit, usage today, approval status, and last-used timestamp. Useful for building dashboards or monitoring usage.

                        Example Response
                    
{
  "success": true,
  "key": {
    "organization_name": "Acme Wellness Staffing",
    "contact_email": "compliance@acmewellness.com",
    "use_case": "HR credential verification for holistic health hires",
    "is_active": true,
    "is_approved": true,
    "rate_limit": 100,
    "requests_today": 14,
    "created_at": "2026-02-10T09:00:00Z",
    "last_used_at": "2026-04-08T18:22:00Z"
  }
}

POST /api/api-keys/register

Submit a request for API access. Keys are reviewed and approved manually within 1–2 business days. No authentication required. You will receive an email once your key is ready.

Request Body (JSON)

Field	Type	Required	Description
`organization_name`	`string`	Required	Legal name of your organization
`contact_email`	`string`	Required	Email address where your API key will be delivered
`use_case`	`string`	Optional	Brief description of how you will use the API. Helps with faster approval.

Response Schema

Practitioner Object

name string Practitioner's display name as registered with ICONIC Board

credential_number string Unique credential identifier (e.g., IBC-HHA-2026-001)

credential_tier string Credential type code (e.g., IBC-HHA, IBC-HHP, IBC-HHE)

credential_title string Full credential title (e.g., "ICONIC Board Certified Holistic Health Advisor")

status string One of: active, expired, suspended, revoked, grace_period, lapsed

issued_date string ISO 8601 date when credential was issued (YYYY-MM-DD)

expiry_date string | null ISO 8601 expiration date, or null if no expiration set

specialties string[] Array of specialty endorsements held. Empty array if none.

Credential Status Values

The status field reflects live registry data. Only active and grace_period return verified: true.

Status	verified	Meaning
`active`	true	Credential is current and in good standing
`grace_period`	true	Renewal pending; credential still considered valid
`expired`	false	Credential passed expiration without renewal
`lapsed`	false	Renewal overdue; reinstatement may be available
`suspended`	false	Temporarily suspended pending ethics or conduct review
`revoked`	false	Permanently revoked; practitioner may not use ICONIC designations

Code Examples

Node.js (fetch)

JavaScript

async function verifyCredential(credentialNumber) {
  const res = await fetch(
    `https://iconicboard.health/api/verify/${credentialNumber}`,
    {
      headers: {
        'X-API-Key': process.env.ICONIC_API_KEY
      }
    }
  );

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

  const data = await res.json();
  return {
    verified: data.verified,
    status: data.practitioner?.status,
    name: data.practitioner?.name,
    expiresAt: data.practitioner?.expiry_date
  };
}

// Usage:
const result = await verifyCredential('IBC-HHA-2026-001');
console.log(result.verified); // true or false

Python (requests)

Python

import requests
import os

def verify_credential(credential_number):
    response = requests.get(
        f"https://iconicboard.health/api/verify/{credential_number}",
        headers={"X-API-Key": os.environ["ICONIC_API_KEY"]}
    )
    response.raise_for_status()
    data = response.json()
    return data

result = verify_credential("IBC-HHA-2026-001")
print(result["verified"])  # True or False
print(result["practitioner"]["status"])  # "active"

cURL

Shell

curl -X GET \
  "https://iconicboard.health/api/verify/IBC-HHA-2026-001" \
  -H "X-API-Key: ibc_your_api_key" \
  -H "Accept: application/json" | jq .

Request API Access

API access is available to qualified organizations — employers, staffing agencies, insurance carriers, and credentialing services. Keys are reviewed and issued within 1–2 business days.

Organization Name *

Work Email Address *

How Will You Use the API?

✓ Your request has been submitted. You'll receive an email at the address provided once your API key is approved — typically within 1–2 business days.

Prefer no-code verification? Use the Employer Verification Portal — search credentials and download PDF verification letters instantly, no API key required.