MarioHR ATS API Integration Guide

Setup

Connect your ATS

Your MarioHR account manager provides an API key and configures which assessments are available. Your engineering team implements the endpoints below against your ATS (or an integration layer).

Get your MarioHR API key

Reach out to your MarioHR account manager for the organization API key used in Authorization: Basic on every request.

Implement the partner flow

Call list_tests to show available assessments, send_test when a recruiter sends one, and test_status to poll progress. Provide a callback url on send so MarioHR can PATCH results when scoring completes.

Expose a results webhook

Your ATS (or middleware) must accept an HTTPS PATCH on the URL you pass in send_test. MarioHR sends a JSON body with Greenhouse-compatible status fields plus full report data and a presigned recording URL.

Store outbound credentials

Share credentials with MarioHR for the PATCH callback (configured as your ATS API key in MarioHR admin). MarioHR uses Basic Auth when posting results back to your endpoint.

API

Endpoints

Base URL: https://mariohr.com (or your staging worker URL). All routes require Authorization: Basic <api_key>: (API key as username, empty password).

list List assessments

GET /api/ats/list_tests

[
  {
    "partner_test_id": "py-fastapi-review",
    "partner_test_name": "Python FastAPI Code Review",
    "description": "Repo-based exercise for backend roles."
  }
]

send Send a test

POST /api/ats/send_test

{
  "partner_test_id": "py-fastapi-review",
  "candidate": {
    "email": "candidate@example.com",
    "first_name": "Alex",
    "last_name": "Kim",
    "greenhouse_profile_url": "https://your-ats.example/candidates/123"
  },
  "url": "https://your-ats.example/webhooks/mariohr/abc",
  "sent_by": "recruiter@company.com"
}

Response: { "partner_interview_id": "abc123def456" }

Field names match the Greenhouse Assessment API for drop-in compatibility. The url is your HTTPS callback for result delivery.

timeline Poll status

GET /api/ats/test_status?partner_interview_id=<token>

{
  "partner_status": "complete",
  "partner_profile_url": "https://mariohr.com/api/report/abc123def456",
  "partner_score": 82,
  "metadata": {
    "Started At": "2026-05-21T10:00:00.000Z",
    "Completed At": "2026-05-21T12:30:00.000Z",
    "Final Total": "82/100"
  }
}

sync Results callback (PATCH)

When an assessment is scored (or you trigger submit from MarioHR admin), MarioHR PATCHes the url from send_test with a JSON body that includes:

Greenhouse-compatible partner_status, partner_score, and metadata
recording_url — presigned S3 URL for the session recording (when processed)
report — transcript, scoring breakdown, and safe assessment fields (passwords excluded)

security

Callback URLs must use HTTPS and cannot target localhost or private networks. Authenticate inbound PATCH requests using the credentials you configured with MarioHR.

error Error reporting

POST /api/ats/response_error

Optional endpoint for your ATS to report integration errors; MarioHR logs the payload for seven days.

Customize

Email messages & assessments

You can customize the email message candidates receive and configure which assessments are available. Talk to your MarioHR account manager to set these up for your team.

Need help?

Your MarioHR account manager can help with API keys, assessment catalog, and callback auth. See also Greenhouse and Ashby integrations, or our FAQ.

Contact Support