Stadium Identity API
v0.1.0 OpenAPI JSON
Developer documentation

Stadium Identity API reference

Searches are read-only and synchronous. Every match is a probability, not a confirmed identity.

Base URL https://txedexchange-idrs.getstadium.org

Obtain a JWT access token from this environment's authorization server using the OAuth 2.0 client credentials grant. Send it as Authorization: Bearer <token>. Student search requires both student:identity:read and partner:<partner_id> scopes.

API concepts and usage

The Stadium API helps you find student records that may refer to students in your own data. Submit the details you know about each student, such as their name, birth date, and identifiers. The API searches student records in Stadium and returns possible matches ranked by score.

Searches are read-only and synchronous: results arrive in the same HTTP response.

Choose where to search

A partner identifies whose Stadium data to search. A tenant identifies a district or other subdivision within that partner. Each search covers exactly one tenant; there are no cross-tenant searches.

Authenticate

Obtain an access token from your environment's authorization server using the OAuth 2.0 client credentials grant. Send Authorization: Bearer <token> with each API request. Request a token whose audience is the public URL of this API environment. A token with another audience is not accepted.

Student search requires both student:identity:read and partner:<partner_id>, where the partner ID matches the URL. For example, searching partner acme requires partner:acme. Partner access covers every tenant within that partner. Use GET /token/verify to inspect the permissions carried by your token.

Submit student details

Send a JSON array to POST /partners/{partner}/tenants/{tenant}/students/search with Content-Type: application/json. Each object describes one student and includes a correlation_id you choose, such as input-1. This identifier associates a result with its input and is not used for matching. Supply the student details you know; missing details may be omitted or set to null.

Interpret the results

The response is an array with one result per submitted student, in the same order. Each result repeats your correlation_id and contains a matches array, ordered by descending score. Each score is an estimate, from 0 to 1, of the probability that the returned record and submitted details refer to the same person. Higher scores indicate stronger matches. Returned student details come from Stadium and may differ from the details you submitted.

A possible match is not a confirmed identity. Use the returned details and scores to decide how to handle the result in your application. An empty matches array means the search returned no qualifying match; it does not establish that the student is absent from Stadium.

Student search

Find possible student matches

POST/partners/{partner}/tenants/{tenant}/students/search

Search student records in one partner and tenant using the details you know. This is a read-only, synchronous search: the response contains the completed results.

Permissions and scope

Requires both student:identity:read and partner:<partner_id> for the partner in the URL. Partner access covers all tenants within that partner. Searches never cross tenant boundaries. An unknown tenant returns no matches. The identity scope permits identity searches; the partner scope identifies whose data the token may search.

Send a batch

Send a JSON array of up to 5,000 student inputs. Only correlation_id is required for each input. Choose a nonempty string unique within the batch that your application can use to associate the returned result with the submitted record. All other fields may be omitted or null. Missing or null identifier lists behave as empty lists. Dates must use YYYY-MM-DD. Unknown object fields and duplicate correlation IDs are rejected. A valid input does not guarantee enough information to find useful matches. An empty array returns [].

There are no supported query parameters; any supplied query parameters are ignored.

Read the results

The response is a JSON array with one result per input, in the same order. Each result repeats your correlation_id and lists possible matches by descending score. Student details in matches come from Stadium and may differ from your input. A possible match is not a confirmed identity. An empty matches array means no qualifying match was returned, not proof that the student is absent from Stadium.

The examples use fictional student data and illustrate single, multiple, and empty match results. Example scores do not define an acceptance threshold.

Authentication required

Parameters

partner path · string required

Partner ID identifying whose Stadium data to search. Requires the matching partner:<partner_id> token scope.

minLength: 1
tenant path · string required

Tenant code within this partner, such as a district code. Contains only letters, digits, underscores, and hyphens. An unknown code returns no matches.

pattern: "^[A-Za-z0-9_-]+$"

Request body required

A JSON array of up to 5,000 student inputs.

application/json

A JSON array of up to 5,000 student inputs. Each correlation_id must be unique within the batch. An empty array is valid and returns [].

maxItems: 5000

Array items · object

Details you know about one student. Only correlation_id is required; all other fields may be omitted or null. Providing more identifying details can help distinguish students. A valid input does not guarantee a useful match. Unknown fields are rejected.

Unknown fields rejected
correlation_id string required

A caller-defined key for this input. Use a value your application can map back to the submitted record, such as its own record identifier. The corresponding result repeats it unchanged. Must be a nonempty string unique within this batch. It does not affect which Stadium records are returned or how they are scored.

minLength: 1
first_name string | null optional

The student's given name.

last_name string | null optional

The student's family name.

birth_date string | null optional

The student's birth date, in YYYY-MM-DD format.

format: "date"
school_ids array<integer> | null optional

Ed-Fi school identifiers associated with the student. Used as matching information; they do not restrict results to those schools. Omitted, null, and empty lists are equivalent.

Child fields

Array items · integer

student_ids array<string> | null optional

Student identification codes you know, such as a state or district student ID. Send the values as strings without identification-system labels. Omitted, null, and empty lists are equivalent.

Child fields

Array items · string

Responses

200 Success

One result per submitted student, in input order, with zero or more possible matches ordered by descending score. An empty input array returns an empty response array.

application/json

Single, multiple, and empty match results
[
  {
    "correlation_id": "input-1",
    "matches": [
      {
        "score": 0.97,
        "student_unique_id": "student-1042",
        "first_name": "Noor",
        "middle_name": null,
        "last_name": "Yang",
        "birth_date": "2008-09-03",
        "student_ids": [
          {
            "id_type": "State",
            "id_value": "SC800227"
          }
        ],
        "school_years": [
          2024,
          2025
        ]
      }
    ]
  },
  {
    "correlation_id": "input-2",
    "matches": [
      {
        "score": 0.86,
        "student_unique_id": "student-2081",
        "first_name": "Alex",
        "middle_name": "Lee",
        "last_name": "Rivera",
        "birth_date": "2009-02-14",
        "student_ids": [
          {
            "id_type": null,
            "id_value": "SC801032"
          }
        ],
        "school_years": [
          2025
        ]
      },
      {
        "score": 0.62,
        "student_unique_id": "student-3150",
        "first_name": "Alexandra",
        "middle_name": null,
        "last_name": "Rivera",
        "birth_date": "2009-02-14",
        "student_ids": [],
        "school_years": [
          2024,
          2025
        ]
      }
    ]
  },
  {
    "correlation_id": "input-3",
    "matches": []
  }
]
Response fields

One result per submitted student, in input order. Each result contains zero or more possible matches.

Array items · object

Search results for one submitted student. Empty matches means no qualifying match was returned; it does not establish that the student is absent from Stadium.

correlation_id string required

The correlation_id from the corresponding input, returned unchanged.

matches array<object> required

Possible matches, highest score first. May be empty.

Child fields

Array items · object

A stored student record that may refer to the student you submitted. Student details come from Stadium and may differ from your input. Nullable fields are always present; null indicates an unavailable value.

score number required

The matching model's estimated probability that this record and the submitted details refer to the same person, from 0 to 1. Higher scores indicate stronger matches. A score is not a confirmation of identity or a prescribed threshold for accepting a match.

minimum: 0maximum: 1
student_unique_id string required

The student_unique_id stored in Stadium for this student. Keep the partner and tenant context with this identifier when using the result.

first_name string | null required

The student's given name from Stadium, or null when unavailable.

middle_name string | null required

The student's middle name from Stadium, or null when unavailable.

last_name string | null required

The student's family name from Stadium, or null when unavailable.

birth_date string | null required

Birth date from Stadium in YYYY-MM-DD format, or null when unavailable.

format: "date"
student_ids array<object> required

Student identification codes from Stadium. May be empty.

Child fields

Array items · object

A student identification code returned from Stadium, with its system when available. Request student_ids contain only string values; response student_ids contain these objects.

id_type string | null required

The Ed-Fi StudentIdentificationSystem label, when available in Stadium. Null means the identification system is unavailable.

id_value string required

The student identification code from Stadium.

school_years array<integer> required

Every school year associated with this student in Stadium. School year is not a search input; use this field to filter possible matches after the search.

Child fields

Array items · integer

400 Response details

Invalid request. Correct the fields named in the JSON details array, including invalid dates, unknown fields, duplicate correlation IDs, or a batch exceeding 5,000 inputs. Malformed JSON and malformed Authorization headers produce plain-text responses instead. Authentication is checked before input validation.

WWW-Authenticate

Present when the Authorization header is malformed. Other validation failures omit this header.

application/json

Example
{
  "error": "invalid_request",
  "details": [
    {
      "path": "0.birth_date",
      "message": "Invalid ISO date"
    }
  ]
}
Response fields

A JSON error response. error is a short code you can branch on — invalid_request, insufficient_scope, unsupported_media_type, partner_not_found, search_error — and message or details provide context when available. Other failures, including malformed authentication headers, may be plain text.

error string required

A short machine-readable code. Use this value for branching; use message and details for human-readable diagnostics.

message string optional

A human-readable explanation of the error, when available.

details array<object> optional

Present on validation failures. Each entry identifies one invalid value.

Child fields

Array items · object

path string required

Location of the invalid value. Object properties use their names; array entries use zero-based indexes, such as 0.birth_date. An empty path indicates an error at the top level of the submitted body or parameters.

message string required

Why the value at path is invalid.

text/plain

Malformed Authorization header
Bad Request
Malformed JSON body
Malformed JSON in request body
401 Response details

The access token is missing or unacceptable. Send a valid access token for this API in the Authorization header.

WWW-Authenticate

Bearer challenge. Missing credentials return Bearer realm="stadium-api"; an unacceptable token returns Bearer error="invalid_token".

text/plain

Example
Unauthorized
403 Response details

The token lacks a required permission. Obtain a token with both required scopes. The identity scope permits student matching; the partner scope selects whose data the token may search. The WWW-Authenticate header names the missing scope when available.

WWW-Authenticate

Bearer challenge. Carries error unless no credentials were sent, and the scope needed when one would have satisfied the request.

application/json

Example
{
  "error": "insufficient_scope"
}
Response fields

A JSON error response. error is a short code you can branch on — invalid_request, insufficient_scope, unsupported_media_type, partner_not_found, search_error — and message or details provide context when available. Other failures, including malformed authentication headers, may be plain text.

error string required

A short machine-readable code. Use this value for branching; use message and details for human-readable diagnostics.

message string optional

A human-readable explanation of the error, when available.

details array<object> optional

Present on validation failures. Each entry identifies one invalid value.

Child fields

Array items · object

path string required

Location of the invalid value. Object properties use their names; array entries use zero-based indexes, such as 0.birth_date. An empty path indicates an error at the top level of the submitted body or parameters.

message string required

Why the value at path is invalid.

404 Response details

For a request authorized to search this partner, the partner is not provisioned for search. Check the partner ID or contact the service operator. An unknown tenant instead returns 200 with empty matches. An empty input batch returns 200 without checking partner provisioning.

application/json

Example
{
  "error": "partner_not_found",
  "message": "This partner is not provisioned for search."
}
Response fields

A JSON error response. error is a short code you can branch on — invalid_request, insufficient_scope, unsupported_media_type, partner_not_found, search_error — and message or details provide context when available. Other failures, including malformed authentication headers, may be plain text.

error string required

A short machine-readable code. Use this value for branching; use message and details for human-readable diagnostics.

message string optional

A human-readable explanation of the error, when available.

details array<object> optional

Present on validation failures. Each entry identifies one invalid value.

Child fields

Array items · object

path string required

Location of the invalid value. Object properties use their names; array entries use zero-based indexes, such as 0.birth_date. An empty path indicates an error at the top level of the submitted body or parameters.

message string required

Why the value at path is invalid.

415 Response details

Missing or unsupported Content-Type. Send Content-Type: application/json with a JSON array body. This check happens before the body is read, so this response does not indicate whether the body would otherwise be valid.

application/json

Example
{
  "error": "unsupported_media_type",
  "message": "This endpoint accepts application/json; received no Content-Type header."
}
Response fields

A JSON error response. error is a short code you can branch on — invalid_request, insufficient_scope, unsupported_media_type, partner_not_found, search_error — and message or details provide context when available. Other failures, including malformed authentication headers, may be plain text.

error string required

A short machine-readable code. Use this value for branching; use message and details for human-readable diagnostics.

message string optional

A human-readable explanation of the error, when available.

details array<object> optional

Present on validation failures. Each entry identifies one invalid value.

Child fields

Array items · object

path string required

Location of the invalid value. Object properties use their names; array entries use zero-based indexes, such as 0.birth_date. An empty path indicates an error at the top level of the submitted body or parameters.

message string required

Why the value at path is invalid.

500 Response details

The service could not complete the request. Depending on where the failure occurs, the response may be JSON or plain text. This status does not indicate whether retrying will succeed. A search is read-only, so you may retry the whole batch. Report persistent failures to the service operator.

application/json

Example
{
  "error": "search_error",
  "message": "The service could not complete this search."
}
Response fields

A JSON error response. error is a short code you can branch on — invalid_request, insufficient_scope, unsupported_media_type, partner_not_found, search_error — and message or details provide context when available. Other failures, including malformed authentication headers, may be plain text.

error string required

A short machine-readable code. Use this value for branching; use message and details for human-readable diagnostics.

message string optional

A human-readable explanation of the error, when available.

details array<object> optional

Present on validation failures. Each entry identifies one invalid value.

Child fields

Array items · object

path string required

Location of the invalid value. Object properties use their names; array entries use zero-based indexes, such as 0.birth_date. An empty path indicates an error at the top level of the submitted body or parameters.

message string required

Why the value at path is invalid.

text/plain

Example
Internal Server Error
Authentication

Inspect the access token on this request

GET/token/verify

Use this endpoint to troubleshoot an access token. It returns the client ID, scopes, partner access, and expiration that this API read from the token. Any valid token may call it; this endpoint requires no particular scope. Send the token in the Authorization: Bearer <token> header.

Authentication required

Responses

200 Success

The token was accepted. The scopes and partners arrays are sorted alphabetically.

application/json

Example
{
  "client_id": "abc123",
  "scopes": [
    "partner:acme",
    "student:identity:read"
  ],
  "partners": [
    "acme"
  ],
  "expires_at": 1755400000
}
Response fields

Information about the accepted access token on this request.

client_id string required

The client identifier from the accepted access token.

scopes array<string> required

Every scope this token carries, including partner scopes. Sorted alphabetically.

Child fields

Array items · string

partners array<string> required

Partner IDs this token may access, derived from its partner:<partner_id> scopes. Sorted alphabetically and without the partner: prefix. An operation may also require its own scope.

Child fields

Array items · string

expires_at integer required

The token expiration time as Unix time in seconds.

400 Response details

The Authorization header was present but malformed. Send Authorization: Bearer <token>. The response is plain text, with WWW-Authenticate: Bearer error="invalid_request".

WWW-Authenticate

Bearer authentication challenge describing the malformed header.

text/plain

Example
Bad Request
401 Response details

Authentication failed. Send a valid access token for this API. The response is plain text. With no Authorization header, the challenge is Bearer realm="stadium-api". With an invalid or expired token, the challenge is Bearer error="invalid_token".

WWW-Authenticate

Bearer authentication challenge explaining the authentication failure.

text/plain

Example
Unauthorized
500 Response details

The service could not complete token verification. The response is plain text. This does not mean the token is invalid, and the status does not indicate whether retrying will succeed. Report persistent failures to the service operator.

text/plain

Example
Internal Server Error