{"openapi":"3.1.0","info":{"title":"Stadium Identity API","version":"0.1.0","description":"The Stadium API helps you find student records that may refer to students in\nyour own data. Submit the details you know about each student, such as their\nname, birth date, and identifiers. The API searches student records in Stadium\nand returns possible matches ranked by score.\n\nSearches are read-only and synchronous: results arrive in the same HTTP response.\n\n### Choose where to search\n\nA **partner** identifies whose Stadium data to search. A **tenant** identifies\na district or other subdivision within that partner. Each search covers exactly\none tenant; there are no cross-tenant searches.\n\n### Authenticate\n\nObtain an access token from your environment's authorization server using the\nOAuth 2.0 client credentials grant. Send `Authorization: Bearer <token>` with\neach API request. Request a token whose audience is the public URL of this API\nenvironment. A token with another audience is not accepted.\n\nStudent search requires both `student:identity:read` and\n`partner:<partner_id>`, where the partner ID matches the URL. For example,\nsearching partner `acme` requires `partner:acme`. Partner access\ncovers every tenant within that partner. Use `GET /token/verify` to inspect the\npermissions carried by your token.\n\n### Submit student details\n\nSend a JSON array to `POST /partners/{partner}/tenants/{tenant}/students/search`\nwith `Content-Type: application/json`. Each object describes one student and\nincludes a `correlation_id` you choose, such as `input-1`. This identifier\nassociates a result with its input and is not used for matching. Supply the\nstudent details you know; missing details may be omitted or set to null.\n\n### Interpret the results\n\nThe response is an array with one result per submitted student, in the same\norder. Each result repeats your `correlation_id` and contains a `matches`\narray, ordered by descending score. Each `score` is an estimate, from 0 to 1,\nof the probability that the returned record and submitted details refer to the same\nperson. Higher scores indicate stronger matches. Returned student details come\nfrom Stadium and may differ from the details you submitted.\n\nA possible match is not a confirmed identity. Use the returned details and scores\nto decide how to handle the result in your application. An empty `matches`\narray means the search returned no qualifying match; it does not establish that\nthe student is absent from Stadium."},"tags":[{"name":"Student search","description":"Find possible matches for students in your data."},{"name":"Authentication","description":"Check the access token used on a request."}],"servers":[{"url":"https://txedexchange-idrs.getstadium.org"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"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."}},"schemas":{"TokenInfo":{"type":"object","properties":{"client_id":{"type":"string","description":"The client identifier from the accepted access token.","example":"abc123"},"scopes":{"type":"array","items":{"type":"string"},"description":"Every scope this token carries, including partner scopes. Sorted alphabetically.","example":["partner:acme","student:identity:read"]},"partners":{"type":"array","items":{"type":"string"},"description":"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.","example":["acme"]},"expires_at":{"type":"integer","description":"The token expiration time as Unix time in seconds.","example":1755400000}},"required":["client_id","scopes","partners","expires_at"],"additionalProperties":false,"title":"TokenInfo","description":"Information about the accepted access token on this request.","example":{"client_id":"abc123","scopes":["partner:acme","student:identity:read"],"partners":["acme"],"expires_at":1755400000}},"StudentSearchResponse":{"type":"array","items":{"$ref":"#/components/schemas/StudentSearchResult"},"title":"StudentSearchResponse","description":"One result per submitted student, in input order. Each result contains zero or more possible matches."},"StudentSearchResult":{"type":"object","properties":{"correlation_id":{"type":"string","description":"The correlation_id from the corresponding input, returned unchanged.","example":"input-1"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/StudentMatch"},"description":"Possible matches, highest score first. May be empty."}},"required":["correlation_id","matches"],"additionalProperties":false,"title":"StudentSearchResult","description":"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."},"StudentMatch":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":1,"description":"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.","example":0.97},"student_unique_id":{"type":"string","description":"The `student_unique_id` stored in Stadium for this student. Keep the partner and tenant context with this identifier when using the result.","example":"student-1042"},"first_name":{"type":["string","null"],"description":"The student's given name from Stadium, or null when unavailable."},"middle_name":{"type":["string","null"],"description":"The student's middle name from Stadium, or null when unavailable."},"last_name":{"type":["string","null"],"description":"The student's family name from Stadium, or null when unavailable."},"birth_date":{"type":["string","null"],"format":"date","description":"Birth date from Stadium in YYYY-MM-DD format, or null when unavailable.","example":"2008-09-03"},"student_ids":{"type":"array","items":{"$ref":"#/components/schemas/StudentIdentifier"},"description":"Student identification codes from Stadium. May be empty."},"school_years":{"type":"array","items":{"type":"integer"},"description":"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.","example":[2024,2025]}},"required":["score","student_unique_id","first_name","middle_name","last_name","birth_date","student_ids","school_years"],"additionalProperties":false,"title":"StudentMatch","description":"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."},"StudentIdentifier":{"type":"object","properties":{"id_type":{"type":["string","null"],"description":"The Ed-Fi StudentIdentificationSystem label, when available in Stadium. Null means the identification system is unavailable.","example":null},"id_value":{"type":"string","description":"The student identification code from Stadium.","example":"SC800227"}},"required":["id_type","id_value"],"additionalProperties":false,"title":"StudentIdentifier","description":"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."},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"A short machine-readable code. Use this value for branching; use `message` and `details` for human-readable diagnostics.","example":"invalid_request"},"message":{"type":"string","description":"A human-readable explanation of the error, when available.","example":"This partner is not provisioned for search."},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"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.","example":"0.birth_date"},"message":{"type":"string","description":"Why the value at `path` is invalid.","example":"Invalid ISO date"}},"required":["path","message"],"additionalProperties":false},"description":"Present on validation failures. Each entry identifies one invalid value."}},"required":["error"],"additionalProperties":false,"title":"ErrorResponse","description":"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.","example":{"error":"invalid_request","details":[{"path":"0.birth_date","message":"Invalid ISO date"}]}},"StudentSearchRequest":{"type":"array","items":{"$ref":"#/components/schemas/StudentSearchInput"},"maxItems":5000,"title":"StudentSearchRequest","description":"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 `[]`."},"StudentSearchInput":{"type":"object","properties":{"correlation_id":{"type":"string","minLength":1,"example":"input-1","description":"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."},"first_name":{"type":["string","null"],"description":"The student's given name.","example":"Noor"},"last_name":{"type":["string","null"],"description":"The student's family name.","example":"Yang"},"birth_date":{"type":["string","null"],"format":"date","description":"The student's birth date, in YYYY-MM-DD format.","example":"2008-09-03"},"school_ids":{"type":["array","null"],"items":{"type":"integer"},"description":"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.","example":[255901044]},"student_ids":{"type":["array","null"],"items":{"type":"string"},"description":"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.","example":["SC800227"]}},"required":["correlation_id"],"additionalProperties":false,"title":"StudentSearchInput","description":"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."}},"parameters":{}},"paths":{"/token/verify":{"get":{"tags":["Authentication"],"operationId":"verifyToken","summary":"Inspect the access token on this request","description":"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":{"description":"The token was accepted. The `scopes` and `partners` arrays are sorted alphabetically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenInfo"}}}},"400":{"description":"The `Authorization` header was present but malformed. Send `Authorization: Bearer <token>`. The response is plain text, with `WWW-Authenticate: Bearer error=\"invalid_request\"`.","headers":{"WWW-Authenticate":{"schema":{"type":"string","description":"Bearer authentication challenge describing the malformed header.","example":"Bearer error=\"invalid_request\""},"required":true,"description":"Bearer authentication challenge describing the malformed header."}},"content":{"text/plain":{"schema":{"type":"string","example":"Bad Request"}}}},"401":{"description":"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\"`.","headers":{"WWW-Authenticate":{"schema":{"type":"string","description":"Bearer authentication challenge explaining the authentication failure.","example":"Bearer error=\"invalid_token\""},"required":true,"description":"Bearer authentication challenge explaining the authentication failure."}},"content":{"text/plain":{"schema":{"type":"string","example":"Unauthorized"}}}},"500":{"description":"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.","content":{"text/plain":{"schema":{"type":"string","example":"Internal Server Error"}}}}}}},"/partners/{partner}/tenants/{tenant}/students/search":{"post":{"tags":["Student search"],"operationId":"searchStudents","summary":"Find possible student matches","description":"Search student records in one partner and tenant using the details you know.\nThis is a read-only, synchronous search: the response contains the completed results.\n\n### Permissions and scope\n\nRequires both `student:identity:read` and `partner:<partner_id>` for the partner\nin the URL. Partner access covers all tenants within that partner. Searches never\ncross tenant boundaries. An unknown tenant returns no matches. The identity scope permits\nidentity searches; the partner scope identifies whose data the token may search.\n\n### Send a batch\n\nSend a JSON array of up to 5,000 student inputs. Only `correlation_id`\nis required for each input. Choose a nonempty string unique within the batch that your application\ncan use to associate the returned result with the submitted record.\nAll other fields may be omitted or null. Missing or null identifier lists behave\nas empty lists. Dates must use `YYYY-MM-DD`. Unknown object fields and duplicate\ncorrelation IDs are rejected. A valid input does not guarantee enough information\nto find useful matches. An empty array returns `[]`.\n\nThere are no supported query parameters; any supplied query parameters are ignored.\n\n### Read the results\n\nThe response is a JSON array with one result per input, in the same order. Each\nresult repeats your `correlation_id` and lists possible matches by descending\nscore. Student details in matches come from Stadium and may differ from your input.\nA possible match is not a confirmed identity. An empty `matches` array means no\nqualifying match was returned, not proof that the student is absent from Stadium.\n\nThe examples use fictional student data and illustrate single, multiple, and empty\nmatch results. Example scores do not define an acceptance threshold.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Partner ID identifying whose Stadium data to search. Requires the matching `partner:<partner_id>` token scope.","example":"acme"},"required":true,"description":"Partner ID identifying whose Stadium data to search. Requires the matching `partner:<partner_id>` token scope.","name":"partner","in":"path"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","description":"Tenant code within this partner, such as a district code. Contains only letters, digits, underscores, and hyphens. An unknown code returns no matches.","example":"district1"},"required":true,"description":"Tenant code within this partner, such as a district code. Contains only letters, digits, underscores, and hyphens. An unknown code returns no matches.","name":"tenant","in":"path"}],"requestBody":{"description":"A JSON array of up to 5,000 student inputs.","required":true,"content":{"application/json":{"examples":{"studentBatch":{"summary":"Search for three students","description":"Fictional inputs paired with the successful response example. Send only the details you know.","value":[{"correlation_id":"input-1","first_name":"Noor","last_name":"Yang","birth_date":"2008-09-03","school_ids":[255901044],"student_ids":["SC800227"]},{"correlation_id":"input-2","first_name":"Alex","last_name":"Rivera","birth_date":"2009-02-14"},{"correlation_id":"input-3","first_name":"Mina","last_name":"Patel","birth_date":null}]}},"schema":{"$ref":"#/components/schemas/StudentSearchRequest"}}}},"responses":{"200":{"description":"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.","content":{"application/json":{"examples":{"studentBatch":{"summary":"Single, multiple, and empty match results","description":"Illustrative results for the three-student request. Scores are examples, not acceptance thresholds.","value":[{"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":[]}]}},"schema":{"$ref":"#/components/schemas/StudentSearchResponse"}}}},"400":{"description":"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.","headers":{"WWW-Authenticate":{"schema":{"type":"string","description":"Present when the `Authorization` header is malformed. Other validation failures omit this header.","example":"Bearer error=\"invalid_request\""},"required":false,"description":"Present when the `Authorization` header is malformed. Other validation failures omit this header."}},"content":{"application/json":{"example":{"error":"invalid_request","details":[{"path":"0.birth_date","message":"Invalid ISO date"}]},"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/plain":{"examples":{"malformedAuthorization":{"summary":"Malformed Authorization header","value":"Bad Request"},"malformedJson":{"summary":"Malformed JSON body","value":"Malformed JSON in request body"}},"schema":{"type":"string"}}}},"401":{"description":"The access token is missing or unacceptable. Send a valid access token for this API in the `Authorization` header.","headers":{"WWW-Authenticate":{"schema":{"type":"string","description":"Bearer challenge. Missing credentials return `Bearer realm=\"stadium-api\"`; an unacceptable token returns `Bearer error=\"invalid_token\"`.","example":"Bearer error=\"invalid_token\""},"required":true,"description":"Bearer challenge. Missing credentials return `Bearer realm=\"stadium-api\"`; an unacceptable token returns `Bearer error=\"invalid_token\"`."}},"content":{"text/plain":{"schema":{"type":"string","example":"Unauthorized"}}}},"403":{"description":"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.","headers":{"WWW-Authenticate":{"schema":{"type":"string","description":"Bearer challenge. Carries `error` unless no credentials were sent, and the `scope` needed when one would have satisfied the request.","example":"Bearer realm=\"stadium-api\", error=\"insufficient_scope\", scope=\"student:identity:read\""},"required":true,"description":"Bearer challenge. Carries `error` unless no credentials were sent, and the `scope` needed when one would have satisfied the request."}},"content":{"application/json":{"example":{"error":"insufficient_scope"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"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.","content":{"application/json":{"example":{"error":"partner_not_found","message":"This partner is not provisioned for search."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"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.","content":{"application/json":{"example":{"error":"unsupported_media_type","message":"This endpoint accepts application/json; received no Content-Type header."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"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.","content":{"application/json":{"example":{"error":"search_error","message":"The service could not complete this search."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}},"text/plain":{"schema":{"type":"string","example":"Internal Server Error"}}}}}}}},"webhooks":{}}