Skip to main content

API Overview

The GoValid REST API provides programmatic access to QR code generation, verification, and management features.

Base URL​

https://api.govalid.org/api/v1/

Alternative endpoints:

  • https://my.govalid.org/api/v1/
  • https://govalid.org/api/v1/

API Version​

Current version: v1.1.0

Features​

  • RESTful JSON API
  • JWT and API Key authentication
  • Rate limiting with clear headers
  • Comprehensive error handling
  • OpenAPI 3.0 specification

API Categories​

CategoryDescriptionDocumentation
AuthenticationRegister, login, tokens, 2FAAuthentication
AccountProfile, settings, securityAccount Endpoints
QR CodesCreate, manage, scan, verifyQR Endpoints
FinancialSubscriptions, invoices, creditsFinancial Endpoints
InstitutionOrganization managementInstitution Endpoints
C-TraceSupply chain traceabilityC-Trace Endpoints
Anti-CounterfeitProduct authenticationAnti-Counterfeit Endpoints
CommunityNexCommunity featuresCommunity Endpoints
WebhooksEvent-driven integrationsWebhooks

Interactive Documentation​

Explore the API interactively:

Rate Limits​

PlanRequests
Free100/hour
Pro1,000/hour
Enterprise10,000/hour

Rate limit headers are included in all responses:

  • X-RateLimit-Limit - Maximum requests allowed
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - Time until limit resets

Response Format​

All responses are JSON:

{
  "success": true,
  "data": { ... }
}

Error responses:

{
  "error": "error_code",
  "message": "Human readable message",
  "details": { ... }
}

Endpoint Groups​

Authentication Endpoints​

MethodEndpointDescription
POST/api/v1/auth/register/Register new account
POST/api/v1/auth/login/Login and get tokens
POST/api/v1/auth/logout/Logout and revoke tokens
POST/api/v1/auth/token/refresh/Refresh access token
POST/api/v1/auth/password/reset/Request password reset
POST/api/v1/auth/email/verify/Verify email address
POST/api/v1/auth/2fa/enable/Enable two-factor auth
POST/api/v1/auth/2fa/verify/Verify 2FA code
POST/api/v1/auth/2fa/disable/Disable two-factor auth

Account Endpoints​

MethodEndpointDescription
GET/api/v1/account/profile/Get profile
PATCH/api/v1/account/profile/Update profile
GET/api/v1/account/preferences/Get preferences
PATCH/api/v1/account/preferences/Update preferences
POST/api/v1/account/change-password/Change password
GET/api/v1/account/security/Get security settings
GET/api/v1/account/sessions/List active sessions
DELETE/api/v1/account/sessions/{id}/Revoke session
POST/api/v1/account/data-export/Request data export
POST/api/v1/account/delete/Request account deletion

QR Endpoints​

MethodEndpointDescription
GET/api/v1/qr/List QR codes
POST/api/v1/qr/Create QR code
GET/api/v1/qr/{id}/Get QR code details
PATCH/api/v1/qr/{id}/Update QR code
DELETE/api/v1/qr/{id}/Delete QR code
GET/api/v1/qr/{id}/scans/Get scan history
GET/api/v1/qr/{id}/analytics/Get analytics
POST/api/v1/qr/bulk/Bulk create QR codes

Financial Endpoints​

MethodEndpointDescription
GET/api/v1/financial/plans/List available plans
GET/api/v1/financial/subscription/Get subscription status
POST/api/v1/financial/subscribe/Subscribe to plan
GET/api/v1/financial/invoices/List invoices
POST/api/v1/financial/topup/Top up credits
GET/api/v1/financial/transactions/List transactions
GET/api/v1/financial/pricing/Get pricing info

Institution Endpoints​

MethodEndpointDescription
GET/api/v1/institution/settings/Get institution settings
GET/api/v1/institution/departments/List departments
POST/api/v1/institution/departments/Create department
GET/api/v1/institution/roles/List roles
POST/api/v1/institution/roles/Create role

C-Trace Endpoints​

MethodEndpointDescription
POST/api/v1/ctrace/verify/Verify C-Trace QR
GET/api/v1/ctrace/templates/List templates
POST/api/v1/ctrace/batches/Create batch
POST/api/v1/ctrace/step-checkin/Log step check-in

Anti-Counterfeit Endpoints​

MethodEndpointDescription
GET/api/v1/anti-counterfeit/profiles/List profiles
POST/api/v1/anti-counterfeit/assignments/Assign QR to product
GET/api/v1/anti-counterfeit/violations/List violations
GET/api/v1/anti-counterfeit/reports/Generate reports
POST/api/v1/anti-counterfeit/detect/Detection check

Community Endpoints​

MethodEndpointDescription
GET/api/v1/community/feed/Get community feed
POST/api/v1/community/vote/Cast trust vote
POST/api/v1/community/comments/Add comment
GET/api/v1/community/friends/List friends
GET/api/v1/community/badges/List badges

Next Steps​