Search the companies of your school. This read-only operation uses POST to carry the filters in its body: credentials holding only read access are served.

Filters are combined with AND; the values of ids and of externalReferenceIds are combined with OR, up to 100 each, and references unknown to your school are ignored. Text filters are exact, except search, a literal substring of name, displayName or businessIdentifier. Date ranges are inclusive ISO-8601 instants. Sorts apply in array order, then by ID ascending.

includeStudents and includeExternals add the full, unpaginated students and externals arrays to each company: active people only; learners attached directly or through an apprenticeship contract, each once; external contacts counted once per email, the ones without an email left out. Learners are ordered by last name, first name, then ID; external contacts by last name, first name, then email. Each array is empty when nobody is attached. hasStudents and hasExternals follow the same rules: a company "has" exactly the people it would list.

Several learners and external contacts can be attached to one company, and a change to the company applies to all of them.

Attach a learner with companyId on PATCH /students/{id} (or its by-reference-id twin): it is the "Company" field of the learner record in the School app. That call also copies the company display name into the learner's historical company text; updating the company later does not rewrite that text.