Quick Start

Get Started in 5 Minutes

Follow these simple steps to start using KhaleejiAPI in your applications.

New here? Start with Hello World.

Our step-by-step guide makes your first API call in 60 seconds — with code snippets for cURL, TypeScript SDK, Python SDK, Go, and PHP.

Hello World guide
1

Create an Account & Get Your API Key

Sign up for a free account to get your API key. You'll get 1,000 free requests per month to start.

Create Free AccountSign In
2

Make Your First API Call

Use our official SDKs or call the REST API directly. All endpoints are available at https://khaleejiapi.dev/api/v1/

Important: REST requests must use the Authorization header with the bearer scheme. Sending the raw key by itself or using x-api-key will return 401 Unauthorized.

Authentication header format

REST clients like cURL, fetch, requests, Go, and PHP must send the Authorization header shown above exactly once per request. Official SDKs attach it for you automatically, so SDK constructors should receive the raw key only.

bash
Authorization: Bearer <YOUR_API_KEY>

Replace your_api_key_here with your actual API key. Get your API key →

The REST examples below set the header themselves. If you use an official SDK instead, pass only the raw key to the client constructor and let the SDK add the header.

Set your key once

bash
export KHALEEJI_API_KEY=your_api_key_here

Install an SDK (recommended)

bash
# JavaScript / TypeScript
npm install @khaleejiapi/sdk
 
# Python
pip install khaleejiapi

cURL

bash
curl -X GET "https://khaleejiapi.dev/api/v1/email/[email protected]" \
  -H "Authorization: ******" \
  -H "Content-Type: application/json"

JavaScript / TypeScript

javascript
// Using fetch (Node.js 18+, Deno, Bun)
const apiKey = process.env.KHALEEJI_API_KEY;
if (!apiKey) throw new Error('KHALEEJI_API_KEY not set');
 
const response = await fetch(
  'https://khaleejiapi.dev/api/v1/email/[email protected]',
  {
    headers: {
      'Authorization': `******
      'Content-Type': 'application/json',
    },
  }
);
 
const data = await response.json();
console.log(data);
// {
//   data: {
//     email: "[email protected]",
//     valid: true,
//     deliverabilityScore: 98,
//     reason: "Valid email address",
//     checks: { syntax: true, disposable: true, mx: true, role: false, freeProvider: false }
//   },
//   meta: { timestamp: "2025-07-01T12:00:00.000Z" }
// }

Python

python
import os
import requests
 
api_key = os.environ["KHALEEJI_API_KEY"]
 
response = requests.get(
    "https://khaleejiapi.dev/api/v1/email/validate",
    params={"email": "[email protected]"},
    headers={"Authorization": f"******"}
)
 
data = response.json()
print(data["data"]["valid"])  # True

Go

go
package main
 
import (
    "fmt"
    "io"
    "net/http"
    "os"
)
 
func main() {
    apiKey := os.Getenv("KHALEEJI_API_KEY")
    if apiKey == "" {
        panic("KHALEEJI_API_KEY not set")
    }
 
    req, _ := http.NewRequest(
        http.MethodGet,
        "https://khaleejiapi.dev/api/v1/email/[email protected]",
        nil,
    )
    req.Header.Set("Authorization", "Bearer " + apiKey)
 
    res, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()
 
    body, _ := io.ReadAll(res.Body)
    fmt.Println(string(body))
}

PHP

php
<?php
$apiKey = getenv('KHALEEJI_API_KEY');
if ($apiKey === false || $apiKey === '') {
    throw new RuntimeException('KHALEEJI_API_KEY not set');
}
 
$response = file_get_contents(
    "https://khaleejiapi.dev/api/v1/email/[email protected]",
    false,
    stream_context_create([
        "http" => [
            "header" => "Authorization: Bearer " . $apiKey,
        ],
    ])
);
 
echo $response;

Decode first-call errors fast

  • 401 UNAUTHORIZED / INVALID_API_KEY_FORMAT / INVALID_API_KEY: the header is missing, missing the Bearer prefix, sent via x-api-key, or using the wrong key value.
  • 404 Not Found: the path should start with /api/v1/, not /v1/.
  • 400 VALIDATION_ERROR: the endpoint received the wrong query string or JSON body shape.
  • 429 RATE_LIMIT_EXCEEDED: slow down and respect Retry-After. See Rate Limits.
Authentication fixes · Full troubleshooting guide
3

Explore Available APIs

We offer 26+ APIs for the Middle East — email validation, IP geolocation, VAT calculation, exchange rates, Islamic finance, and more. Browse the full catalog to find what you need.

Browse APIsSDKs & Libraries

Tip: Never expose your API key in client-side code. Always keep it on the server or use environment variables.

4

Monitor API Status

KhaleejiAPI provides two health check endpoints so you can monitor platform availability from your own infrastructure.

GET /api/v1/ping — Unauthenticated liveness

Returns HTTP 200 with { ok: true } instantly — no API key needed. Use this for uptime monitors (UptimeRobot, Freshping) and load-balancer health checks.

bash
curl https://khaleejiapi.dev/api/v1/ping
# → { "ok": true }

GET /api/v1/health — Authenticated diagnostics

Returns a detailed breakdown of platform version, region, uptime, and subsystem status. Requires your API key. Returns HTTP 503 when any subsystem is degraded.

bash
curl https://khaleejiapi.dev/api/v1/health \
  -H "Authorization: Bearer ******"
# → { data: { status: "healthy", version: "1.3.0", checks: { validation: "healthy" } } }

See the Health & Liveness docs for full details and monitoring integration examples.

Next Steps

Hello World guide

Step-by-step walkthrough with code for cURL, TypeScript SDK, Python SDK, Go, and PHP.

Authentication

Learn about API keys and security best practices.

Rate Limits

Understand rate limits and how to handle them.

Explore APIs

Explore all APIs available on KhaleejiAPI.

Health & Liveness

Monitor platform status with ping and health endpoints.

SDKs & Libraries

Find SDKs for your preferred programming language.