role relay Developer Portal · v1.1.0
GCA Candidate Management Platform · Contract v1.1.0

The GCA CMP API

APIs that power candidate management across Africa and beyond — a stable, versioned contract your team can build against today.

Explore the API → Quick start

Catalog

The platform's APIs. Build against what's live; the rest are on the roadmap.

Live
Candidate API
Intake and records — create a candidate, fetch the safe profile, versioned documents. Powered by the shared contract.
Phase 2
Opportunities API
Open roles from client organisations, faceted search and matching.
Phase 2
Assessments API
Proctored assessment results and work-readiness scoring.
Phase 2
Placements API
Recruiter pipeline stages and placement tracking.

Guides

Everything you need to integrate.

Quick Start
Your first request in one curl.
Authentication
X-API-Key, scoped per org & environment.
Environments
Dev and production base URLs.
Versioning & Compatibility
What /v1 guarantees.
Webhooks
Get candidate-lifecycle events, signed.
API Reference (Scalar)
Interactive docs with try-it & search.
Interactive docs (Swagger)
Classic Swagger UI over the same spec.
Postman
Import the collection and go.
Examples
Copy-paste request & response payloads.
OpenAPI Spec
Generate a client in any language.

Quick start

Every /v1 request carries an X-API-Key. Create a candidate:

# POST a candidate — returns 201 with a stagedId
curl -X POST https://api.dev.gca.rolerelay.com/v1/candidates \
  -H "X-API-Key: <your-key>" \
  -H "Content-Type: application/json" \
  -d @candidate.json

Grab a ready-made body from the examples, or open the reference and use Try it to send a live request (pick your environment in the server dropdown).

Authentication

Send your key in the X-API-Key header on every /v1 request. Missing or invalid keys return 401. Each key is scoped to one organisation and one environment — a dev key cannot reach production data.

Environments

Development
https://api.dev.gca.rolerelay.com
Production
https://api.gca.rolerelay.com

The reference's Try it targets whichever server you select in the dropdown. Ask your team for a key scoped to the environment you need.

Versioning & compatibility

The URL carries the major version (/v1). Within v1, changes are backward-compatible — new optional fields may be added, but existing fields and behaviour will not break. Breaking changes ship only under a new major version (/v2). This portal documents contract v1.1.0.

Webhooks

GCA notifies you as candidates move through the lifecycle — no polling.

1. Register an endpoint and keep the signingSecret it returns (shown once):

# returns 201 with a signingSecret
curl -X POST https://api.dev.gca.rolerelay.com/v1/webhook-endpoints \
  -H "X-API-Key: <your-key>" -H "Content-Type: application/json" \
  -d '{"url":"https://you.example/gca-hooks","eventTypes":["candidate.promoted"]}'

2. Events we send (each a signed POST to your URL):

candidate.received
Accepted into intake.
candidate.verified
Identity verification done.
candidate.promoted
Met exit criteria, searchable.
candidate.validation_failed
Intake rejected (with reasons).
candidate.consent_revoked
Access frozen.
candidate.erased
Data erased (no PII in payload).

3. Verify the signature. Each delivery carries X-RR-Signature: sha256=<hmac> — the HMAC-SHA256 of the raw body using your signingSecret. Recompute and compare before trusting the event. Dedupe on X-RR-Event-Id; return any 2xx to acknowledge.

Full payload schemas are in the reference (Webhooks section). Send yourself a sample with POST /v1/webhook-endpoints/{id}/test.