Developer Guide & API Reference

🌐 1. Ecosystem Architecture & Multi-Tenancy

The Grapphen Cloud OS operates as a high-throughput, multi-tenant enterprise system. Four core services work together via standardized REST, Webhook, and Real-Time WebSocket channels:

🎯 Grapphen ATS

AI candidate sourcing, automated JD parsing, pipeline stage automation, and candidate dispatch.

🎙️ Grapphen Vox

STIR/SHAKEN Tier-1 SIP trunking, WebRTC softphone token issuance, 10DLC SMS, and call flip.

📹 Grapphen Rooms

Low-latency WebRTC SFU Mesh, collaborative code sandbox, anti-cheat proctoring, and RTMP recording.

✉️ Grapphen Mail

High-deliverability MTA, 2048-bit DKIM, automated SPF/DMARC/BIMI sync, and warmup curves.

🔐 2. Authentication & Multi-Tenancy

Grapphen uses standard HTTP Bearer authentication via cryptographic API Tokens. All API requests must be transmitted over HTTPS.

Header	Value	Description
Authorization	`Bearer <YOUR_API_TOKEN>`	Required. Master or Tenant-specific Sanctum API key.
X-Tenant-ID	`tenant_org_9283fa`	Required for multi-tenant accounts to scope data isolation.
X-Grapphen-Secret	`<ECOSYSTEM_SSO_SECRET>`	Required for inter-service SSO handshakes between Vox, Rooms, and Mail.

🎯 3. Grapphen ATS API Reference

Manage talent acquisition, parse unstructured resumes and job descriptions using enterprise Gemini AI, and dispatch submissions.

POST /api/ecosystem/ats/parse-jd

AI JD Parsing

Extracts structured job requirements, tech stack, salary bands, and security clearance criteria from raw job descriptions.

Request Payload (JSON)

{
  "title": "Senior Cloud Systems Architect",
  "description": "Looking for an AWS expert with 7+ years of Kubernetes, Terraform, and SOC-2 compliance...",
  "department": "Infrastructure"
}

POST /api/ecosystem/ats/parse-resume

Resume Parser

Uploads a candidate CV (PDF, DOCX, TXT) and returns structured contact, education, work experience, and verified skills.

POST /api/ecosystem/ats/create-candidate

Candidate Pipeline

Inserts candidate profile directly into the talent database or associates them with an active requisition.

🎙️ 4. Grapphen Vox Telephony & Voice AI API

Interact with Sofia Voice AI, issue WebRTC softphone tokens, send 10DLC carrier-registered SMS, and access AI call summaries.

GET /api/token

WebRTC Token Issuance

Generates a dynamic 45-minute cryptographically signed WebRTC softphone access token for browser and mobile softphones.

Response (JSON)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.t-78abx92...",
  "identity": "agent_alex_ext_104",
  "expires_in": 2700
}

POST /api/mobile/sms/send

10DLC Carrier Compliant SMS

Dispatches two-way business text messages with automatic STOP/UNSUBSCRIBE compliance checks.

POST /api/call/flip

Call Flip Handoff

Seamlessly transfers an active phone call between mobile softphone (iOS/Android) and desktop web browser without dropping.

📹 5. Grapphen Rooms WebRTC & Code Sandbox API

Provision live technical interview sessions with synchronized Monaco code editors, real-time audio/video SFU mesh, and proctoring telemetry.

POST /api/v1/meetings

Provision Room

Creates an interview room instance with isolated code execution sandbox (Python, Node.js, Go, Java, Rust, C++).

GET /api/v1/meetings/{id}/artifacts

Telemetry & Code Snapshots

Fetches candidate code test results, whiteboard vector drawings, and gaze-tracking anti-cheat metrics.

✉️ 6. Grapphen Mail High-Deliverability MTA API

Manage sending domains, automatically verify DNS records (SPF, 2048-bit DKIM, DMARC, BIMI, MTA-STS), and dispatch transactional & campaign emails.

POST /api/v1/domains/{id}/verify

DNS Deliverability Check

Triggers real-time DNS queries against authoritative name servers to validate SPF, DKIM selector, DMARC p=reject/quarantine policy, and BIMI SVG certificates.

POST /api/v1/emails/send

Outbound Send

Injects email into Postfix/Rust high-deliverability spool with custom tracking pixels and open/click telemetry.

⚡ 7. Webhooks & HMAC Signature Verification

Subscribe to asynchronous events across the Grapphen ecosystem. Every webhook delivery includes an X-Grapphen-Signature header generated using HMAC-SHA256.

Verifying Signatures (Node.js & PHP)

// Node.js Example
const crypto = require('crypto');

function verifyWebhook(rawPayload, headerSignature, webhookSecret) {
    const expectedSignature = crypto
        .createHmac('sha256', webhookSecret)
        .update(rawPayload)
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(headerSignature),
        Buffer.from(expectedSignature)
    );
}

Supported Webhook Event Types:

ats.candidate.created — Dispatched when a candidate profile is ingested
ats.application.status_changed — Fired when an applicant moves through hiring stages
vox.call.completed — Dispatched with duration, recording URL, and AI transcription
vox.sms.received — Inbound SMS received on a tracked phone number
rooms.meeting.ended — Interview concluded; includes code execution summary and report
mail.message.delivered / mail.message.bounced — Mail delivery receipts

💻 8. Code Samples & SDK Quickstart

Send an API request using your preferred language:

curl -X POST "https://api.grapphen.com/v1/ecosystem/ats/check-sender" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "X-Tenant-ID: your-org-slug" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

⚠️ 9. Rate Limits & HTTP Status Codes

All API endpoints employ token bucket rate limiting to ensure 99.99% service availability.

Endpoint Type	Default Quota	Burst Limit
Standard REST CRUD (ATS, Mail, Vox)	120 requests / min	200 requests / min
AI Parsers (Resume & JD Extraction)	30 requests / min	50 requests / min
WebRTC Softphone Token Issuance	60 requests / min	100 requests / min