Stadium Identity API reference
Searches are read-only and synchronous. Every match is a probability, not a confirmed identity.
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.
Find possible student matches
/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.
Parameters
partner
path · string
required
Partner ID identifying whose Stadium data to search. Requires the matching partner:<partner_id> token scope.
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 [].
5000Array 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.
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.
1first_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.
"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
[
{
"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.
0maximum: 1student_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.
"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
{
"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
Bad Request
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
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
{
"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
{
"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
{
"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
{
"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
Internal Server Error
Inspect the access token on this request
/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.
Responses
200 Success
The token was accepted. The scopes and partners arrays are sorted alphabetically.
application/json
{
"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
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
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
Internal Server Error