{"service":"platform3 People & Orgs Alpha API","module":"people_and_orgs","surface":"alpha","belongsHereIf":"Who someone is and where they belong, as of a date.","allowedValues":{"brand":["100for100","alpha","gt","limitless_education","montessorium","nextgen","nova_academy","novatio","sw_sales","texas_sports_academy","towermath","unbound","waypoint"],"modality":["physical","virtual"],"segment":["charter","private","sw_sales","virtual","mixed"],"place_kind":["department","school","district","local","state","national"],"reality":["real","test","synthetic"],"level":["WL","LL","L1","L2","MS","HS"]},"allowedValueDetails":{"brand":[{"value":"100for100","meaning":"100for100 brand. Live active org validation found this brand in the campus taxonomy intersected with production org rows.","useWhen":"Use for NWEA-account district and school rows whose typed brand is 100for100.","invalidWhen":"Invalid as a fallback for Alpha, GT, Texas Sports Academy, or partner brands."},{"value":"alpha","meaning":"Alpha School brand. Live source aliases include Alpha, Alpha School, Alpha Anywhere, Alpha School campus names, and 2 Hour Learning legacy names.","useWhen":"Use for Alpha School physical and virtual NWEA-account rows.","invalidWhen":"Invalid for GT School, Texas Sports Academy, or non-Alpha partner schools."},{"value":"gt","meaning":"GT School brand. Live aliases include GT School and GT Anywhere.","useWhen":"Use for GT physical or virtual NWEA-account rows.","invalidWhen":"Invalid for Alpha or partner school rows."},{"value":"limitless_education","meaning":"Limitless Education brand observed in live active org rows.","useWhen":"Use for schools whose typed brand is Limitless Education.","invalidWhen":"Invalid for generic partner rows without that brand assignment."},{"value":"montessorium","meaning":"Montessorium brand observed in live active org rows.","useWhen":"Use for Montessorium school rows.","invalidWhen":"Invalid for Alpha, GT, or Texas Sports Academy rows."},{"value":"nextgen","meaning":"NextGen brand observed in live active org rows.","useWhen":"Use for NextGen Academy or NextGen tutoring rows.","invalidWhen":"Invalid for unrelated partner schools."},{"value":"nova_academy","meaning":"Nova Academy brand observed in live active org rows.","useWhen":"Use for Nova Academy campuses.","invalidWhen":"Invalid for Novatio; that is a separate brand value."},{"value":"novatio","meaning":"Novatio brand observed in live active org rows.","useWhen":"Use for Novatio rows.","invalidWhen":"Invalid for Nova Academy rows."},{"value":"sw_sales","meaning":"SW Sales segment/brand value observed across Allendale and similar live active org rows.","useWhen":"Use when the production taxonomy classifies the school as SW Sales.","invalidWhen":"Invalid for Alpha-owned campuses or Texas Sports Academy rows."},{"value":"texas_sports_academy","meaning":"Texas Sports Academy brand. Live aliases include Texas Sports Academy, TSA, TSA Online, and TSA sport/prep campus names.","useWhen":"Use for Texas Sports Academy physical and virtual accounts.","invalidWhen":"Invalid for Alpha, GT, or non-TSA partner rows."},{"value":"towermath","meaning":"TowerMath brand observed in live active org rows.","useWhen":"Use for TowerMath rows.","invalidWhen":"Invalid for Alpha math products unless the typed brand is TowerMath."},{"value":"unbound","meaning":"Unbound brand observed in live active org rows.","useWhen":"Use for Unbound Academy rows.","invalidWhen":"Invalid for other partner schools."},{"value":"waypoint","meaning":"Waypoint brand observed in live active org rows.","useWhen":"Use for Waypoint Academy rows.","invalidWhen":"Invalid for other partner schools."}],"modality":[{"value":"physical","meaning":"The NWEA account is for the physical-school modality of a brand. Live source aliases validated 2026-06-09: Physical folds here.","useWhen":"Use for the district or school place row representing the physical NWEA account or child school.","invalidWhen":"Invalid for virtual accounts or for a mixed/hybrid account."},{"value":"virtual","meaning":"The NWEA account is for the virtual-school modality of a brand. Live source aliases validated 2026-06-09: Virtual folds here.","useWhen":"Use for the district or school place row representing the virtual NWEA account or child school.","invalidWhen":"Invalid for physical accounts or for a mixed/hybrid account."}],"segment":[{"value":"charter","meaning":"Charter-school segment observed in live active org rows.","useWhen":"Use for schools whose typed segment is charter.","invalidWhen":"Invalid for private, virtual, or SW Sales rows."},{"value":"private","meaning":"Private-school segment observed in live active org rows.","useWhen":"Use for private school campuses and district accounts.","invalidWhen":"Invalid for virtual-only, charter, or SW Sales rows."},{"value":"sw_sales","meaning":"SW Sales segment observed in live active org rows.","useWhen":"Use for schools typed into the SW Sales segment.","invalidWhen":"Invalid for Alpha private/virtual rows unless the write boundary explicitly assigns SW Sales."},{"value":"virtual","meaning":"Virtual segment observed in live active org rows.","useWhen":"Use for schools or accounts whose segment is virtual.","invalidWhen":"Invalid for physical private or charter segment rows; modality still remains physical or virtual separately."},{"value":"mixed","meaning":"District/account rollup reserved for a district spanning multiple segments.","useWhen":"Use only on a district/account row that intentionally spans more than one segment.","invalidWhen":"Invalid on an ordinary school row or as a substitute for unknown."}],"place_kind":[{"value":"department","meaning":"Department-level organization, usually below a school or district.","useWhen":"Use for academic/administrative departments that can own courses or roles but should not satisfy school_sourced_id references.","invalidWhen":"Invalid as the target of classes.school_sourced_id or enrollments.school_sourced_id."},{"value":"school","meaning":"School/building organization and the required org type for school-scoped class, enrollment, and line-item references.","useWhen":"Use when a row can be referenced by classes.school_sourced_id, enrollments.school_sourced_id, or line_items.school_sourced_id.","invalidWhen":"Invalid for district or department rows that should only be hierarchy parents."},{"value":"district","meaning":"District organization that commonly parents school rows.","useWhen":"Use as parent_sourced_id for schools or for district-level roles/courses where the source sends them.","invalidWhen":"Invalid as a class/enrollment school_sourced_id target."},{"value":"local","meaning":"Local education authority or local-level organization.","useWhen":"Use when the source models an LEA/local authority distinct from a district.","invalidWhen":"Invalid as a school_sourced_id target unless the source profile explicitly says local rows are schools."},{"value":"state","meaning":"State-level education agency or authority.","useWhen":"Use as a hierarchy ancestor or role scope when supplied by the source.","invalidWhen":"Invalid as a class/enrollment school_sourced_id target."},{"value":"national","meaning":"National-level education agency or authority.","useWhen":"Use only for national hierarchy/role contexts supplied by the source.","invalidWhen":"Invalid as a school_sourced_id target or ordinary school parent when a district/local row exists."}],"reality":[{"value":"real","meaning":"A production student, person, school, district, or roster place that belongs in ordinary customer reports.","useWhen":"Use for real TimeBack people and places after the write boundary has verified the source classification.","invalidWhen":"Invalid for QA accounts, AI-agent test rows, generated fixtures, or demo-only entities."},{"value":"test","meaning":"A QA, staff-test, integration-test, or AI-agent test entity that must be excluded from ordinary reports.","useWhen":"Use for entities intentionally created to test the surface or another app.","invalidWhen":"Invalid for production students or schools even if their display name looks unusual."},{"value":"synthetic","meaning":"Generated, seeded, anonymized, or fixture data that is useful for demos or development but not a real customer row.","useWhen":"Use for generated seed rows, local fixtures, and anonymized examples.","invalidWhen":"Invalid for a row imported from the authoritative SIS or TimeBack production source as a real entity."}],"level":[{"value":"WL","meaning":"WonderLab, the pre-K Alpha level. Live source alias validated 2026-06-09: PKBY folds here.","useWhen":"Use for the pre-K Alpha level, point-in-time as of the roster date.","invalidWhen":"Invalid for kindergarten, LearningLab, or any grade-level placement."},{"value":"LL","meaning":"LearningLab, the K-1 Alpha level. Live source alias validated 2026-06-09: Linc folds here.","useWhen":"Use for K-1 Alpha-level grouping, point-in-time as of the roster date.","invalidWhen":"Invalid for WonderLab or numbered upper levels."},{"value":"L1","meaning":"Level 1, the grade 2-3 Alpha level after live cohort confirmation.","useWhen":"Use for the Alpha level spanning grade 2 through grade 3.","invalidWhen":"Invalid for grade 4+ cohorts or for MAP working-grade state."},{"value":"L2","meaning":"Level 2, the grade 4-5 Alpha level after live cohort confirmation.","useWhen":"Use for the Alpha level spanning grade 4 through grade 5.","invalidWhen":"Invalid for grade 2-3, middle school, high school, or Results working-grade state."},{"value":"MS","meaning":"Middle School, the grade 6-8 Alpha level. Live source aliases validated 2026-06-09: Middle School and L3 fold here.","useWhen":"Use for middle-school Alpha-level grouping.","invalidWhen":"Invalid for high school or elementary level rows."},{"value":"HS","meaning":"High School, the grade 9-12 Alpha level. Live source aliases validated 2026-06-09: High School, L4.1, L4.2, and L4.3 fold here.","useWhen":"Use for high-school Alpha-level grouping.","invalidWhen":"Invalid for middle-school or elementary level rows."}]},"orgTaxonomyContract":{"owner":"People & Orgs","groupingGrain":"Brand x Modality","fields":{"brand":"Closed reporting brand for the NWEA account boundary.","modality":"Closed physical or virtual modality for the NWEA account boundary.","segment":"Closed operating segment for school and district reporting slices.","nwea_district_id":"Required on district rows because each Brand x Modality maps 1:1 to an NWEA account."},"requiredOnPlaceKinds":["district","school"],"districtAccountRule":"Each Brand x Modality is represented as a district place with a required nwea_district_id.","schoolRule":"Only place_kind=school anchors enrollments; brand, modality, and segment refine grouping but never override place_kind.","mixedSegmentRule":"segment=mixed is only for a district/account row intentionally spanning multiple segments; it is never an unknown fallback.","locationRule":"Location is derived from school address fields, not parsed from place names.","sourceOfTruth":"https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/data_dictionary#field-alpha-place-brand"},"behaviorContracts":["Brand, modality, and segment are typed closed values on district and school places.","Each Brand x Modality is a district place with required nwea_district_id; schools attach below it by parent_place_id.","segment=mixed is reserved for multi-segment district/account rows and must not be used as an unknown fallback.","Clients must not infer brand, modality, segment, or location by parsing place names."],"dateSemanticsContract":{"owner":"People & Orgs","personLifecycle":{"fields":["admission_date","exit_date"],"source":"alpha.person_ext surfaced through alpha.person","rule":"admission_date is the person-level lifecycle open date; exit_date is the exclusive person-level lifecycle close date; null exit_date means the person lifecycle remains open after admission_date."},"membershipIntervals":{"fields":["begin_date","end_date","is_time_locatable"],"source":"alpha.place_membership, alpha.class_membership, alpha.alpha_level_history, alpha.age_grade_history","rule":"begin_date <= asOfDate < end_date; begin_date null is not time-locatable and excluded; null end_date means active after begin_date."},"schoolPeriods":{"fields":["start_date","end_date"],"source":"alpha.school_period","rule":"start_date/end_date name academic periods only; they are never person admission/exit or membership interval fields."},"invalidWhen":"A consumer or implementation derives person exit_date from a membership end_date, uses school_period start_date as admission_date, or exposes a generic person start_date."},"endpoints":{"demoToken":"/api/dev/mint","demoTokenAlias":"/api/demo-token","collections":["/api/people","/api/places","/api/alpha_level_history","/api/age_grade_history","/api/place_memberships","/api/class_memberships","/api/school_periods","/api/person_sensitive_profiles","/api/guardians","/api/guardian_relationships","/api/staff_assignments","/api/program_participations","/api/app_credentials","/api/tag_definitions","/api/object_tags"],"policyConfig":"/api/policy_config","schoolCalendar":{"day":"/api/places/{placeId}/school_calendar/{date}","range":"/api/places/{placeId}/school_calendar?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD","between":"/api/places/{placeId}/school_days_between?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD","remaining":"/api/places/{placeId}/school_days_remaining?asOfDate=YYYY-MM-DD","nextSchoolYearStart":"/api/places/{placeId}/next_school_year_start?asOfDate=YYYY-MM-DD"},"namedReads":{"alphaLevel":"/api/people/{personId}/alpha_level?asOfDate=YYYY-MM-DD","ageGrade":"/api/people/{personId}/age_grade?asOfDate=YYYY-MM-DD","enrolledGradeInSubject":"/api/people/{personId}/enrolled_grade?subject=math&asOfDate=YYYY-MM-DD","firstEnrolledCourseGrade":"/api/people/{personId}/enrollment_anchors/first_enrolled_course_grade?subject=math","firstSingleGradeEnrollmentDate":"/api/people/{personId}/enrollment_anchors/first_single_grade?subject=math","studentsForGuide":"/api/guides/{guidePersonId}/students?asOfDate=YYYY-MM-DD"},"imports":{"timebackClassContext":"/api/imports/timeback-class-context"},"subcollections":["/api/people/{personId}/memberships","/api/people/{personId}/alpha_level","/api/people/{personId}/age_grade","/api/people/{personId}/enrolled_grade","/api/people/{personId}/enrollment_anchors/first_enrolled_course_grade","/api/people/{personId}/enrollment_anchors/first_single_grade","/api/guides/{guidePersonId}/students","/api/places/{placeId}/people","/api/places/{placeId}/school_calendar/{date}","/api/places/{placeId}/school_calendar","/api/places/{placeId}/school_days_between","/api/places/{placeId}/school_days_remaining","/api/places/{placeId}/next_school_year_start","/api/people/{personId}/guardians","/api/people/{personId}/program_participations","/api/places/{placeId}/staff_assignments","/api/places/{placeId}/schools","/api/school_periods/{periodId}/active_memberships"]},"quickstart":{"createPerson":{"method":"POST","path":"/api/people","requiredHeaders":["Authorization: Bearer <token>","Content-Type: application/json","Idempotency-Key: <stable retry key>"],"body":{"person_id":"person_demo_roster_widget","reality":"real","is_enabled":true,"username":"demo.roster.widget","first_name":"Demo","last_name":"Student","email":"demo.roster.widget@example.edu","family_or_agent_person_ids":[],"grade_levels":[8],"primary_place_id":"place_north_valley_school","admission_date":"2026-08-15","exit_date":null,"age_grade":8,"source_status":"active"},"tolerantAliases":["personId","isEnabled","firstName","lastName","fullName","full_name","name","gradeLevels","primaryPlaceId","admissionDate","exitDate","ageGrade","reality"]},"patchPerson":{"method":"PATCH","path":"/api/people/{personId}","requiredHeaders":["Authorization: Bearer <token>","Content-Type: application/json","If-Match: <current ETag>","Idempotency-Key: <stable retry key>"],"body":{"preferred_first_name":"Demo","email":"demo.student@example.edu"},"responseHeaders":{"ETag":"The validated request validator, echoed so Vercel accepts native If-Match mutations.","X-People-Orgs-ETag":"Current saved People & Orgs validator. Use this explicit header as the next If-Match value when chaining mutations."}}},"links":{"architecture":"https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture","dataDictionary":"https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/data_dictionary","customerWebsite":"https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/customer_website","aliasMap":"https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture#alias-map"}}