MyCulture Client API

One assessment contract. Any hiring system.

Discover assessments, invite candidates, reconcile progress, retrieve versioned results, and receive retryable signed events—without adopting another ATS’s data model.

Make your first request Download the specification

Provider-neutral resources
Scoped organization keys
Retryable signed webhooks

Private previewv1

Base URL

https://api.myculture.ai/api/v1

Preview access is enabled per organization. Each key is limited to an organization, environment, and explicit set of permissions.

The integration lifecycle

Completion is a milestone. Result readiness is the contract.

1
Template
Choose an assessment
Read only the active templates belonging to your organization.
2
Invitation
Create a candidate link
Use an idempotency key so retries never produce duplicate invitations.
3
Progress
Track candidate activity
Reconcile invitations or consume assessment.started.
4
Ready
Wait for the stable snapshot
assessment.result_ready fires after every selected module has finished.
5
Result
Retrieve typed results
Read versioned scores, profiles, benchmarks, dimensions, and narrative.

Quickstart

List your assessment templates

Store the key in a backend secret manager. MyCulture keys are never safe to expose in a browser or mobile application.

curl "https://api.myculture.ai/api/v1/assessment-templates?limit=25" \
  --header "Authorization: Bearer $MYCULTURE_API_KEY" \
  --header "Accept: application/json"const response = await fetch(
  "https://api.myculture.ai/api/v1/assessment-templates?limit=25",
  { headers: { Authorization: `Bearer ${process.env.MYCULTURE_API_KEY}` } }
);
const page = await response.json();import os
import requests

response = requests.get(
    "https://api.myculture.ai/api/v1/assessment-templates",
    headers={"Authorization": f"Bearer {os.environ['MYCULTURE_API_KEY']}"},
    params={"limit": 25},
)
response.raise_for_status()
page = response.json()

200application/json

{
  "data": [{
    "id": "tpl_culture_alignment",
    "name": "Culture Alignment",
    "sections": ["values_and_traits", "acceptable_behaviors"],
    "status": "active"
  }],
  "pagination": { "next_page_token": null, "has_more": false }
}

Authentication

Keys carry their own boundaries

Send the key as a Bearer token or in X-API-Key. Both forms resolve to the same scoped credential.

ORG

Organization isolation

A key cannot read templates, invitations, or results belonging to another organization.

ENV

Live and test keys

Keys identify their environment with an mc_live_ or mc_test_ prefix.

SCP

Explicit permissions

Permissions separate template reads, invitation writes, result reads, and webhook management.

Keys are shown once

MyCulture stores a one-way hash, not the raw key. Rotate a key if the original value is lost or exposed.

Endpoint reference

Assessment workflow

The neutral resources below are the client integration contract. Database collection names and Greenhouse fields are deliberately absent.

GET

List assessment templates

/assessment-templates

Returns active templates owned by the authenticated organization. Use the opaque next_page_token to continue through large sets.

ParameterTypeDescription

limitinteger1–100; defaults to 25.

page_tokenstringOpaque token from the preceding response.

POST

Create an invitation

/invitations

Creates a unique assessment and candidate URL. Set send_email to false when your own system will deliver the link.

Idempotency-Key is required

Generate a unique key for the business action and reuse it when retrying. MyCulture returns the original result for 24 hours instead of creating a duplicate.

Request

{
  "assessment_template_id": "tpl_culture_alignment",
  "candidate": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "external_id": "candidate_4821"
  },
  "client_reference": "application_9017",
  "send_email": true
}

201 response

{
  "id": "inv_f4J9…",
  "assessment_id": "asmt_w8N2…",
  "assessment_template_id": "tpl_culture_alignment",
  "status": "invited",
  "assessment_url": "https://app.myculture.ai/assessment-test/…",
  "email_status": "queued",
  "client_reference": "application_9017"
}

POST

Create a batch of invitations

/invitation-batches

Invite up to 100 candidates in one request. Each item succeeds or fails independently, so one invalid candidate does not hide the invitations that were created.

Reconciliation is built in

Store each returned invitation ID together with your client_reference or candidate.external_id. Both fields can be used to list the matching invitation or result later.

GET

Get invitation status

/invitations/{invitationId}

Returns candidate progress separately from result_status. A completed assessment can legitimately report result_status: processing while evaluator modules finish.

GET

Get an assessment result

/assessment-results/{assessmentId}

Returns the immutable integration snapshot only after result_status becomes ready. Every result and section includes a schema version.

Stable fields

FieldTypeDescription

overall_scorescore|nullValue, percent scale, and semantic score kind.

sections[].scorescore|nullModule-level score when one is meaningful.

sections[].dimensionsarrayNamed dimension scores produced by that module.

sections[].narrativestring|nullSupported generated summary, when available.

sections[].dataobjectTyped module details such as a profile, benchmark, or scoring version.

Completed result

{
  "assessment_id": "asmt_w8N2…",
  "status": "ready",
  "schema_version": "2026-08-05",
  "overall_score": { "value": 84, "scale": "percent", "kind": "composite" },
  "sections": [{
    "key": "human_skills",
    "schema_version": "2026-08-05",
    "score": { "value": 81.2, "scale": "percent", "kind": "ability" },
    "dimensions": [{
      "key": "communication",
      "name": "Communication",
      "score": { "value": 88, "scale": "percent", "kind": "ability" }
    }],
    "narrative": "Strong collaboration…"
  }],
  "ready_at": "2026-08-05T09:15:00.000Z"
}

Lifecycle events

Receive, inspect, and replay signed webhooks

Create a public HTTPS endpoint through POST /webhook-endpoints. The signing secret is returned once.

Store the secret

Keep the returned whsec_… value in your server-side secret manager.

Verify before parsing

Compute HMAC-SHA256 over timestamp.raw_body and compare it with X-MyCulture-Signature.

Acknowledge and deduplicate

Return a 2xx response and persist X-MyCulture-Delivery. Failed deliveries retry with backoff.

Completion and readiness are separate

Use assessment.completed to update candidate progress. Wait for assessment.result_ready before beginning downstream decisions. Inspect attempts through GET /webhook-deliveries and replay a delivery when your system recovers.

Result contract

Rich enough to integrate, narrow enough to trust

The API translates module-specific storage into one versioned public structure.

Included when produced

Typed overall and section scores
Dimension and benchmark values
Categorical profiles when applicable
Supported generated narratives
Started, completed, and ready timestamps

Never returned

Raw candidate answers
Internal prompts or scoring configuration
Other organizations’ data
Database collection structures
API or webhook secrets

Errors

Every failure has a request ID

StatusMeaningWhat to do

400Query or page token is invalid.Correct the parameter; do not retry unchanged.

401 / 403Key is invalid or lacks the required permission.Check the key and its scopes.

404Resource is absent from your organization.Verify the identifier and environment.

409Assessment or result processing is incomplete, or an idempotent request conflicts.Check result_status; retry only when the state changes.

422JSON body failed validation.Use the field-level details to correct it.

429 / 500Temporary capacity or service failure.Retry with exponential backoff and jitter.

Error envelope

{
  "error": {
    "code": "validation_error",
    "message": "The request body is invalid.",
    "details": [{ "field": "candidate.email", "message": "Must be a valid email address." }],
    "request_id": "64d6fda4-…"
  }
}

ATS compatibility

Greenhouse remains an adapter

The existing Greenhouse Assessment Partner endpoints remain available for Greenhouse installations. New direct integrations should use the neutral Client API.

No forced migration

The Client API does not rename or remove the Greenhouse endpoints. Both surfaces use MyCulture’s assessment services while keeping their external contracts separate.

Private preview

Bring us your workflow.

We’ll confirm permissions, issue a scoped key, and validate one complete invitation-to-result flow before production access.

Request API access

One assessment contract. Any hiring system.

Completion is a milestone. Result readiness is the contract.

Choose an assessment

Create a candidate link

Track candidate activity

Wait for the stable snapshot

Retrieve typed results

List your assessment templates

Keys carry their own boundaries

Organization isolation

Live and test keys

Explicit permissions

Assessment workflow

Stable fields

Receive, inspect, and replay signed webhooks

Store the secret

Verify before parsing

Acknowledge and deduplicate

Rich enough to integrate, narrow enough to trust

Every failure has a request ID

Greenhouse remains an adapter

Bring us your workflow.