API Reference

The Meritra API provides programmatic access to our professional trust ecosystem. It allows human resource systems, job boards, and marketplace platforms to verify candidate standings, retrieve trust scores, and embed real-time professional badges.

API Base URL:
https://meritra.net/api/v1

Authentication

Meritra authenticate API requests using a custom API Key header. You can manage your API keys in the Developer Console.

To authenticate, include the X-API-KEY header in all requests.

Header Example 
X-API-KEY: mr_0192jks09823k8s90jnd9
Keep your keys safe! Keys are shown only once. If you lose a key, you must revoke it and generate a new one. Never share your secret keys in client-side code (JavaScript).

Request Signing (HMAC)

For enhanced security and request integrity, Meritra supports HMAC-SHA256 signing. This prevents request tampering and replay attacks. Highly recommended for automated systems.

How to Sign Requests

1. Generate a X-API-TIMESTAMP (current Unix timestamp).
2. Concatenate: timestamp + method + path + body.
3. Sign the string using HMAC-SHA256 with your Secret Key.
4. Send the signature in the X-API-SIGNATURE header.

PHP Implementation
$timestamp = time();
$method = 'POST';
$path = 'api/v1/ratings';
$body = json_encode(['employee_id' => '...']); // Content of request

$signature = hash_hmac('sha256', $timestamp . $method . $path . $body, $secret_key);

Usage & Pricing

Meritra API uses a pay-per-request model. Each API key maintains a separate balance in USD. New keys are provisioned with $1.00 USD free credit.

Service Endpoint Cost (USD)
Basic Verification/verify$0.05
Detailed Profile/profiles$0.10
Trust Metrics/metrics$0.10
Submit Rating/ratings$0.25
Certifications/certifications$0.10
Dispute Reporting/disputes$0.25

Verified Certifications

Access the verified educational and professional certifications of a member.

GET /certifications/{meritra_id}

Response Fields

  • issuing_organization: The entity that issued the record.
  • credential_id: Unique organization record ID.
  • verification_url: Source verification link.

Submit Rating

Programmatically submit verified professional ratings from your platform directly into the Meritra global score.

POST /ratings

JSON Body

{
  "meritra_id": "MR-88291",
  "comment": "Excellent execution...",
  "dimension_scores": {
    "Professionalism": 10,
    "Quality of Service": 9
  }
}

Verify Professional

This resource allows you to check the current standing of any professional registered on Meritra using their unique Meritra ID.

GET /verify/{meritra_id}

Parameters

Name Description
meritra_id
string Required 		The unique professional identifier (e.g., MR-123456)

Response Example

{
  "success": true,
  "data": {
    "name": "Jane Smith",
    "meritra_id": "MR-88291",
    "trust_score": 92.5,
    "standing": "VERIFIED",
    "verification_badges": ["KYC", "EXPERIENCE"],
    "verified_at": "2024-02-15T10:00:00Z"
  }
}

Detailed Profiles

Retrieve the complete professional dossier, including sector-specific ratings, work history summary, and education verification status.

GET /profiles/{meritra_id}

Query Parameters

Name Type Description
full boolean Include full work history and educational records. Default: false 
{
  "success": true,
  "data": {
    "bio": "Senior Software Engineer...",
    "overall_score": 88,
    "sector": "Information Technology",
    "records": {
        "education": "Verified",
        "identity": "Verified"
    }
  }
}

Visual Score Badges

Embeddable, high-performance SVG badges that automatically reflect the current trust score of any professional. No API key required for public badges.

SVG /widget/badge/{meritra_id}

Usage

Simply use the URL as an image source in your HTML or Markdown.

<img src="https://meritra.net/api/v1/widget/badge/MR-88291" />

Preview

Sample Badge
Live dynamic preview

Error Handling

Meritra uses standard HTTP status codes to indicate the success or failure of an API request.

Code Title Description
200 OK The request was successful.
401 Unauthorized Invalid or missing X-API-KEY header.
404 Not Found The requested Meritra ID does not exist.
429 Too Many Requests Rate limit exceeded.