API Documentation

Provider API Reference

Submit certifications for your graduates programmatically. This page covers authentication, the bulk submission endpoint, request and response schemas, and rate limits.

Authentication

All provider API requests must include your API key in theX-API-Keyheader. API keys are issued when you register as a provider. Contact [email protected] to request one.

X-API-Key: your-api-key-here

API keys are non-transferable. Do not embed them in client-side code. Keep them in server-side environment variables.

Base URL

https://getmeritus.org/api/v1

Bulk Submit Certifications

POST/api/v1/provider/bulk-submit

Submit up to 100 certification entries per request. Each entry creates (or appends to) a Meritus profile for the named student. Entries are attested under your provider account's binding declaration.

Request Body

{
  "entries": [
    {
      "worker_email": "[email protected]",
      "trade_noc_code": "7271",
      "level": "Journeyperson",
      "certificate_hash": "a1b2c3d4e5f6...64-char-hex-sha256",
      "issued_at": "2026-03-01",
      "expires_at": "2029-03-01"
    }
  ]
}

Field	Type	Required	Description
worker_email	string	Yes	Email of the registered worker. Must already have a Meritus account.
trade_noc_code	string	Yes	NOC/O*NET-SOC trade code (e.g., "7271" for carpenter). Max 10 characters.
level	string	Yes	Certification level (e.g., "Journeyperson", "Apprentice Level 3"). Max 50 characters.
certificate_hash	string	Yes	SHA-256 hash of the certificate document (64 hex characters).
issued_at	string	Yes	ISO 8601 date (YYYY-MM-DD) when the credential was issued.
expires_at	string	No	ISO 8601 date (YYYY-MM-DD) when the credential expires. Omit for non-expiring credentials.

Success Response (200)

{
  "success": true,
  "data": {
    "total": 1,
    "created": 1,
    "skipped": 0,
    "errors": 0,
    "results": [
      {
        "email": "[email protected]",
        "status": "created",
        "serial_number": "MER-7271-2026-A1B2C3D4"
      }
    ]
  }
}

Error Response (422)

{
  "success": false,
  "error": "Validation failed",
  "details": [
    {
      "type": "field",
      "msg": "Invalid value",
      "path": "entries[0].worker_email",
      "location": "body"
    }
  ]
}

If validation fails, the request is rejected with details about which fields need correction. Fix the errors and resubmit.

Rate Limits

Plan	Entries per batch	Monthly limit	Rate limit
Starter (Free)	100	10 entries	10 requests/minute
Growth ($49/mo)	100	500 entries	30 requests/minute
Pro ($99/mo)	100	Unlimited	60 requests/minute

Rate limit headers are included in every response:X-RateLimit-RemainingandX-RateLimit-Reset.

Example: cURL

curl -X POST https://getmeritus.org/api/v1/provider/bulk-submit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "entries": [
      {
        "worker_email": "[email protected]",
        "trade_noc_code": "7271",
        "level": "Journeyperson",
        "certificate_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "issued_at": "2026-03-01",
        "expires_at": "2029-03-01"
      },
      {
        "worker_email": "[email protected]",
        "trade_noc_code": "7271",
        "level": "Apprentice Level 4",
        "certificate_hash": "d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592",
        "issued_at": "2026-03-01"
      }
    ]
  }'

HTTP Status Codes

Code	Description
200	Batch submitted successfully. All entries attested.
400	Malformed request body. Check JSON syntax.
401	Missing or invalid X-API-Key header.
403	API key is valid but account is suspended.
413	Batch exceeds 100 entries. Split into multiple requests.
422	Validation error. One or more entries have invalid fields.
429	Rate limit exceeded. Wait and retry.
500	Internal server error. Contact support if persistent.

Need an API Key?

Request API Key Back to Provider Overview