GigID™ / IndieID™ API

Build verified worker identity
into your platform.

The GigID™ API gives your platform access to verified income identities for independent workers — the same infrastructure banks, landlords, and insurers use to confirm a worker is real, active, and earning. Free up to 1,000 verifications/month. Revenue share from day one.

20 min

Drop-in widget integration

Free

Up to 1,000 workers/month

$3–$12

Per B2B verification query

✓ GDPR · CCPA · LGPD compliant ✓ Consent-first by design ✓ REST API · JSON ✓ Drop-in widget available

Quickstart

Live in 20 minutes

Four steps from signup to your first verified worker.

1

Get your sandbox key

Sign up at identity.mavvrixx.ai/partners — your sandbox API key is issued instantly. No approval needed.

2

Add the widget (2 lines of HTML)

HTML
<div id="gigid-widget"></div>
<script
  src="https://identity.mavvrixx.ai/api/widget/gigid.js"
  data-partner-id="YOUR_PARTNER_ID"
  data-container="gigid-widget"
  data-theme="dark"
  data-ref="YOUR_AFFILIATE_CODE">
</script>

3

Listen for worker events

JavaScript
window.addEventListener('message', (event) => {
  const { type, gigId, level, gigScore } = event.data;

  if (type === 'GIGID_CLAIMED') {
    // Worker claimed their GigID — ID issued
    console.log('New worker:', gigId, level);
  }

  if (type === 'GIGID_VERIFIED') {
    // Worker reached Level 2 or 3 — income verified
    console.log('Verified:', gigId, 'Score:', gigScore);
  }

  if (type === 'GIGID_SHARED') {
    // Worker shared their badge — viral loop event
  }
});

4

Query a worker's income (B2B)

cURL

curl -G https://identity.mavvrixx.ai/api/v1/identity/verify \
  -d gigId=GID-US-288867 \
  -d partnerId=YOUR_PARTNER_ID \
  -d consentRef=CONS-xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication

All API requests require a Bearer token in the Authorization header.

HTTP Header
Authorization: Bearer gid_test_sk_a7f2e1b9c3d84f6e7a8b2c1d3e4f5a6b

Sandbox vs Production: Sandbox keys begin with gid_test_sk_. Production keys begin with gid_live_sk_. Sandbox mode logs all requests and never triggers real income queries or billing.

Identity API

POST /api/v1/identity/claim Issue a GigID™ or IndieID™

Creates a new verified worker identity at Level 1 — Declared. Fires a welcome email with badge and magic link automatically.

Request body

Parameter	Type	Required	Description
email	string	required	Worker's email address. Unique per identity.
type	string	required	`"GIG"` for platform workers, `"INDIE"` for professional independents.
market	string	optional	2-letter country code. Default: `"US"`. Sets ID prefix: `GID-US-XXXXXX`.
ref	string	optional	Affiliate/partner referral code. Stored on worker record for revenue share attribution.

Response 201
{
  "success": true,
  "identity": {
    "id": "cmn92r3s40000w7yr...",
    "gigId": "GID-US-288867",
    "type": "GIG",
    "level": "LEVEL_1",
    "gigScore": 300,
    "email": "worker@example.com",
    "market": "US",
    "ref": "partner_upwork_001",
    "createdAt": "2026-03-28T00:00:00.000Z"
  }
}

POST /api/v1/identity/connect Connect a platform → Level 2

Connects a gig platform to the worker's identity. Triggers upgrade to Level 2 (Verified) and updates GigScore. Fires a level-up email automatically.

Parameter	Type	Required	Description
identityId	string	required	Internal identity ID (from /claim response).
platform	string	required	Platform name: `uber`, `doordash`, `upwork`, `grab`, `deliveroo`, etc.
oauthCode	string	optional	OAuth authorization code from platform. Enables real income data pull (production).

GET /api/v1/identity/verify B2B income verification query (paid)

Verifies a worker's identity and income signal. Requires worker consent. This is the paid endpoint — $3–$12/query depending on your plan. Worker must be Level 3 (isQueryable = true).

Parameter	Type	Required	Description
gigId	string	required	The worker's GigID (e.g. `GID-US-288867`).
partnerId	string	required	Your partner ID (from /partners/identity/setup).
consentRef	string	required	Consent record reference. Worker must have granted consent for this query.

Response 200
{
  "verified": true,
  "gigId": "GID-US-288867",
  "level": "LEVEL_3",
  "gigScore": 650,
  "incomeSignal": "ACTIVE",
  "kycVerified": true,
  "platforms": ["uber"],
  "market": "US",
  "queryId": "qry_...",
  "queriedAt": "2026-03-28T00:00:00.000Z"
}

Badge API

All badge endpoints return SVG. Embed directly in email, web, LinkedIn, or WhatsApp.

Variant	Endpoint	Dimensions	Use case
Standard	`/badge/:id`	540×300	LinkedIn, website embed
Square	`/badge/:id/square`	320×320	Profile photo overlay, WhatsApp
Mini	`/badge/:id/mini`	280×72	Email signature
Animated	`/badge/:id/animated`	360×360	TikTok, Instagram, social
OG Image	`/badge/:id/og`	1200×630	Open Graph / link previews

HTML — embed a badge
<!-- Standard badge -->
<img src="https://identity.mavvrixx.ai/api/v1/identity/GID-US-288867/badge"
     alt="GigID Verified" width="540" height="300">

<!-- Email signature mini -->
<img src="https://identity.mavvrixx.ai/api/v1/identity/GID-US-288867/badge/mini"
     alt="GigID™ Certified" width="280" height="72">

Drop-in Widget

The fastest integration. Two lines of HTML. Handles the full claim flow — email, platform connect, badge display. Workers never leave your page.

HTML
<div id="gigid-widget"></div>
<script
  src="https://identity.mavvrixx.ai/api/v1/widget/gigid.js"
  data-partner-id="pid_7f3a2e1d"
  data-container="gigid-widget"
  data-theme="dark"       <!-- or "light" -->
  data-type="gig"          <!-- or "indie" -->
  data-market="US"         <!-- 2-letter country code -->
  data-ref="your_ref_code" <!-- affiliate tracking -->
></script>

The widget fires postMessage events your page can listen to:

Event type	When	Payload
GIGID_CLAIMED	Worker submits email — ID issued	`{ gigId, level, gigScore, type }`
GIGID_VERIFIED	Worker connects platform — Level 2	`{ gigId, level, gigScore, platform }`
GIGID_CERTIFIED	Worker completes KYC — Level 3	`{ gigId, level, gigScore }`
GIGID_SHARED	Worker clicks share button	`{ gigId, channel }`

View live widget demo →

GigScore™ Formula

GigScore is a portable income confidence score accepted by partner lenders, landlords, and insurers as equivalent to a payslip-based credit signal.

Formula
GigScore = 300                          // Base (all Level 1 workers)
         + (75 × platforms_connected)      // Max 3 platforms counted
         + 50  (if Level 2 or higher)     // Verification bonus
         + 150 (if KYC verified)          // Identity confirmation bonus

// Maximum possible: 300 + 225 + 50 + 150 = 725

Score range	Interpretation	Level
300	Declared — email claimed, no verification	Level 1
375–525	Verified — 1–3 platforms connected	Level 2
575–725	Certified — KYC verified, income confirmed	Level 3

Referral & Affiliate Tracking

Pass a ref parameter to attribute workers to your partner account for revenue share calculations.

URL Parameter
# Worker lands from your platform with your ref code
https://identity.mavvrixx.ai/claim?ref=YOUR_PARTNER_CODE

# Or pass in the widget
data-ref="YOUR_PARTNER_CODE"

# Or pass directly to the API
POST /api/v1/identity/claim
{ "email": "...", "type": "GIG", "ref": "YOUR_PARTNER_CODE" }

Workers referred via your code are attributed to your partner account. Revenue share is calculated monthly — $0.50–$2.00 per verified worker + 20% of B2B query revenue generated from your referred workers.

Error Codes

HTTP Status	Code	Meaning
400	MISSING_PARAMS	Required parameters not provided
400	INVALID_TYPE	type must be "GIG" or "INDIE"
401	UNAUTHORIZED	Missing or invalid API key
403	CONSENT_REQUIRED	Worker has not granted consent for this query
404	NOT_FOUND	Identity not found for this GigID
409	ALREADY_CLAIMED	Email has already claimed an identity
402	NOT_QUERYABLE	Worker not yet at Level 3 — cannot be queried
429	RATE_LIMITED	Too many requests — back off and retry

Build verified worker identityinto your platform.