> For the complete documentation index, see [llms.txt](https://guide.fariaedu.com/integrations-portal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.fariaedu.com/integrations-portal/schoolsbuddy/public-rest-apis/pref.md).

# Pref

## GET /api/v1/CcaSignUp/Pref

> Gets a paginated list of Preference signups for the calling
> \
> organisation(s), sorted by id. Archived signups are added when
> \
> includeArchived is true; search filters on the signup name.

```json
{"openapi":"3.0.1","info":{"title":"SchoolsBuddy Public API","version":"1.0"},"servers":[{"url":"https://publicapi-eu.schoolsbuddy.net","description":"EMEA Public Api server"},{"url":"https://publicapi-asia.schoolsbuddy.net","description":"Asia Public Api server"},{"url":"https://publicapi-us.schoolsbuddy.net","description":"US Public Api server"},{"url":"https://publicapi.schoolsbuddy.cn","description":"China Public Api server"},{"url":"https://identity-eu.schoolsbuddy.net","description":"EMEA Identity server"},{"url":"https://identity-asia.schoolsbuddy.net","description":"Asia Identity server"},{"url":"https://identity-us.schoolsbuddy.net","description":"US Identity server"},{"url":"https://accounts.schoolsbuddy.cn","description":"China Identity server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Type \"Bearer\" followed by a space and a token.","name":"Authorization","in":"header"}},"schemas":{"PrefResponseDtoListPagedPrefFilterResponseDto":{"type":"object","properties":{"isSuccess":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"},"nullable":true},"messageTranslationParameters":{"nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PrefResponseDto"},"nullable":true},"pageNumber":{"type":"integer","format":"int32"},"pageSize":{"type":"integer","format":"int32"},"firstPage":{"type":"string","format":"uri","nullable":true},"lastPage":{"type":"string","format":"uri","nullable":true},"totalPages":{"type":"integer","format":"int32"},"totalRecords":{"type":"integer","format":"int32"},"nextPage":{"type":"string","format":"uri","nullable":true},"previousPage":{"type":"string","format":"uri","nullable":true},"baseUri":{"type":"string","format":"uri","nullable":true},"searchParameters":{"type":"array","items":{"$ref":"#/components/schemas/StringStringKeyValuePair"},"nullable":true}},"additionalProperties":false},"PrefResponseDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"organisationId":{"type":"integer","format":"int32"},"containerTypeId":{"type":"integer","format":"int32"},"preferenceTypeId":{"type":"integer","format":"int32"},"preferenceSelectionScope":{"$ref":"#/components/schemas/PreferenceSelectionScopeEnum"},"eventCategoryId":{"type":"integer","format":"int32","nullable":true},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"activitiesStartDate":{"type":"string","format":"date"},"activitiesEndDate":{"type":"string","format":"date"},"activitiesDefaultStartTime":{"type":"string","format":"partial-time","nullable":true},"activitiesDefaultEndTime":{"type":"string","format":"partial-time","nullable":true},"responsibilityForConfirmation":{"$ref":"#/components/schemas/CcaSignupResponsibility"},"signupOpens":{"type":"string","format":"date-time","nullable":true},"signupCloses":{"type":"string","format":"date-time","nullable":true},"useOrganisationBlockDates":{"type":"boolean","nullable":true},"termsAndConditions":{"type":"string","nullable":true},"additionalInfoUrl":{"type":"string","nullable":true},"isArchived":{"type":"boolean"},"timeZone":{"type":"string","nullable":true},"createdAtUtc":{"type":"string","format":"date-time","nullable":true},"updatedAtUtc":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":false},"PreferenceSelectionScopeEnum":{"enum":["Daily","Weekly"],"type":"string"},"CcaSignupResponsibility":{"enum":["None","PupilsOrParents","ParentsOnly","PupilsOnly"],"type":"string"},"StringStringKeyValuePair":{"type":"object","properties":{"key":{"type":"string","nullable":true},"value":{"type":"string","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`,\r\n`INTERNAL_ERROR`) per cross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"Structured body for 4xx / 5xx responses on the new Public API surface:\r\na machine-readable SchoolsBuddy.PublicAPI.Models.ErrorResponse.Code plus a human-readable\r\nSchoolsBuddy.PublicAPI.Models.ErrorResponse.Error. See cross-cutting-design.md §5.3. This is additive —\r\nexisting endpoints continue returning their legacy plain-string /\r\nModelState shapes until migrated by their per-controller ticket."}}},"paths":{"/api/v1/CcaSignUp/Pref":{"get":{"tags":["Pref"],"summary":"Gets a paginated list of Preference signups for the calling\r\norganisation(s), sorted by id. Archived signups are added when\r\nincludeArchived is true; search filters on the signup name.","parameters":[{"name":"IncludeArchived","in":"query","schema":{"type":"boolean"}},{"name":"Search","in":"query","schema":{"type":"string"}},{"name":"PageNumber","in":"query","schema":{"maximum":2147483647,"minimum":1,"type":"integer","format":"int32"}},{"name":"PageSize","in":"query","schema":{"maximum":2000,"minimum":1,"type":"integer","format":"int32"}},{"name":"OrganisationIds","in":"query","schema":{"type":"array","items":{"type":"integer","format":"int32"}}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrefResponseDtoListPagedPrefFilterResponseDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## POST /api/v1/CcaSignUp/Pref

> Creates a Preference signup. The container type and the preference
> \
> type are both derived from the URL — the server always creates
> \
> Preference rows. preferenceSelectionScope chooses whether a pupil's
> \
> 1-5 ranking restarts each day (Daily, the default) or runs across
> \
> the whole week (Weekly); it accepts the name or its ordinal. The
> \
> signup always starts unarchived. The name must be unique among the
> \
> organisation's active signups.

```json
{"openapi":"3.0.1","info":{"title":"SchoolsBuddy Public API","version":"1.0"},"servers":[{"url":"https://publicapi-eu.schoolsbuddy.net","description":"EMEA Public Api server"},{"url":"https://publicapi-asia.schoolsbuddy.net","description":"Asia Public Api server"},{"url":"https://publicapi-us.schoolsbuddy.net","description":"US Public Api server"},{"url":"https://publicapi.schoolsbuddy.cn","description":"China Public Api server"},{"url":"https://identity-eu.schoolsbuddy.net","description":"EMEA Identity server"},{"url":"https://identity-asia.schoolsbuddy.net","description":"Asia Identity server"},{"url":"https://identity-us.schoolsbuddy.net","description":"US Identity server"},{"url":"https://accounts.schoolsbuddy.cn","description":"China Identity server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Type \"Bearer\" followed by a space and a token.","name":"Authorization","in":"header"}},"schemas":{"CreatePrefRequestDto":{"required":["activitiesEndDate","activitiesStartDate","description","eventCategoryId","name","signupCloses","signupOpens"],"type":"object","properties":{"name":{"maxLength":255,"minLength":1,"type":"string"},"description":{"minLength":1,"type":"string"},"preferenceSelectionScope":{"$ref":"#/components/schemas/PreferenceSelectionScopeEnum"},"eventCategoryId":{"maximum":2147483647,"minimum":1,"type":"integer","format":"int32"},"activitiesStartDate":{"type":"string","format":"date"},"activitiesEndDate":{"type":"string","format":"date"},"activitiesDefaultStartTime":{"type":"string","format":"partial-time","nullable":true},"activitiesDefaultEndTime":{"type":"string","format":"partial-time","nullable":true},"responsibilityForConfirmation":{"$ref":"#/components/schemas/CcaSignupResponsibility"},"signupOpens":{"type":"string","format":"date-time"},"signupCloses":{"type":"string","format":"date-time"},"termsAndConditions":{"type":"string","nullable":true},"additionalInfoUrl":{"type":"string","nullable":true}},"additionalProperties":false},"PreferenceSelectionScopeEnum":{"enum":["Daily","Weekly"],"type":"string"},"CcaSignupResponsibility":{"enum":["None","PupilsOrParents","ParentsOnly","PupilsOnly"],"type":"string"},"PrefResponseDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"organisationId":{"type":"integer","format":"int32"},"containerTypeId":{"type":"integer","format":"int32"},"preferenceTypeId":{"type":"integer","format":"int32"},"preferenceSelectionScope":{"$ref":"#/components/schemas/PreferenceSelectionScopeEnum"},"eventCategoryId":{"type":"integer","format":"int32","nullable":true},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"activitiesStartDate":{"type":"string","format":"date"},"activitiesEndDate":{"type":"string","format":"date"},"activitiesDefaultStartTime":{"type":"string","format":"partial-time","nullable":true},"activitiesDefaultEndTime":{"type":"string","format":"partial-time","nullable":true},"responsibilityForConfirmation":{"$ref":"#/components/schemas/CcaSignupResponsibility"},"signupOpens":{"type":"string","format":"date-time","nullable":true},"signupCloses":{"type":"string","format":"date-time","nullable":true},"useOrganisationBlockDates":{"type":"boolean","nullable":true},"termsAndConditions":{"type":"string","nullable":true},"additionalInfoUrl":{"type":"string","nullable":true},"isArchived":{"type":"boolean"},"timeZone":{"type":"string","nullable":true},"createdAtUtc":{"type":"string","format":"date-time","nullable":true},"updatedAtUtc":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`,\r\n`INTERNAL_ERROR`) per cross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"Structured body for 4xx / 5xx responses on the new Public API surface:\r\na machine-readable SchoolsBuddy.PublicAPI.Models.ErrorResponse.Code plus a human-readable\r\nSchoolsBuddy.PublicAPI.Models.ErrorResponse.Error. See cross-cutting-design.md §5.3. This is additive —\r\nexisting endpoints continue returning their legacy plain-string /\r\nModelState shapes until migrated by their per-controller ticket."}}},"paths":{"/api/v1/CcaSignUp/Pref":{"post":{"tags":["Pref"],"summary":"Creates a Preference signup. The container type and the preference\r\ntype are both derived from the URL — the server always creates\r\nPreference rows. preferenceSelectionScope chooses whether a pupil's\r\n1-5 ranking restarts each day (Daily, the default) or runs across\r\nthe whole week (Weekly); it accepts the name or its ordinal. The\r\nsignup always starts unarchived. The name must be unique among the\r\norganisation's active signups.","parameters":[{"name":"organisationId","in":"query","description":"The organisation to create the signup in — required when the client has access to multiple organisations","schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The create request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePrefRequestDto"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrefResponseDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## GET /api/v1/CcaSignUp/Pref/{id}

> Gets a single Preference signup by id. Archived signups — and
> \
> signups of any other container type (Instant Book & Pay, PTC) —
> \
> return 404 CCASIGNUP\_NOT\_FOUND.

```json
{"openapi":"3.0.1","info":{"title":"SchoolsBuddy Public API","version":"1.0"},"servers":[{"url":"https://publicapi-eu.schoolsbuddy.net","description":"EMEA Public Api server"},{"url":"https://publicapi-asia.schoolsbuddy.net","description":"Asia Public Api server"},{"url":"https://publicapi-us.schoolsbuddy.net","description":"US Public Api server"},{"url":"https://publicapi.schoolsbuddy.cn","description":"China Public Api server"},{"url":"https://identity-eu.schoolsbuddy.net","description":"EMEA Identity server"},{"url":"https://identity-asia.schoolsbuddy.net","description":"Asia Identity server"},{"url":"https://identity-us.schoolsbuddy.net","description":"US Identity server"},{"url":"https://accounts.schoolsbuddy.cn","description":"China Identity server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Type \"Bearer\" followed by a space and a token.","name":"Authorization","in":"header"}},"schemas":{"PrefResponseDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"organisationId":{"type":"integer","format":"int32"},"containerTypeId":{"type":"integer","format":"int32"},"preferenceTypeId":{"type":"integer","format":"int32"},"preferenceSelectionScope":{"$ref":"#/components/schemas/PreferenceSelectionScopeEnum"},"eventCategoryId":{"type":"integer","format":"int32","nullable":true},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"activitiesStartDate":{"type":"string","format":"date"},"activitiesEndDate":{"type":"string","format":"date"},"activitiesDefaultStartTime":{"type":"string","format":"partial-time","nullable":true},"activitiesDefaultEndTime":{"type":"string","format":"partial-time","nullable":true},"responsibilityForConfirmation":{"$ref":"#/components/schemas/CcaSignupResponsibility"},"signupOpens":{"type":"string","format":"date-time","nullable":true},"signupCloses":{"type":"string","format":"date-time","nullable":true},"useOrganisationBlockDates":{"type":"boolean","nullable":true},"termsAndConditions":{"type":"string","nullable":true},"additionalInfoUrl":{"type":"string","nullable":true},"isArchived":{"type":"boolean"},"timeZone":{"type":"string","nullable":true},"createdAtUtc":{"type":"string","format":"date-time","nullable":true},"updatedAtUtc":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":false},"PreferenceSelectionScopeEnum":{"enum":["Daily","Weekly"],"type":"string"},"CcaSignupResponsibility":{"enum":["None","PupilsOrParents","ParentsOnly","PupilsOnly"],"type":"string"},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`,\r\n`INTERNAL_ERROR`) per cross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"Structured body for 4xx / 5xx responses on the new Public API surface:\r\na machine-readable SchoolsBuddy.PublicAPI.Models.ErrorResponse.Code plus a human-readable\r\nSchoolsBuddy.PublicAPI.Models.ErrorResponse.Error. See cross-cutting-design.md §5.3. This is additive —\r\nexisting endpoints continue returning their legacy plain-string /\r\nModelState shapes until migrated by their per-controller ticket."}}},"paths":{"/api/v1/CcaSignUp/Pref/{id}":{"get":{"tags":["Pref"],"summary":"Gets a single Preference signup by id. Archived signups — and\r\nsignups of any other container type (Instant Book & Pay, PTC) —\r\nreturn 404 CCASIGNUP_NOT_FOUND.","parameters":[{"name":"id","in":"path","description":"The signup id (CcaSignUp.CcaSignUpId)","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"organisationId","in":"query","description":"The organisation to look the signup up in — required when the client has access to multiple organisations","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrefResponseDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## PUT /api/v1/CcaSignUp/Pref/{id}

> Partially updates a Preference signup — omitted fields preserve
> \
> their existing values (§3.7e). The URL {id} is the canonical
> \
> identifier; the body carries no id. The signup's
> \
> archive state cannot be changed here: it follows its groups —
> \
> archiving the last live group archives the signup, unarchiving any
> \
> group re-activates it. Any write against an archived signup returns
> \
> 409 RESOURCE\_ARCHIVED.

```json
{"openapi":"3.0.1","info":{"title":"SchoolsBuddy Public API","version":"1.0"},"servers":[{"url":"https://publicapi-eu.schoolsbuddy.net","description":"EMEA Public Api server"},{"url":"https://publicapi-asia.schoolsbuddy.net","description":"Asia Public Api server"},{"url":"https://publicapi-us.schoolsbuddy.net","description":"US Public Api server"},{"url":"https://publicapi.schoolsbuddy.cn","description":"China Public Api server"},{"url":"https://identity-eu.schoolsbuddy.net","description":"EMEA Identity server"},{"url":"https://identity-asia.schoolsbuddy.net","description":"Asia Identity server"},{"url":"https://identity-us.schoolsbuddy.net","description":"US Identity server"},{"url":"https://accounts.schoolsbuddy.cn","description":"China Identity server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Type \"Bearer\" followed by a space and a token.","name":"Authorization","in":"header"}},"schemas":{"UpdatePrefRequestDto":{"type":"object","properties":{"name":{"maxLength":255,"type":"string","nullable":true},"description":{"type":"string","nullable":true},"preferenceSelectionScope":{"$ref":"#/components/schemas/PreferenceSelectionScopeEnum"},"eventCategoryId":{"maximum":2147483647,"minimum":1,"type":"integer","format":"int32","nullable":true},"activitiesStartDate":{"type":"string","format":"date","nullable":true},"activitiesEndDate":{"type":"string","format":"date","nullable":true},"activitiesDefaultStartTime":{"type":"string","format":"partial-time","nullable":true},"activitiesDefaultEndTime":{"type":"string","format":"partial-time","nullable":true},"responsibilityForConfirmation":{"$ref":"#/components/schemas/CcaSignupResponsibility"},"signupOpens":{"type":"string","format":"date-time","nullable":true},"signupCloses":{"type":"string","format":"date-time","nullable":true},"termsAndConditions":{"type":"string","nullable":true},"additionalInfoUrl":{"type":"string","nullable":true}},"additionalProperties":false},"PreferenceSelectionScopeEnum":{"enum":["Daily","Weekly"],"type":"string"},"CcaSignupResponsibility":{"enum":["None","PupilsOrParents","ParentsOnly","PupilsOnly"],"type":"string"},"PrefResponseDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"organisationId":{"type":"integer","format":"int32"},"containerTypeId":{"type":"integer","format":"int32"},"preferenceTypeId":{"type":"integer","format":"int32"},"preferenceSelectionScope":{"$ref":"#/components/schemas/PreferenceSelectionScopeEnum"},"eventCategoryId":{"type":"integer","format":"int32","nullable":true},"name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"activitiesStartDate":{"type":"string","format":"date"},"activitiesEndDate":{"type":"string","format":"date"},"activitiesDefaultStartTime":{"type":"string","format":"partial-time","nullable":true},"activitiesDefaultEndTime":{"type":"string","format":"partial-time","nullable":true},"responsibilityForConfirmation":{"$ref":"#/components/schemas/CcaSignupResponsibility"},"signupOpens":{"type":"string","format":"date-time","nullable":true},"signupCloses":{"type":"string","format":"date-time","nullable":true},"useOrganisationBlockDates":{"type":"boolean","nullable":true},"termsAndConditions":{"type":"string","nullable":true},"additionalInfoUrl":{"type":"string","nullable":true},"isArchived":{"type":"boolean"},"timeZone":{"type":"string","nullable":true},"createdAtUtc":{"type":"string","format":"date-time","nullable":true},"updatedAtUtc":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`,\r\n`INTERNAL_ERROR`) per cross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"Structured body for 4xx / 5xx responses on the new Public API surface:\r\na machine-readable SchoolsBuddy.PublicAPI.Models.ErrorResponse.Code plus a human-readable\r\nSchoolsBuddy.PublicAPI.Models.ErrorResponse.Error. See cross-cutting-design.md §5.3. This is additive —\r\nexisting endpoints continue returning their legacy plain-string /\r\nModelState shapes until migrated by their per-controller ticket."}}},"paths":{"/api/v1/CcaSignUp/Pref/{id}":{"put":{"tags":["Pref"],"summary":"Partially updates a Preference signup — omitted fields preserve\r\ntheir existing values (§3.7e). The URL {id} is the canonical\r\nidentifier; the body carries no id. The signup's\r\narchive state cannot be changed here: it follows its groups —\r\narchiving the last live group archives the signup, unarchiving any\r\ngroup re-activates it. Any write against an archived signup returns\r\n409 RESOURCE_ARCHIVED.","parameters":[{"name":"id","in":"path","description":"The signup id (CcaSignUp.CcaSignUpId)","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"organisationId","in":"query","description":"The organisation the signup belongs to — required when the client has access to multiple organisations","schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The update request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePrefRequestDto"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrefResponseDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## GET /api/v1/CcaSignUp/Pref/{id}/groups

> Gets a paginated list of a Preference signup's child groups, sorted
> \
> by id. Archived groups are added when includeArchived is true. The
> \
> sub-resource list has no search parameter (locked 2026-06-23). The
> \
> parent may be archived — its groups stay listable so callers can
> \
> find the ids to unarchive.

```json
{"openapi":"3.0.1","info":{"title":"SchoolsBuddy Public API","version":"1.0"},"servers":[{"url":"https://publicapi-eu.schoolsbuddy.net","description":"EMEA Public Api server"},{"url":"https://publicapi-asia.schoolsbuddy.net","description":"Asia Public Api server"},{"url":"https://publicapi-us.schoolsbuddy.net","description":"US Public Api server"},{"url":"https://publicapi.schoolsbuddy.cn","description":"China Public Api server"},{"url":"https://identity-eu.schoolsbuddy.net","description":"EMEA Identity server"},{"url":"https://identity-asia.schoolsbuddy.net","description":"Asia Identity server"},{"url":"https://identity-us.schoolsbuddy.net","description":"US Identity server"},{"url":"https://accounts.schoolsbuddy.cn","description":"China Identity server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Type \"Bearer\" followed by a space and a token.","name":"Authorization","in":"header"}},"schemas":{"PrefGroupResponseDtoListPagedPrefGroupFilterResponseDto":{"type":"object","properties":{"isSuccess":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"},"nullable":true},"messageTranslationParameters":{"nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PrefGroupResponseDto"},"nullable":true},"pageNumber":{"type":"integer","format":"int32"},"pageSize":{"type":"integer","format":"int32"},"firstPage":{"type":"string","format":"uri","nullable":true},"lastPage":{"type":"string","format":"uri","nullable":true},"totalPages":{"type":"integer","format":"int32"},"totalRecords":{"type":"integer","format":"int32"},"nextPage":{"type":"string","format":"uri","nullable":true},"previousPage":{"type":"string","format":"uri","nullable":true},"baseUri":{"type":"string","format":"uri","nullable":true},"searchParameters":{"type":"array","items":{"$ref":"#/components/schemas/StringStringKeyValuePair"},"nullable":true}},"additionalProperties":false},"PrefGroupResponseDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"organisationId":{"type":"integer","format":"int32"},"groupName":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"groupCode":{"type":"string","nullable":true},"billingCode":{"type":"string","nullable":true},"leadStaffId":{"type":"integer","format":"int32","nullable":true},"activityId":{"type":"integer","format":"int32","nullable":true},"showInSportsPortal":{"type":"boolean"},"locationId":{"type":"integer","format":"int32","nullable":true},"informationOnly":{"type":"boolean"},"day1":{"$ref":"#/components/schemas/DayOfWeekType"},"day1StartTime":{"type":"string","format":"partial-time","nullable":true},"day1EndTime":{"type":"string","format":"partial-time","nullable":true},"day2":{"$ref":"#/components/schemas/DayOfWeekType"},"day2StartTime":{"type":"string","format":"partial-time","nullable":true},"day2EndTime":{"type":"string","format":"partial-time","nullable":true},"maximumPlaces":{"type":"integer","format":"int32"},"minimumPlaces":{"type":"integer","format":"int32"},"cost":{"type":"number","format":"double"},"costType":{"$ref":"#/components/schemas/CcaCostTypeEnum"},"joinRequestsOn":{"type":"boolean","nullable":true},"availableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"preRequisite":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"notAvailableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"genderAvailableTo":{"$ref":"#/components/schemas/TeamGenderType"},"taxCode":{"type":"string","nullable":true},"shortName":{"type":"string","nullable":true},"isArchived":{"type":"boolean"},"timeZone":{"type":"string","nullable":true},"createdAtUtc":{"type":"string","format":"date-time","nullable":true},"updatedAtUtc":{"type":"string","format":"date-time"}},"additionalProperties":false},"DayOfWeekType":{"enum":["Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"],"type":"string"},"CcaCostTypeEnum":{"enum":["FreeOfCharge","PerTermOrSeason","PerSession","OneOff"],"type":"string"},"CcaGroupReferenceDto":{"required":["type"],"type":"object","properties":{"id":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32"},"type":{"$ref":"#/components/schemas/CcaGroupReferenceType"}},"additionalProperties":false},"CcaGroupReferenceType":{"enum":["Group","Class","House","Year","SubjectClass"],"type":"string"},"TeamGenderType":{"enum":["Female","Male","Mixed"],"type":"string"},"StringStringKeyValuePair":{"type":"object","properties":{"key":{"type":"string","nullable":true},"value":{"type":"string","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`,\r\n`INTERNAL_ERROR`) per cross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"Structured body for 4xx / 5xx responses on the new Public API surface:\r\na machine-readable SchoolsBuddy.PublicAPI.Models.ErrorResponse.Code plus a human-readable\r\nSchoolsBuddy.PublicAPI.Models.ErrorResponse.Error. See cross-cutting-design.md §5.3. This is additive —\r\nexisting endpoints continue returning their legacy plain-string /\r\nModelState shapes until migrated by their per-controller ticket."}}},"paths":{"/api/v1/CcaSignUp/Pref/{id}/groups":{"get":{"tags":["Pref"],"summary":"Gets a paginated list of a Preference signup's child groups, sorted\r\nby id. Archived groups are added when includeArchived is true. The\r\nsub-resource list has no search parameter (locked 2026-06-23). The\r\nparent may be archived — its groups stay listable so callers can\r\nfind the ids to unarchive.","parameters":[{"name":"id","in":"path","description":"The parent signup id (CcaSignUp.CcaSignUpId)","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"IncludeArchived","in":"query","schema":{"type":"boolean"}},{"name":"PageNumber","in":"query","schema":{"maximum":2147483647,"minimum":1,"type":"integer","format":"int32"}},{"name":"PageSize","in":"query","schema":{"maximum":2000,"minimum":1,"type":"integer","format":"int32"}},{"name":"OrganisationIds","in":"query","schema":{"type":"array","items":{"type":"integer","format":"int32"}}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrefGroupResponseDtoListPagedPrefGroupFilterResponseDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## POST /api/v1/CcaSignUp/Pref/{id}/groups

> Creates a child group under a Preference signup. The parent signup
> \
> must exist as a Preference signup (404 CCASIGNUP\_NOT\_FOUND) and
> \
> must not be archived (409 RESOURCE\_ARCHIVED — unarchive one of its
> \
> groups first, which re-activates the signup). The day1 triple
> \
> (day1, day1StartTime, day1EndTime) is required; supplying the day2
> \
> triple adds a second weekly session. Day times are
> \
> organisation-local and are interpreted via the timeZone on the
> \
> response. costType is derived from cost and is ignored if sent.
> \
> joinRequestsOn defaults to true when omitted. The group always
> \
> starts unarchived.

```json
{"openapi":"3.0.1","info":{"title":"SchoolsBuddy Public API","version":"1.0"},"servers":[{"url":"https://publicapi-eu.schoolsbuddy.net","description":"EMEA Public Api server"},{"url":"https://publicapi-asia.schoolsbuddy.net","description":"Asia Public Api server"},{"url":"https://publicapi-us.schoolsbuddy.net","description":"US Public Api server"},{"url":"https://publicapi.schoolsbuddy.cn","description":"China Public Api server"},{"url":"https://identity-eu.schoolsbuddy.net","description":"EMEA Identity server"},{"url":"https://identity-asia.schoolsbuddy.net","description":"Asia Identity server"},{"url":"https://identity-us.schoolsbuddy.net","description":"US Identity server"},{"url":"https://accounts.schoolsbuddy.cn","description":"China Identity server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Type \"Bearer\" followed by a space and a token.","name":"Authorization","in":"header"}},"schemas":{"CreatePrefGroupRequestDto":{"required":["activityId","availableTo","day1","day1EndTime","day1StartTime","description","groupName","leadStaffId"],"type":"object","properties":{"groupName":{"maxLength":255,"minLength":1,"type":"string"},"description":{"minLength":1,"type":"string"},"groupCode":{"maxLength":50,"type":"string","nullable":true},"billingCode":{"maxLength":50,"type":"string","nullable":true},"leadStaffId":{"maximum":2147483647,"minimum":1,"type":"integer","format":"int32"},"activityId":{"maximum":2147483647,"minimum":1,"type":"integer","format":"int32"},"showInSportsPortal":{"type":"boolean","nullable":true},"locationId":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32","nullable":true},"informationOnly":{"type":"boolean","nullable":true},"day1":{"$ref":"#/components/schemas/DayOfWeekType"},"day1StartTime":{"type":"string","format":"partial-time"},"day1EndTime":{"type":"string","format":"partial-time"},"day2":{"$ref":"#/components/schemas/DayOfWeekType"},"day2StartTime":{"type":"string","format":"partial-time","nullable":true},"day2EndTime":{"type":"string","format":"partial-time","nullable":true},"maximumPlaces":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32","nullable":true},"minimumPlaces":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32","nullable":true},"cost":{"type":"number","format":"double","nullable":true},"joinRequestsOn":{"type":"boolean","nullable":true},"availableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"}},"preRequisite":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"notAvailableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"genderAvailableTo":{"$ref":"#/components/schemas/TeamGenderType"},"taxCode":{"maxLength":10,"type":"string","nullable":true},"shortName":{"maxLength":30,"type":"string","nullable":true}},"additionalProperties":false},"DayOfWeekType":{"enum":["Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"],"type":"string"},"CcaGroupReferenceDto":{"required":["type"],"type":"object","properties":{"id":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32"},"type":{"$ref":"#/components/schemas/CcaGroupReferenceType"}},"additionalProperties":false},"CcaGroupReferenceType":{"enum":["Group","Class","House","Year","SubjectClass"],"type":"string"},"TeamGenderType":{"enum":["Female","Male","Mixed"],"type":"string"},"PrefGroupResponseDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"organisationId":{"type":"integer","format":"int32"},"groupName":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"groupCode":{"type":"string","nullable":true},"billingCode":{"type":"string","nullable":true},"leadStaffId":{"type":"integer","format":"int32","nullable":true},"activityId":{"type":"integer","format":"int32","nullable":true},"showInSportsPortal":{"type":"boolean"},"locationId":{"type":"integer","format":"int32","nullable":true},"informationOnly":{"type":"boolean"},"day1":{"$ref":"#/components/schemas/DayOfWeekType"},"day1StartTime":{"type":"string","format":"partial-time","nullable":true},"day1EndTime":{"type":"string","format":"partial-time","nullable":true},"day2":{"$ref":"#/components/schemas/DayOfWeekType"},"day2StartTime":{"type":"string","format":"partial-time","nullable":true},"day2EndTime":{"type":"string","format":"partial-time","nullable":true},"maximumPlaces":{"type":"integer","format":"int32"},"minimumPlaces":{"type":"integer","format":"int32"},"cost":{"type":"number","format":"double"},"costType":{"$ref":"#/components/schemas/CcaCostTypeEnum"},"joinRequestsOn":{"type":"boolean","nullable":true},"availableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"preRequisite":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"notAvailableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"genderAvailableTo":{"$ref":"#/components/schemas/TeamGenderType"},"taxCode":{"type":"string","nullable":true},"shortName":{"type":"string","nullable":true},"isArchived":{"type":"boolean"},"timeZone":{"type":"string","nullable":true},"createdAtUtc":{"type":"string","format":"date-time","nullable":true},"updatedAtUtc":{"type":"string","format":"date-time"}},"additionalProperties":false},"CcaCostTypeEnum":{"enum":["FreeOfCharge","PerTermOrSeason","PerSession","OneOff"],"type":"string"},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`,\r\n`INTERNAL_ERROR`) per cross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"Structured body for 4xx / 5xx responses on the new Public API surface:\r\na machine-readable SchoolsBuddy.PublicAPI.Models.ErrorResponse.Code plus a human-readable\r\nSchoolsBuddy.PublicAPI.Models.ErrorResponse.Error. See cross-cutting-design.md §5.3. This is additive —\r\nexisting endpoints continue returning their legacy plain-string /\r\nModelState shapes until migrated by their per-controller ticket."}}},"paths":{"/api/v1/CcaSignUp/Pref/{id}/groups":{"post":{"tags":["Pref"],"summary":"Creates a child group under a Preference signup. The parent signup\r\nmust exist as a Preference signup (404 CCASIGNUP_NOT_FOUND) and\r\nmust not be archived (409 RESOURCE_ARCHIVED — unarchive one of its\r\ngroups first, which re-activates the signup). The day1 triple\r\n(day1, day1StartTime, day1EndTime) is required; supplying the day2\r\ntriple adds a second weekly session. Day times are\r\norganisation-local and are interpreted via the timeZone on the\r\nresponse. costType is derived from cost and is ignored if sent.\r\njoinRequestsOn defaults to true when omitted. The group always\r\nstarts unarchived.","parameters":[{"name":"id","in":"path","description":"The parent signup id (CcaSignUp.CcaSignUpId)","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"organisationId","in":"query","description":"The organisation the signup belongs to — required when the client has access to multiple organisations","schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The create request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePrefGroupRequestDto"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrefGroupResponseDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## PUT /api/v1/CcaSignUp/Pref/{id}/groups/{groupId}

> Partially updates a child group under a Preference signup — omitted
> \
> fields preserve their existing values (§3.7e). Each day triple is
> \
> atomic: send all three of its fields to change that session, or
> \
> none to leave it as it is (omitting them does not clear the
> \
> session). cost re-derives costType only when it is present and
> \
> non-null. For the availableTo / preRequisite / notAvailableTo lists
> \
> an omitted field preserves the stored set while an empty array
> \
> clears it. Setting isArchived = true archives the group — rejected
> \
> with 409 CCASIGNUP\_ARCHIVE\_BLOCKED\_ACTIVE while the group has
> \
> future events; archiving the LAST live group also archives the
> \
> signup. Sending isArchived = false unarchives an archived group
> \
> (EC-1 as amended 2026-07-31, never blocked) and re-activates an
> \
> archived signup — subject to the signup's NAME\_NOT\_UNIQUE
> \
> unarchive-into-collision guard; any other write against an archived
> \
> group returns 409 RESOURCE\_ARCHIVED.

```json
{"openapi":"3.0.1","info":{"title":"SchoolsBuddy Public API","version":"1.0"},"servers":[{"url":"https://publicapi-eu.schoolsbuddy.net","description":"EMEA Public Api server"},{"url":"https://publicapi-asia.schoolsbuddy.net","description":"Asia Public Api server"},{"url":"https://publicapi-us.schoolsbuddy.net","description":"US Public Api server"},{"url":"https://publicapi.schoolsbuddy.cn","description":"China Public Api server"},{"url":"https://identity-eu.schoolsbuddy.net","description":"EMEA Identity server"},{"url":"https://identity-asia.schoolsbuddy.net","description":"Asia Identity server"},{"url":"https://identity-us.schoolsbuddy.net","description":"US Identity server"},{"url":"https://accounts.schoolsbuddy.cn","description":"China Identity server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Type \"Bearer\" followed by a space and a token.","name":"Authorization","in":"header"}},"schemas":{"UpdatePrefGroupRequestDto":{"type":"object","properties":{"groupName":{"maxLength":255,"type":"string","nullable":true},"description":{"type":"string","nullable":true},"groupCode":{"maxLength":50,"type":"string","nullable":true},"billingCode":{"maxLength":50,"type":"string","nullable":true},"leadStaffId":{"type":"integer","format":"int32","nullable":true},"activityId":{"type":"integer","format":"int32","nullable":true},"showInSportsPortal":{"type":"boolean","nullable":true},"locationId":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32","nullable":true},"informationOnly":{"type":"boolean","nullable":true},"day1":{"$ref":"#/components/schemas/DayOfWeekType"},"day1StartTime":{"type":"string","format":"partial-time","nullable":true},"day1EndTime":{"type":"string","format":"partial-time","nullable":true},"day2":{"$ref":"#/components/schemas/DayOfWeekType"},"day2StartTime":{"type":"string","format":"partial-time","nullable":true},"day2EndTime":{"type":"string","format":"partial-time","nullable":true},"maximumPlaces":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32","nullable":true},"minimumPlaces":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32","nullable":true},"cost":{"type":"number","format":"double","nullable":true},"joinRequestsOn":{"type":"boolean","nullable":true},"availableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"preRequisite":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"notAvailableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"genderAvailableTo":{"$ref":"#/components/schemas/TeamGenderType"},"taxCode":{"maxLength":10,"type":"string","nullable":true},"shortName":{"maxLength":30,"type":"string","nullable":true},"isArchived":{"type":"boolean","nullable":true}},"additionalProperties":false},"DayOfWeekType":{"enum":["Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"],"type":"string"},"CcaGroupReferenceDto":{"required":["type"],"type":"object","properties":{"id":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32"},"type":{"$ref":"#/components/schemas/CcaGroupReferenceType"}},"additionalProperties":false},"CcaGroupReferenceType":{"enum":["Group","Class","House","Year","SubjectClass"],"type":"string"},"TeamGenderType":{"enum":["Female","Male","Mixed"],"type":"string"},"PrefGroupResponseDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"organisationId":{"type":"integer","format":"int32"},"groupName":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"groupCode":{"type":"string","nullable":true},"billingCode":{"type":"string","nullable":true},"leadStaffId":{"type":"integer","format":"int32","nullable":true},"activityId":{"type":"integer","format":"int32","nullable":true},"showInSportsPortal":{"type":"boolean"},"locationId":{"type":"integer","format":"int32","nullable":true},"informationOnly":{"type":"boolean"},"day1":{"$ref":"#/components/schemas/DayOfWeekType"},"day1StartTime":{"type":"string","format":"partial-time","nullable":true},"day1EndTime":{"type":"string","format":"partial-time","nullable":true},"day2":{"$ref":"#/components/schemas/DayOfWeekType"},"day2StartTime":{"type":"string","format":"partial-time","nullable":true},"day2EndTime":{"type":"string","format":"partial-time","nullable":true},"maximumPlaces":{"type":"integer","format":"int32"},"minimumPlaces":{"type":"integer","format":"int32"},"cost":{"type":"number","format":"double"},"costType":{"$ref":"#/components/schemas/CcaCostTypeEnum"},"joinRequestsOn":{"type":"boolean","nullable":true},"availableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"preRequisite":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"notAvailableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"genderAvailableTo":{"$ref":"#/components/schemas/TeamGenderType"},"taxCode":{"type":"string","nullable":true},"shortName":{"type":"string","nullable":true},"isArchived":{"type":"boolean"},"timeZone":{"type":"string","nullable":true},"createdAtUtc":{"type":"string","format":"date-time","nullable":true},"updatedAtUtc":{"type":"string","format":"date-time"}},"additionalProperties":false},"CcaCostTypeEnum":{"enum":["FreeOfCharge","PerTermOrSeason","PerSession","OneOff"],"type":"string"},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`,\r\n`INTERNAL_ERROR`) per cross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"Structured body for 4xx / 5xx responses on the new Public API surface:\r\na machine-readable SchoolsBuddy.PublicAPI.Models.ErrorResponse.Code plus a human-readable\r\nSchoolsBuddy.PublicAPI.Models.ErrorResponse.Error. See cross-cutting-design.md §5.3. This is additive —\r\nexisting endpoints continue returning their legacy plain-string /\r\nModelState shapes until migrated by their per-controller ticket."}}},"paths":{"/api/v1/CcaSignUp/Pref/{id}/groups/{groupId}":{"put":{"tags":["Pref"],"summary":"Partially updates a child group under a Preference signup — omitted\r\nfields preserve their existing values (§3.7e). Each day triple is\r\natomic: send all three of its fields to change that session, or\r\nnone to leave it as it is (omitting them does not clear the\r\nsession). cost re-derives costType only when it is present and\r\nnon-null. For the availableTo / preRequisite / notAvailableTo lists\r\nan omitted field preserves the stored set while an empty array\r\nclears it. Setting isArchived = true archives the group — rejected\r\nwith 409 CCASIGNUP_ARCHIVE_BLOCKED_ACTIVE while the group has\r\nfuture events; archiving the LAST live group also archives the\r\nsignup. Sending isArchived = false unarchives an archived group\r\n(EC-1 as amended 2026-07-31, never blocked) and re-activates an\r\narchived signup — subject to the signup's NAME_NOT_UNIQUE\r\nunarchive-into-collision guard; any other write against an archived\r\ngroup returns 409 RESOURCE_ARCHIVED.","parameters":[{"name":"id","in":"path","description":"The parent signup id (CcaSignUp.CcaSignUpId)","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"groupId","in":"path","description":"The child group id (Team.Id)","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"organisationId","in":"query","description":"The organisation the signup belongs to — required when the client has access to multiple organisations","schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The update request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePrefGroupRequestDto"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrefGroupResponseDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## POST /api/v1/CcaSignUp/Pref/{id}/groups/BulkCreate

> Creates child groups under a Preference signup in bulk. The parent
> \
> signup gates the whole request (validated before any per-item
> \
> work); items are then processed independently.

```json
{"openapi":"3.0.1","info":{"title":"SchoolsBuddy Public API","version":"1.0"},"servers":[{"url":"https://publicapi-eu.schoolsbuddy.net","description":"EMEA Public Api server"},{"url":"https://publicapi-asia.schoolsbuddy.net","description":"Asia Public Api server"},{"url":"https://publicapi-us.schoolsbuddy.net","description":"US Public Api server"},{"url":"https://publicapi.schoolsbuddy.cn","description":"China Public Api server"},{"url":"https://identity-eu.schoolsbuddy.net","description":"EMEA Identity server"},{"url":"https://identity-asia.schoolsbuddy.net","description":"Asia Identity server"},{"url":"https://identity-us.schoolsbuddy.net","description":"US Identity server"},{"url":"https://accounts.schoolsbuddy.cn","description":"China Identity server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Type \"Bearer\" followed by a space and a token.","name":"Authorization","in":"header"}},"schemas":{"BulkCreatePrefGroupRequestDto":{"type":"object","properties":{"organisationId":{"type":"integer","description":"Gets or sets the organisation the batch operates on. Optional\r\nwhen the calling client has access to a single organisation;\r\nrequired for multi-org clients.","format":"int32","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/BulkCreatePrefGroupItemDto"},"description":"Gets or sets the child groups to create. Each item is processed\r\nindependently; one failure does not roll back the others.\r\nItem-level validation deliberately bypasses automatic model\r\nvalidation — violations surface per item in failedItems[]\r\n(cross-cutting §6.1).","nullable":true}},"additionalProperties":false,"description":"Request body for POST /api/v1/CcaSignUp/Pref/{id}/groups/BulkCreate\r\n(SB-15666). The parent signup id in the URL gates the whole request\r\n(CCASIGNUP_NOT_FOUND, validated before any per-item work — closes\r\nSB-15244 / SB-15245)."},"BulkCreatePrefGroupItemDto":{"required":["activityId","availableTo","day1","day1EndTime","day1StartTime","description","groupName","leadStaffId"],"type":"object","properties":{"groupName":{"maxLength":255,"minLength":1,"type":"string"},"description":{"minLength":1,"type":"string"},"groupCode":{"maxLength":50,"type":"string","nullable":true},"billingCode":{"maxLength":50,"type":"string","nullable":true},"leadStaffId":{"maximum":2147483647,"minimum":1,"type":"integer","format":"int32"},"activityId":{"maximum":2147483647,"minimum":1,"type":"integer","format":"int32"},"showInSportsPortal":{"type":"boolean","nullable":true},"locationId":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32","nullable":true},"informationOnly":{"type":"boolean","nullable":true},"day1":{"$ref":"#/components/schemas/DayOfWeekType"},"day1StartTime":{"type":"string","format":"partial-time"},"day1EndTime":{"type":"string","format":"partial-time"},"day2":{"$ref":"#/components/schemas/DayOfWeekType"},"day2StartTime":{"type":"string","format":"partial-time","nullable":true},"day2EndTime":{"type":"string","format":"partial-time","nullable":true},"maximumPlaces":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32","nullable":true},"minimumPlaces":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32","nullable":true},"cost":{"type":"number","format":"double","nullable":true},"joinRequestsOn":{"type":"boolean","nullable":true},"availableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"}},"preRequisite":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"notAvailableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"genderAvailableTo":{"$ref":"#/components/schemas/TeamGenderType"},"taxCode":{"maxLength":10,"type":"string","nullable":true},"shortName":{"maxLength":30,"type":"string","nullable":true},"clientReferenceId":{"maxLength":100,"type":"string","nullable":true}},"additionalProperties":false},"DayOfWeekType":{"enum":["Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"],"type":"string"},"CcaGroupReferenceDto":{"required":["type"],"type":"object","properties":{"id":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32"},"type":{"$ref":"#/components/schemas/CcaGroupReferenceType"}},"additionalProperties":false},"CcaGroupReferenceType":{"enum":["Group","Class","House","Year","SubjectClass"],"type":"string"},"TeamGenderType":{"enum":["Female","Male","Mixed"],"type":"string"},"Int32BulkOperationResult":{"type":"object","properties":{"successfulIds":{"type":"array","items":{"type":"integer","format":"int32"},"description":"Gets or sets the ids of the items that were processed successfully.\r\nOn BulkCreate these are the newly-created ids.","nullable":true},"failedItems":{"type":"array","items":{"$ref":"#/components/schemas/BulkFailedItem"},"description":"Gets or sets the per-item failures, each carrying its request index,\r\noptional client reference, name, machine-readable code, and message.","nullable":true},"totalRequested":{"type":"integer","description":"Gets or sets the total number of items in the request. Set by the\r\ncaller (it is not derivable from the success/failure lists alone —\r\nitems rejected before per-item processing may appear in neither).","format":"int32"},"totalSuccessful":{"type":"integer","description":"Gets the number of items processed successfully (computed).","format":"int32","readOnly":true},"totalFailed":{"type":"integer","description":"Gets the number of items that failed (computed).","format":"int32","readOnly":true}},"additionalProperties":false,"description":"Standard envelope returned by every Public API bulk endpoint\r\n(BulkCreate / BulkUpdate / BulkArchive). Each item in the request is\r\nprocessed independently — one item failing does not roll back the\r\nothers — and the envelope reports per-item outcome. See\r\ncross-cutting-design.md §4."},"BulkFailedItem":{"type":"object","properties":{"index":{"type":"integer","description":"Gets or sets the zero-based index of the failed item within the\r\nrequest array, so callers keeping request order can map it back.","format":"int32"},"clientReferenceId":{"type":"string","description":"Gets or sets the optional opaque client-supplied reference echoed\r\nback from the request item. Null when the caller did not supply one.","nullable":true},"name":{"type":"string","description":"Gets or sets the name of the entity the failed item referred to,\r\nfor at-a-glance identification in the response.","nullable":true},"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `GROUP_IMPORTED_READ_ONLY`) per\r\ncross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"A single per-item failure entry in a SchoolsBuddy.PublicAPI.Models.BulkOperationResult`1\r\nenvelope. Mirrors the structured error body (cross-cutting-design.md §5.3):\r\na machine-readable SchoolsBuddy.PublicAPI.Models.BulkFailedItem.Code plus a human-readable SchoolsBuddy.PublicAPI.Models.BulkFailedItem.Error."},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`,\r\n`INTERNAL_ERROR`) per cross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"Structured body for 4xx / 5xx responses on the new Public API surface:\r\na machine-readable SchoolsBuddy.PublicAPI.Models.ErrorResponse.Code plus a human-readable\r\nSchoolsBuddy.PublicAPI.Models.ErrorResponse.Error. See cross-cutting-design.md §5.3. This is additive —\r\nexisting endpoints continue returning their legacy plain-string /\r\nModelState shapes until migrated by their per-controller ticket."}}},"paths":{"/api/v1/CcaSignUp/Pref/{id}/groups/BulkCreate":{"post":{"tags":["Pref"],"summary":"Creates child groups under a Preference signup in bulk. The parent\r\nsignup gates the whole request (validated before any per-item\r\nwork); items are then processed independently.","parameters":[{"name":"id","in":"path","description":"The parent signup id (CcaSignUp.CcaSignUpId)","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The bulk create envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCreatePrefGroupRequestDto"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Int32BulkOperationResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## PUT /api/v1/CcaSignUp/Pref/{id}/groups/BulkUpdate

> Partially updates child groups under a Preference signup in bulk.
> \
> The parent signup gates the whole request (validated before any
> \
> per-item work); each item carries the target group id and items are
> \
> processed independently. Day-triple, cost and archive semantics per
> \
> item match the single-resource PUT.

```json
{"openapi":"3.0.1","info":{"title":"SchoolsBuddy Public API","version":"1.0"},"servers":[{"url":"https://publicapi-eu.schoolsbuddy.net","description":"EMEA Public Api server"},{"url":"https://publicapi-asia.schoolsbuddy.net","description":"Asia Public Api server"},{"url":"https://publicapi-us.schoolsbuddy.net","description":"US Public Api server"},{"url":"https://publicapi.schoolsbuddy.cn","description":"China Public Api server"},{"url":"https://identity-eu.schoolsbuddy.net","description":"EMEA Identity server"},{"url":"https://identity-asia.schoolsbuddy.net","description":"Asia Identity server"},{"url":"https://identity-us.schoolsbuddy.net","description":"US Identity server"},{"url":"https://accounts.schoolsbuddy.cn","description":"China Identity server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Type \"Bearer\" followed by a space and a token.","name":"Authorization","in":"header"}},"schemas":{"BulkUpdatePrefGroupRequestDto":{"type":"object","properties":{"organisationId":{"type":"integer","description":"Gets or sets the organisation the batch operates on. Optional\r\nwhen the calling client has access to a single organisation;\r\nrequired for multi-org clients.","format":"int32","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/BulkUpdatePrefGroupItemDto"},"description":"Gets or sets the child groups to update. Each item is processed\r\nindependently; one failure does not roll back the others.\r\nItem-level validation deliberately bypasses automatic model\r\nvalidation — violations surface per item in failedItems[]\r\n(cross-cutting §6.1).","nullable":true}},"additionalProperties":false,"description":"Request body for PUT /api/v1/CcaSignUp/Pref/{id}/groups/BulkUpdate\r\n(SB-15666). The parent signup id in the URL gates the whole request\r\n(CCASIGNUP_NOT_FOUND, validated before any per-item work); each item\r\ncarries its target group Id (EC-7)."},"BulkUpdatePrefGroupItemDto":{"type":"object","properties":{"groupName":{"maxLength":255,"type":"string","nullable":true},"description":{"type":"string","nullable":true},"groupCode":{"maxLength":50,"type":"string","nullable":true},"billingCode":{"maxLength":50,"type":"string","nullable":true},"leadStaffId":{"type":"integer","format":"int32","nullable":true},"activityId":{"type":"integer","format":"int32","nullable":true},"showInSportsPortal":{"type":"boolean","nullable":true},"locationId":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32","nullable":true},"informationOnly":{"type":"boolean","nullable":true},"day1":{"$ref":"#/components/schemas/DayOfWeekType"},"day1StartTime":{"type":"string","format":"partial-time","nullable":true},"day1EndTime":{"type":"string","format":"partial-time","nullable":true},"day2":{"$ref":"#/components/schemas/DayOfWeekType"},"day2StartTime":{"type":"string","format":"partial-time","nullable":true},"day2EndTime":{"type":"string","format":"partial-time","nullable":true},"maximumPlaces":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32","nullable":true},"minimumPlaces":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32","nullable":true},"cost":{"type":"number","format":"double","nullable":true},"joinRequestsOn":{"type":"boolean","nullable":true},"availableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"preRequisite":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"notAvailableTo":{"type":"array","items":{"$ref":"#/components/schemas/CcaGroupReferenceDto"},"nullable":true},"genderAvailableTo":{"$ref":"#/components/schemas/TeamGenderType"},"taxCode":{"maxLength":10,"type":"string","nullable":true},"shortName":{"maxLength":30,"type":"string","nullable":true},"isArchived":{"type":"boolean","nullable":true},"id":{"type":"integer","format":"int32","nullable":true},"clientReferenceId":{"maxLength":100,"type":"string","nullable":true}},"additionalProperties":false},"DayOfWeekType":{"enum":["Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"],"type":"string"},"CcaGroupReferenceDto":{"required":["type"],"type":"object","properties":{"id":{"maximum":2147483647,"minimum":0,"type":"integer","format":"int32"},"type":{"$ref":"#/components/schemas/CcaGroupReferenceType"}},"additionalProperties":false},"CcaGroupReferenceType":{"enum":["Group","Class","House","Year","SubjectClass"],"type":"string"},"TeamGenderType":{"enum":["Female","Male","Mixed"],"type":"string"},"Int32BulkOperationResult":{"type":"object","properties":{"successfulIds":{"type":"array","items":{"type":"integer","format":"int32"},"description":"Gets or sets the ids of the items that were processed successfully.\r\nOn BulkCreate these are the newly-created ids.","nullable":true},"failedItems":{"type":"array","items":{"$ref":"#/components/schemas/BulkFailedItem"},"description":"Gets or sets the per-item failures, each carrying its request index,\r\noptional client reference, name, machine-readable code, and message.","nullable":true},"totalRequested":{"type":"integer","description":"Gets or sets the total number of items in the request. Set by the\r\ncaller (it is not derivable from the success/failure lists alone —\r\nitems rejected before per-item processing may appear in neither).","format":"int32"},"totalSuccessful":{"type":"integer","description":"Gets the number of items processed successfully (computed).","format":"int32","readOnly":true},"totalFailed":{"type":"integer","description":"Gets the number of items that failed (computed).","format":"int32","readOnly":true}},"additionalProperties":false,"description":"Standard envelope returned by every Public API bulk endpoint\r\n(BulkCreate / BulkUpdate / BulkArchive). Each item in the request is\r\nprocessed independently — one item failing does not roll back the\r\nothers — and the envelope reports per-item outcome. See\r\ncross-cutting-design.md §4."},"BulkFailedItem":{"type":"object","properties":{"index":{"type":"integer","description":"Gets or sets the zero-based index of the failed item within the\r\nrequest array, so callers keeping request order can map it back.","format":"int32"},"clientReferenceId":{"type":"string","description":"Gets or sets the optional opaque client-supplied reference echoed\r\nback from the request item. Null when the caller did not supply one.","nullable":true},"name":{"type":"string","description":"Gets or sets the name of the entity the failed item referred to,\r\nfor at-a-glance identification in the response.","nullable":true},"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `GROUP_IMPORTED_READ_ONLY`) per\r\ncross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"A single per-item failure entry in a SchoolsBuddy.PublicAPI.Models.BulkOperationResult`1\r\nenvelope. Mirrors the structured error body (cross-cutting-design.md §5.3):\r\na machine-readable SchoolsBuddy.PublicAPI.Models.BulkFailedItem.Code plus a human-readable SchoolsBuddy.PublicAPI.Models.BulkFailedItem.Error."},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`,\r\n`INTERNAL_ERROR`) per cross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"Structured body for 4xx / 5xx responses on the new Public API surface:\r\na machine-readable SchoolsBuddy.PublicAPI.Models.ErrorResponse.Code plus a human-readable\r\nSchoolsBuddy.PublicAPI.Models.ErrorResponse.Error. See cross-cutting-design.md §5.3. This is additive —\r\nexisting endpoints continue returning their legacy plain-string /\r\nModelState shapes until migrated by their per-controller ticket."}}},"paths":{"/api/v1/CcaSignUp/Pref/{id}/groups/BulkUpdate":{"put":{"tags":["Pref"],"summary":"Partially updates child groups under a Preference signup in bulk.\r\nThe parent signup gates the whole request (validated before any\r\nper-item work); each item carries the target group id and items are\r\nprocessed independently. Day-triple, cost and archive semantics per\r\nitem match the single-resource PUT.","parameters":[{"name":"id","in":"path","description":"The parent signup id (CcaSignUp.CcaSignUpId)","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The bulk update envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpdatePrefGroupRequestDto"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Int32BulkOperationResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## POST /api/v1/CcaSignUp/Pref/{id}/groups/BulkArchive

> Archives or unarchives child groups under a Preference signup in
> \
> bulk (toggleable via the isArchived body flag). Archiving is
> \
> rejected per item (CCASIGNUP\_ARCHIVE\_BLOCKED\_ACTIVE) while a group
> \
> has future events; archiving the LAST live group also archives the
> \
> signup. Unarchiving is never blocked and re-activates an archived
> \
> signup — subject to the signup's NAME\_NOT\_UNIQUE
> \
> unarchive-into-collision guard. Alongside PUT / BulkUpdate items
> \
> carrying isArchived = false, the write verbs allowed against
> \
> already-archived groups (EC-1 as amended 2026-07-31).

```json
{"openapi":"3.0.1","info":{"title":"SchoolsBuddy Public API","version":"1.0"},"servers":[{"url":"https://publicapi-eu.schoolsbuddy.net","description":"EMEA Public Api server"},{"url":"https://publicapi-asia.schoolsbuddy.net","description":"Asia Public Api server"},{"url":"https://publicapi-us.schoolsbuddy.net","description":"US Public Api server"},{"url":"https://publicapi.schoolsbuddy.cn","description":"China Public Api server"},{"url":"https://identity-eu.schoolsbuddy.net","description":"EMEA Identity server"},{"url":"https://identity-asia.schoolsbuddy.net","description":"Asia Identity server"},{"url":"https://identity-us.schoolsbuddy.net","description":"US Identity server"},{"url":"https://accounts.schoolsbuddy.cn","description":"China Identity server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Type \"Bearer\" followed by a space and a token.","name":"Authorization","in":"header"}},"schemas":{"BulkArchivePrefGroupRequestDto":{"required":["ids"],"type":"object","properties":{"organisationId":{"type":"integer","description":"Gets or sets the organisation the batch operates on. Optional\r\nwhen the calling client has access to a single organisation;\r\nrequired for multi-org clients.","format":"int32","nullable":true},"ids":{"minItems":1,"type":"array","items":{"type":"integer","format":"int32"},"description":"Gets or sets the ids (Team.Id) of the child groups to transition.\r\nId validity is checked per item (EC-7) — 0 / negative ids fail\r\nthat item only."},"isArchived":{"type":"boolean","description":"Gets or sets a value indicating whether the groups are archived\r\n(true, default) or unarchived (false)."}},"additionalProperties":false,"description":"Request body for POST /api/v1/CcaSignUp/Pref/{id}/groups/BulkArchive\r\n(SB-15666, mirroring SB-15665 §10 C3). Toggleable: isArchived true\r\narchives each group (Team.StatusId = Archive) — blocked per item with\r\nCCASIGNUP_ARCHIVE_BLOCKED_ACTIVE while the group has future events\r\n(§10 D2); false unarchives (StatusId = Active, never blocked). The\r\ncontainer cascade runs per item: archiving the last live group\r\narchives the container (CcaSignUp.Status = 4); unarchiving any group\r\nre-activates it. The parent signup id in the URL gates the whole\r\nrequest (CCASIGNUP_NOT_FOUND, validated before any per-item work) —\r\nan ARCHIVED parent is allowed here, since unarchiving a group is the\r\ncontainer's recovery path (§10 D5)."},"Int32BulkOperationResult":{"type":"object","properties":{"successfulIds":{"type":"array","items":{"type":"integer","format":"int32"},"description":"Gets or sets the ids of the items that were processed successfully.\r\nOn BulkCreate these are the newly-created ids.","nullable":true},"failedItems":{"type":"array","items":{"$ref":"#/components/schemas/BulkFailedItem"},"description":"Gets or sets the per-item failures, each carrying its request index,\r\noptional client reference, name, machine-readable code, and message.","nullable":true},"totalRequested":{"type":"integer","description":"Gets or sets the total number of items in the request. Set by the\r\ncaller (it is not derivable from the success/failure lists alone —\r\nitems rejected before per-item processing may appear in neither).","format":"int32"},"totalSuccessful":{"type":"integer","description":"Gets the number of items processed successfully (computed).","format":"int32","readOnly":true},"totalFailed":{"type":"integer","description":"Gets the number of items that failed (computed).","format":"int32","readOnly":true}},"additionalProperties":false,"description":"Standard envelope returned by every Public API bulk endpoint\r\n(BulkCreate / BulkUpdate / BulkArchive). Each item in the request is\r\nprocessed independently — one item failing does not roll back the\r\nothers — and the envelope reports per-item outcome. See\r\ncross-cutting-design.md §4."},"BulkFailedItem":{"type":"object","properties":{"index":{"type":"integer","description":"Gets or sets the zero-based index of the failed item within the\r\nrequest array, so callers keeping request order can map it back.","format":"int32"},"clientReferenceId":{"type":"string","description":"Gets or sets the optional opaque client-supplied reference echoed\r\nback from the request item. Null when the caller did not supply one.","nullable":true},"name":{"type":"string","description":"Gets or sets the name of the entity the failed item referred to,\r\nfor at-a-glance identification in the response.","nullable":true},"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `GROUP_IMPORTED_READ_ONLY`) per\r\ncross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"A single per-item failure entry in a SchoolsBuddy.PublicAPI.Models.BulkOperationResult`1\r\nenvelope. Mirrors the structured error body (cross-cutting-design.md §5.3):\r\na machine-readable SchoolsBuddy.PublicAPI.Models.BulkFailedItem.Code plus a human-readable SchoolsBuddy.PublicAPI.Models.BulkFailedItem.Error."},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`,\r\n`INTERNAL_ERROR`) per cross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"Structured body for 4xx / 5xx responses on the new Public API surface:\r\na machine-readable SchoolsBuddy.PublicAPI.Models.ErrorResponse.Code plus a human-readable\r\nSchoolsBuddy.PublicAPI.Models.ErrorResponse.Error. See cross-cutting-design.md §5.3. This is additive —\r\nexisting endpoints continue returning their legacy plain-string /\r\nModelState shapes until migrated by their per-controller ticket."}}},"paths":{"/api/v1/CcaSignUp/Pref/{id}/groups/BulkArchive":{"post":{"tags":["Pref"],"summary":"Archives or unarchives child groups under a Preference signup in\r\nbulk (toggleable via the isArchived body flag). Archiving is\r\nrejected per item (CCASIGNUP_ARCHIVE_BLOCKED_ACTIVE) while a group\r\nhas future events; archiving the LAST live group also archives the\r\nsignup. Unarchiving is never blocked and re-activates an archived\r\nsignup — subject to the signup's NAME_NOT_UNIQUE\r\nunarchive-into-collision guard. Alongside PUT / BulkUpdate items\r\ncarrying isArchived = false, the write verbs allowed against\r\nalready-archived groups (EC-1 as amended 2026-07-31).","parameters":[{"name":"id","in":"path","description":"The parent signup id (CcaSignUp.CcaSignUpId)","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The bulk archive envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkArchivePrefGroupRequestDto"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Int32BulkOperationResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```