Quickstart

This walkthrough covers the complete server-to-server flow: choose a test, send it to a candidate, then retrieve the result.

Before you begin

You need a bearer token. In the B2B dashboard, go to Integration Settings and select Create API Token.

Keep tokens private

Make API requests from your server. Never expose a bearer token in client-side application code.

1. List available tests

curl 'https://app.smalltalk2.me/api/integration/list_tests' \
  -H 'Authorization: Bearer <token>'

Choose the id of the assessment you want to send:

[
  {
    "id": "1b23q",
    "name": "Speaking test"
  },
  {
    "id": "42a621",
    "name": "Writing test"
  }
]

2. Send the test

curl -X POST 'https://app.smalltalk2.me/api/integration/send_test' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "test_id": "1b23q",
    "first_name": "Harry",
    "last_name": "Potter",
    "email": "hpotter@hogwarts.edu",
    "profile_url": "https://example.com/people/17681532",
    "callback_url": "https://example.com/assessment-status"
  }'

The response always includes both interview_id and test_link. Save the returned interview_id; it identifies this candidate's assessment.

{
  "interview_id": "o2jn3r",
  "test_link": "https://app.smalltalk2.me/assessment/?id=o2jn3r"
}

When no_send_email is true, your integration is responsible for delivering test_link to the candidate.

3. Retrieve the status

curl 'https://app.smalltalk2.me/api/integration/test_status?id=o2jn3r' \
  -H 'Authorization: Bearer <token>'

If you need richer report data, request one or more additional fields:

curl 'https://app.smalltalk2.me/api/integration/test_status?id=o2jn3r&additional_fields=detailed_scores,strength_weaknesses' \
  -H 'Authorization: Bearer <token>'

Next steps

• Review the complete send_test request.
• Configure status callbacks.
• Handle every documented assessment status.