Graphoid API Reference

Quick Start

Get your first API call running in under 5 minutes.

Step 1 — Get your API key from Settings → Developer → API Keys

Step 2 — Make your first request:

curl

curl https://api.graphoid.io/v2/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Step 3 — Parse the response:

json response

{
  "status": "success",
  "data": {
    "leads": [...],
    "total": 48,
    "page": 1,
    "per_page": 25
  },
  "meta": {
    "request_id": "req_2hG7x...",
    "timestamp": "2026-04-03T10:24:00Z"
  }
}

Authentication

All API requests must include your API key in the Authorization header using Bearer token format.

http header

Authorization: Bearer gph_live_xxxxxxxxxxxxxxxxxxxx

API keys are prefixed with gph_live_ for production and gph_test_ for sandbox. Never expose keys in client-side code.

Keys can be scoped to specific permissions (read-only, write, admin) from your dashboard. Rotate keys without downtime using the key rotation API.

Base URL & Versioning

base url

https://api.graphoid.io/v2/

All endpoints are versioned. The current stable version is v2. We maintain backward compatibility within a major version and give 6 months notice before deprecating any endpoint.

Leads

Create, read, update leads and their associated activities.

Endpoint	Method	Description
/leads	GET	List all leads with pagination and filters
/leads	POST	Create a new lead
/leads/{id}	GET	Get a single lead by ID
/leads/{id}	PUT	Update lead details or status
/leads/{id}/activities	GET	Get all activities for a lead
/leads/{id}/mindmap	GET	Get AI-generated mind map for a lead

javascript — create lead

const response = await fetch('https://api.graphoid.io/v2/leads', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corp',
    contact_email: 'procurement@acme.com',
    value: 45000,
    status: 'qualified',
    assigned_to: 'user_8x2k...'
  })
});

const { data } = await response.json();
console.log(data.lead.id); // lead_9pQr...

Tickets & Support

Manage service tickets, SLA tracking, and escalations programmatically.

Endpoint	Method	Description
/tickets	GET	List tickets with status/SLA filters
/tickets	POST	Open a new service ticket
/tickets/{id}/resolve	POST	Mark a ticket as resolved
/tickets/{id}/escalate	POST	Manually escalate a ticket

Analytics & AI

Access the Graphoid AI Intelligence Center programmatically. Returns the same insights shown in your dashboard.

Endpoint	Method	Description
/ai/health-score	GET	Business health score (0–100) + label
/ai/forecast	GET	30-day AI forecast based on pipeline
/ai/insights	GET	Ranked AI insights across all departments
/ai/risks	GET	Active risk signals by severity
/ai/recommendations	GET	Prioritized action items (High/Medium/Low)

AI responses are cached for 15 minutes. Use ?force_refresh=true to bypass cache (counts against rate limit).

Attendance

Query GPS attendance records, punch-in/out times, and field team locations.

Endpoint	Method	Description
/attendance	GET	List attendance records with date/user filters
/attendance/live	GET	Real-time field team location snapshot
/attendance/{user_id}/summary	GET	Monthly summary for a user

Rate Limits

Rate limits are applied per API key per endpoint category.

Plan	Standard endpoints	AI endpoints	Burst
Starter	1,000 / hour	50 / hour	100 / min
Business	5,000 / hour	200 / hour	500 / min
Enterprise	Unlimited	1,000 / hour	Configurable

Rate limit headers are returned on every response: X-RateLimit-Remaining and X-RateLimit-Reset.

Error Codes

HTTP Code	Error	Meaning
200	OK	Success
400	Bad Request	Invalid parameters or request body
401	Unauthorized	Missing or invalid API key
403	Forbidden	Key lacks permission for this endpoint
429	Rate Limited	Too many requests — check Retry-After header
500	Server Error	Contact support with your request_id

Official SDKs

Drop-in libraries with TypeScript types, automatic retry logic, and full API coverage.

JavaScript / TypeScript

npm install @graphoid/sdk

Python

pip install graphoid

PHP

composer require graphoid/php-sdk