Skip to main content

Assessments

An assessment is a single MNTEST administration for a subject. It tracks item responses and transitions through a lifecycle as responses accumulate.

Lifecycle​

created → in_progress → scoring → completed
              ↓
           abandoned (if explicitly abandoned)
           expired   (if not completed within 7 days)

Start an assessment​

POST /v1/nature/subjects/{subject_id}/assessments

const assessment = await client.nature.assessments.start(subject.id, {
  language: 'en',             // 'en' or 'fr'
  item_set_version: undefined, // optional: pin to a specific item bank version
});
// assessment.responses_required = 76
// assessment.status = 'created'

Submit responses​

PATCH /v1/nature/subjects/{subject_id}/assessments/{assessment_id}

Responses can be submitted incrementally across multiple PATCH calls. The assessment transitions to scoring automatically when all 76 required responses are received.

// Partial submission (first batch)
await client.nature.assessments.submitResponses(subject.id, assessment.id, {
  responses: [
    { item_id: 'mn_001', value: 4 },
    { item_id: 'mn_002', value: 2 },
    // ...
  ],
});

// Final batch — triggers scoring when total reaches 76
await client.nature.assessments.submitResponses(subject.id, assessment.id, {
  responses: remainingResponses,
});

Response values are 1–5 (Likert scale). Item IDs correspond to the MNTEST item bank. The item bank itself is not returned via the API — your integration receives the bank from Xavigate separately as part of the partner onboarding.

Supports Idempotency-Key — safe to retry partial submissions.

Check assessment status​

GET /v1/nature/subjects/{subject_id}/assessments/{assessment_id}

const assessment = await client.nature.assessments.get(subject.id, assessmentId);
console.log(assessment.status);            // 'in_progress', 'scoring', 'completed'
console.log(assessment.responses_received); // 52 of 76
console.log(assessment.profile_id);         // null until status === 'completed'

Wait for completion​

Use webhooks (recommended) or poll:

// In your webhook handler:
app.post('/webhooks/xavigate', async (req, res) => {
  const event = verifyWebhook(await req.text(), req.headers, secret);
  if (event.type === 'nature.assessment.completed') {
    const { subject_id, profile_id } = event.data;
    const profile = await client.nature.profiles.get(subject_id);
    // process profile...
  }
  res.sendStatus(200);
});
// Poll until completed (for simple integrations; webhooks preferred in production)
async function waitForProfile(subjectId: string, assessmentId: string) {
  for (let i = 0; i < 30; i++) {
    const asm = await client.nature.assessments.get(subjectId, assessmentId);
    if (asm.status === 'completed') {
      return client.nature.profiles.get(subjectId);
    }
    await new Promise(r => setTimeout(r, 2000)); // poll every 2s
  }
  throw new Error('Timed out waiting for assessment completion');
}

Notes​

  • Assessments expire after 7 days if not completed
  • A subject can have multiple assessments; only the most recent completed profile is returned by the profile endpoint
  • Re-assessing a subject (starting a new assessment) is allowed and produces a new profile