# Quickstart — use cases by outcome

Real, end-to-end sequences you can copy and adapt, indexed by outcome rather than by
endpoint. Start with a flagship; the same calls power use cases across the whole employee
lifecycle. Every step's `operationId` is a real operation in the committed OpenAPI
artifact — see [/api-reference.md](/api-reference.md) and the generated operation docs
under `/docs/api/operations/`.

## Start

- **Get your API key** — sign in to create a key, then send it as your bearer token. Key
  issuance lives in the signed-in portal; the public docs never issue one.
- **Import your people & trigger assessments** — bring your directory into Thomas and
  trigger everyone's first assessment. Operations: `bulkValidateColleagues` (dry run) →
  `bulkCreateColleagues` → `bulkCreateAssessmentAssignments`, then track with
  `getAssessmentAssignment` / `listAssessmentAssignments`. About 100 batched calls for
  10,000 people.

## People & profiles

- **Assess a person** (flagship) — trigger a Thomas assessment for one person, then read
  their behaviour profile. Operations: `resolveIdentity` → `createAssessmentAssignment` →
  `getAssessmentAssignment` → `getAssessmentBehaviourProfile`.
- **Enrich a performance review** (flagship) — pull a person's profile into your review
  screen. Operations: `resolveIdentity` → `getAssessmentBehaviourProfile`.

## Teams & connection

- **Measure a team's dynamic** — group resolved people into a team and read its dynamic.
  Operations: `resolveIdentity` → `createConnectionTeam` → `getConnectionTeamDynamics`.
- **Track team connection over time** — read a team's connection score and its trend.
  Operations: `createConnectionTeam` → `getConnectionTeamResults` →
  `configureConnectionRecurrence` (optional).
- **Coach in context** — ask Thomas for grounded coaching, in the flow of work; the
  reply streams back as Server-Sent Events. Operations: `createCoachingConversation` →
  `sendCoachingMessage`.

## Lifecycle

- **Onboard a new joiner** (flagship) — weave Thomas across the systems a new joiner
  touches (your HRIS, LMS and calendar) alongside Thomas calls, personalised to how they
  work.

## Reacting to completion

The person completes the assessment themselves, in Thomas — the API cannot start, complete,
or score it on their behalf. An assignment reaches `COMPLETED`, and a scored behaviour profile
becomes available, only after they have finished; `getAssessmentBehaviourProfile` returns 404
("No scored assessment found for this individual") until a scored result exists.

An `assessment.completed` webhook is coming soon. Until it ships, poll the assignment with
`getAssessmentAssignment` until its `status` is `COMPLETED`.

## Where next

- [API reference](/api-reference.md)
- [Concepts](/concepts.md)
- [Overview](/overview.md)