Bring invitations and shared reports into your workflow.

Quickstart

Create an invitation from your service.

Keep the token in a secret store or environment variable. Never put it in browser code, source control, analytics, or request logs. Replace the placeholders with values from your company account.

curl --request POST "$STEEPSTEP_API_BASE/organizations/$STEEPSTEP_ORGANIZATION_ID/invitations" \
  --header "Authorization: Bearer $STEEPSTEP_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $INVITATION_REQUEST_UUID" \
  --data '{
    "email": "person@example.invalid",
    "name": "Example person",
    "purpose": "personal-feedback",
    "expires_in_days": 14,
    "send_email": true
  }'

Omit send_email or set it to false when your system will deliver the returned link. The default remains caller-managed. When set to true, SteepStep emails the invited address through its configured mail provider. The private bearer URL remains in the response, so do not print or log it. accepted_by_provider confirms provider acceptance only, not delivery to an inbox. An outcome_unknown status needs operator review before any retry.

The URL is a bearer credential in the request path. Use HTTPS and redact this path from application, proxy, analytics, and support logs.

Production availability: invitation creation is currently disabled in production. An eligible assessment version and the separate production and purpose checks must all pass; publishing a version alone does not enable the endpoint. Until then, production requests are rejected and no credit is reserved.

Check progress and read a shared report

Keep the invitation ID from the create response. Poll its detail to see the original invited email, reference, and whether the assessment is in progress or complete. Once the person grants your company access to the report bound to that invitation, the same detail response includes the report ID, the sections shared for that invitation’s purpose, and direct JSON/PDF links. Use those URLs as returned. Before an active matching grant, the report fields are empty. After that grant ends, they become empty again. No matching by name, email, or external reference is needed.

# Invitation detail includes the original invite. A report link appears only
# while this invitation has an active report grant for this organization.
curl --silent --show-error "$STEEPSTEP_API_BASE/organizations/$STEEPSTEP_ORGANIZATION_ID/invitations/$INVITATION_ID" \
  --header "Authorization: Bearer $STEEPSTEP_API_TOKEN"

# Reports currently shared with this company
curl --silent --show-error "$STEEPSTEP_API_BASE/organizations/$STEEPSTEP_ORGANIZATION_ID/reports?limit=50" \
  --header "Authorization: Bearer $STEEPSTEP_API_TOKEN"

# Copy report_url from invitation detail when it is non-null. Keep its purpose query.
curl --silent --show-error "$STEEPSTEP_REPORT_URL" \
  --header "Authorization: Bearer $STEEPSTEP_API_TOKEN"

# If the role closes before the person starts, release the reserved credit
curl --request DELETE "$STEEPSTEP_API_BASE/organizations/$STEEPSTEP_ORGANIZATION_ID/invitations/$INVITATION_ID" \
  --header "Authorization: Bearer $STEEPSTEP_API_TOKEN"

Invitation detail includes the original invited email and must stay in a restricted service. Its report fields identify only a report bound to that invitation with an active grant for this organization and the same recorded purpose. Keep the purpose query on its returned URLs: report and PDF endpoints return only that purpose’s sections, or 404 when that grant ends. A report shared for another purpose is not a fallback. The invitation detail no longer includes report links after access ends.