API Documentation

This technical documentation provides everything needed for technology providers to integrate GUIP identity services into their applications. Use our secure RESTful APIs to verify citizens, fetch KYC levels, and handle identity-driven authentication.

Base URL

https://api.guip.gov.earth

All API endpoints are relative to this base URL. Ensure you use HTTPS for all requests.

Authentication & Security

All API requests must be authenticated to access government identity services.
Include the X-API-KEY header in all your requests.
Keys are issued via the Partner Portal after successful organization verification.
Security Warning: Keep your API key secure. Never expose it in client-side code (e.g., frontend browsers).

Example Authentication Request

curl -X GET https://api.guip.gov.earth/api/v1/user/{id} \
  -H "X-API-KEY: YOUR_PARTNER_KEY"

Core Endpoints

GET/api/v1/user/{id}

Description: Fetch user identity details using GUIP ID.

Parameters

Name	In	Description
id	path	The 12-digit GUIP ID of the user.

Example Request

curl -X GET "https://api.guip.gov.earth/api/v1/user/123456789012" \
  -H "X-API-KEY: YOUR_PARTNER_KEY"

Successful Response (200 OK)

{
  "guip_id": "123456789012",
  "name": "Rahul Sharma",
  "kyc_status": "verified"
}

Error Response (4xx)

{
  "error": "Invalid API Key"
}

POST/api/v1/generate-id

Description: Registers a new user and generates a unique 12-digit GUIP ID.

Parameters

Name	In	Description
name	body	Full name of the citizen.
dob	body	Date of birth (YYYY-MM-DD).
gender	body	Gender (M/F/O).
mobile	body	Valid 10-digit mobile number.

Example Request

curl -X POST "https://api.guip.gov.earth/api/v1/generate-id" \
  -H "X-API-KEY: YOUR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Rahul Sharma", "dob":"1990-01-01", "gender":"M", "mobile":"9876543210"}'

Successful Response (200 OK)

{
  "status": "success",
  "guip_id": "356789012345"
}

Error Response (4xx)

{
  "error": "Validation failed",
  "details": ["mobile: invalid format"]
}

Need integration support? Contact our developer team at dev@guip.gov.earth