Sends a survey template to students, groups, professors and external contacts, now or at a scheduled date, with an optional custom message shown in the invitation email. Each accepted request creates a new survey, readable through GET /surveys/:id, which copies the template's name, questions, anonymity and type as they are at send time.
Identifiers: the template, the training and each recipient type are given by Edusign id or by external reference, never both (400 *_IDENTIFIER_AMBIGUOUS). An external reference matching exactly one active person designates them; several active people → 409 *_EXTERNAL_REFERENCE_NOT_UNIQUE listing every such reference; archived people only → 409 *_ARCHIVED.
All-or-nothing: every recipient must exist in the school and be active. Recipients are checked in the order students, groups, professors, external contacts, and within each type unknown (404), then reference matching several people (409), then archived (409). Only the first failing check is returned, listing every offender of that type; nothing is created and nobody receives anything. A person listed more than once, directly or through groups, receives the survey once; groups are replaced by their active members at request time.
With a valid training (ID or external reference), recipients may be omitted, empty, or contain empty lists. No training participants are selected automatically. Without sendAt, this creates an unsent, unscheduled student questionnaire, with no answers or invitations (201, meta.type: "created", recipientsCount: 0). Recipient assignment and delivery are subsequent operations. Explicit nonempty selectors that resolve to nobody still fail.
With recipients and without sendAt the survey is created, marked as sent and every invitation is queued (200, meta.type: "sent"): the invitations go out in the background, each recipient getting their sent date and on_survey_sent webhook as their invitation goes out. Students and external contacts receive the student invitation email, professors the professor one; students also get the push and in-app notification. With sendAt (ISO 8601 with a timezone, strictly in the future) the survey is scheduled (202, meta.type: "scheduled") and sent at that instant like a scheduled send from the platform; if the scheduling service is unavailable the request fails with 502 SURVEY_SCHEDULING_FAILED and no survey is kept, so it is safe to retry. A sendAt no longer ahead once the send is registered is withdrawn and refused like a past one (400 SURVEY_SCHEDULED_DATE_IN_PAST), nothing kept either: send again, at once or later; when the withdrawal itself fails the request fails with the 502 above. For an initially empty training survey, this schedules delivery to recipients assigned by that instant; adding recipients after it does not create a new scheduled send.
A survey linked to a training that includes at least one student, or is created empty, follows the training enrolment options: a student enrolled later with "past surveys" set joins a sent survey and receives it at once, one enrolled with "future surveys" set joins a scheduled survey. An unscheduled training questionnaire is also selected by the existing "past surveys" option, which may send it when a student enrols; creation itself sends nothing. Recipients without an email address are accepted and counted: they are marked as sent without an email, as from the platform.
Each accepted request creates a survey. An identical request (same template, training, message, sendAt and resolved recipients) repeated within about 5 seconds of the first one (5 to 6 seconds: the creation time is stored to the second) receives the first response, with the same status, and sends nothing again; repeated later, it creates a second survey and repeats the requested operation. Two identical requests sent at the very same moment are absorbed on a best-effort basis, and a repeat that arrives while the first request is still queuing or scheduling its send receives its response even if that first request then fails. A request answered with an error (4xx, 502) kept no survey and can be sent again.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||

