SendPulse Students API

openapi: 3.2.0
info:
  description: This is the REST API endpoints definition for Education SendPulse project
  title: Education SendPulse Project API Definition Students API
  version: 1.0.0
servers:
- url: https://api.sendpulse.com/edu/public/v1
security:
- apiKey: []
- oauth2: []
tags:
- name: Students
paths:
  /students:
    post:
      tags:
      - Students
      summary: Create student
      requestBody:
        description: Payload to create a new student and enroll to a course/tariff.
        content:
          application/json:
            schema:
              properties:
                courseId:
                  type: integer
                  description: ID of the course to enroll the student in.
                email:
                  type: string
                  description: Student email address.
                firstName:
                  type: string
                  description: Student first name.
                lastName:
                  type: string
                  description: Student last name.
                tagIds:
                  type: array
                  description: List of tag IDs to assign to the student.
                  items:
                    type: integer
                language:
                  type: string
                  example: uk_UA
                  description: Preferred language/locale code (e.g., uk_UA).
                courseTariffId:
                  type: integer
                  description: ID of the course tariff to enroll the student on.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Student'
      operationId: createStudent
      x-ai-role: online_education_enrollment_specialist
      x-ai-description: Initializes a student account and simultaneously enrolls them into a specific course or tariff tier. This is the primary onboarding entry point in SendPulse Edu — it creates the learner identity and binds it to a course in a single atomic operation. The tariff determines access scope, content availability, and billing logic for the student.
      x-ai-reasoning-instructions:
      - Verify that the courseId exists and is active before attempting enrollment.
      - If courseTariffId is provided, confirm it belongs to the specified courseId — mismatched tariff/course pairs will fail silently or cause inconsistent enrollment state.
      - Check whether a student with the same email is already enrolled in the course to avoid duplicate records.
      - tagIds are optional but recommended for segmentation — suggest relevant tags if the caller has context about the student's origin or segment.
      - Language/locale (e.g., uk_UA) affects notification templates sent to the student — confirm the locale is supported if the user specifies one.
      x-ai-responding-instructions:
      - Confirm successful creation by surfacing the new student ID from the response.
      - Mention which course and tariff the student was enrolled into.
      - If enrollment fails due to duplicate email, suggest using an update or re-enrollment endpoint instead.
      - Suggest next steps such as sending a welcome email or assigning additional courses.
      x-ai-suggestions:
      - Use courseId + courseTariffId together for paid or tiered course access.
      - After creation, trigger a welcome notification via the SendPulse Automation or Email API.
      - Assign tagIds at creation time to enable targeted communication segments from the start.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - PersonalDataWrite
          - ResourceStateUpdate
  /students/auditory:
    post:
      tags:
      - Students
      summary: Get auditory
      requestBody:
        description: Filters to search and paginate the auditory list.
        content:
          application/json:
            schema:
              properties:
                offset:
                  type: integer
                  description: Pagination offset (number of records to skip).
                limit:
                  type: integer
                  description: Pagination limit (maximum number of records to return).
                tags:
                  type: array
                  description: Filter by tag IDs assigned to students.
                  items:
                    type: integer
                firstName:
                  type: string
                  description: Filter by student first name (substring match).
                lastName:
                  type: string
                  description: Filter by student last name (substring match).
                email:
                  type: string
                  description: Filter by email address (substring match).
                courseStatus:
                  type: array
                  description: Filter by student status on courses.
                  items:
                    type: string
                    enum:
                    - registered
                    - inProgress
                    - success
                    - failed
                    - certificated
                orderBy:
                  type: string
                  description: Field to sort by.
                  enum:
                  - firstName
                  - studentStatusOnCourse
                  - studentTest
                  - studentDateRegistrationOnCourse
                sort:
                  type: string
                  description: Sort direction.
                  enum:
                  - asc
                  - desc
                isPaid:
                  type: boolean
                  description: Filter by whether the student has paid for at least one course.
                dateRegistrationOnCourse:
                  type:
                  - object
                  - 'null'
                  description: Date range filter for the date of registration on a course.
                  properties:
                    dateFrom:
                      type: string
                      format: date
                      description: Start date (inclusive) in YYYY-MM-DD format.
                    dateTo:
                      type: string
                      format: date
                      description: End date (inclusive) in YYYY-MM-DD format.
                dateLastEntry:
                  type:
                  - object
                  - 'null'
                  description: Date range filter for the last entry/login date.
                  properties:
                    dateFrom:
                      type: string
                      format: date
                      description: Start date (inclusive) in YYYY-MM-DD format.
                    dateTo:
                      type: string
                      format: date
                      description: End date (inclusive) in YYYY-MM-DD format.
                promoCodeIds:
                  type: array
                  description: Filter by promo code IDs used by students.
                  items:
                    type: integer
                usedPromoCode:
                  type:
                  - boolean
                  - 'null'
                  description: Filter by whether any promo code was used.
                searchString:
                  type: string
                  description: Free-text search across student attributes (name, email, etc.).
                courseId:
                  type: integer
                  description: Filter by a specific course ID.
                courseRestrictions:
                  type: string
                  description: Filter by course access restriction type.
                  enum:
                  - none
                  - open
                  - closed
                paidCoursesCondition:
                  type: string
                  description: Comparison operator to apply to paidCoursesValue.
                  enum:
                  - '='
                  - '>='
                  - <=
                paidCoursesValue:
                  type: integer
                  description: Numeric value used with paidCoursesCondition to filter by the number of paid courses.
              required:
              - offset
              - limit
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    description: Auditory search results (list of students matching filters).
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Student ID.
                        uuid:
                          type: string
                          description: Unique student UUID.
                        email:
                          type: string
                          description: Student email address.
                        domainId:
                          type: integer
                          description: Domain ID the student belongs to.
                        schoolId:
                          type: integer
                          description: School ID the student belongs to.
                        firstName:
                          type: string
                          description: Student first name.
                        lastName:
                          type: string
                          description: Student last name.
                        contactFirstName:
                          type:
                          - string
                          - 'null'
                          description: Contact first name (nullable).
                        contactLastName:
                          type:
                          - string
                          - 'null'
                          description: Contact last name (nullable).
                        status:
                          type: string
                          description: Overall student status.
                        responsibleId:
                          type: integer
                          description: User ID.
                        tags:
                          type: array
                          description: List of tag IDs assigned to the student.
                          items:
                            type: integer
                        language:
                          type: string
                          description: Preferred language/locale code (e.g., uk_UA).
                        avatar:
                          type:
                          - string
                          - 'null'
                          description: URL to the student's avatar image.
                        courses:
                          type: array
                          description: List of courses associated with the student in the search results.
                          items:
                            type: object
                            properties:
                              courseId:
                                type: integer
                                description: Course ID.
                              courseName:
                                type: string
                                description: Course name.
                              coverImage:
                                type:
                                - string
                                - 'null'
                                description: Course cover image URL.
                              studentStatus:
                                type: string
                                description: Student status on this course.
                              paymentStatus:
                                type:
                                - string
                                - 'null'
                                description: Payment status for this course.
                              promoCode:
                                type:
                                - string
                                - 'null'
                                description: Applied promo code (if any).
                              discount:
                                type:
                                - integer
                                - 'null'
                                description: Discount value applied for this course.
                              studentDateRegistrationOnCourse:
                                type: string
                                format: date-time
                                description: Registration date and time on this course.
                              studentLastEntry:
                                type: string
                                format: date-time
                                description: Last entry date and time on this course.
                              courseAvailableDate:
                                type:
                                - string
                                - 'null'
                                format: date-time
                                description: Date when the course becomes available to the student.
                              hasPaidTariff:
                                type: boolean
                                description: Whether the student has a paid tariff for this course.
                              courseTariffId:
                                type:
                                - integer
                                - 'null'
                                description: Tariff ID for the course (nullable).
                              courseTariffName:
                                type:
                                - string
                                - 'null'
                                description: Tariff name for the course (nullable).
                              studentTariffStatus:
                                type:
                                - string
                                - 'null'
                                description: Student's tariff status for the course (nullable).
                  meta:
                    type: object
                    description: Additional metadata for the auditory results.
                    properties:
                      searchString:
                        type: string
                        description: Echo of the search string used to filter results (if provided).
                      total:
                        type: integer
                        description: Total number of matching records across all pages.
      operationId: getStudentsAuditory
      x-ai-role: lms_audience_analyst
      x-ai-description: Retrieves a filtered, paginated snapshot of the student audience (auditory) for a school. This is the primary segmentation endpoint in the LMS — it combines demographic filters, course progress states, payment conditions, and temporal ranges into a single query. Use it to build targeted cohorts for re-engagement campaigns, certificate tracking, promo effectiveness analysis, or course performance reports.
      x-ai-reasoning-instructions:
      - 'Always require `offset` and `limit` in the request — they are mandatory. Start with `offset: 0` and a reasonable `limit` (e.g., 50) unless the user specifies otherwise.'
      - When filtering by `courseStatus`, note that multiple statuses can be combined — e.g., ['failed', 'inProgress'] to find at-risk students.
      - Prefer `searchString` for broad free-text queries; use specific fields like `firstName`, `lastName`, `email` only when the user targets a known attribute.
      - When filtering by payment, combine `isPaid` with `paidCoursesCondition` + `paidCoursesValue` for precise numeric queries (e.g., students with 2+ paid courses).
      - Date filters (`dateRegistrationOnCourse`, `dateLastEntry`) use inclusive YYYY-MM-DD ranges — verify both `dateFrom` and `dateTo` are provided when using these filters.
      - If `courseId` is provided, results are scoped to that course's enrollment data; `courseStatus` then applies within that course context.
      - Use `meta.total` from the response to determine if pagination is needed — if `total > offset + limit`, more pages exist.
      x-ai-responding-instructions:
      - Report the total number of matching students from `meta.total`, not just the count of items returned on the current page.
      - When presenting results, highlight the student's name, email, and course statuses as the primary identifiers.
      - If the result set is empty, suggest relaxing filters — e.g., removing `courseStatus` restrictions or widening date ranges.
      - For large result sets (total > 100), remind the user to paginate using `offset` increments of `limit`.
      - When course data is included per student, summarize the most relevant course (e.g., the one matching the applied `courseId` filter) rather than listing all courses.
      x-ai-suggestions:
      - 'Find all students currently in progress: set `courseStatus: [''inProgress'']`'
      - 'Find paying students who used a promo: combine `isPaid: true` with `usedPromoCode: true`'
      - 'Find recently registered students: use `dateRegistrationOnCourse` with a recent date range'
      - 'Find inactive students: use `dateLastEntry` with an old date range to identify those who haven''t logged in recently'
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
          - ReadOnly
          - ContainsPersonalData
  /students/course-statistics/{studentId}:
    get:
      tags:
      - Students
      summary: Get students course statistic
      parameters:
      - name: studentId
        in: path
        required: true
        description: Student identifier.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: object
                    properties:
                      schools:
                        type: array
                        description: List of schools associated with the student's courses
                        items:
                          type: object
                          properties:
                            schoolId:
                              type: integer
                              description: Identifier of the school
                            schoolName:
                              type: string
                              description: Name of the school
                            isLms:
                              type: boolean
                              description: Indicates whether the school is a Learning Management System
                            courses:
                              type: array
                              description: List of courses the student is enrolled in at this school
                              items:
                                type: object
                                properties:
                                  id:
                                    type: integer
                                    description: Identifier of the course
                                  status:
                                    type: string
                                    description: Current status of the course
                                    enum:
                                    - blocked
                                    - inProgress
                                    - inactive
                                  name:
                                    type: string
                                    description: Name of the course
                                  statusStudentOnCourse:
                                    type: string
                                    description: Student's current status in the course
                                    enum:
                                    - unPaid
                                    - registered
                                    - inProgress
                                    - paid
                                    - success
                                    - failed
                                    - certificated
                                    - deletedFromCourse
                                    - invited
                                  studentDateRegistrationOnCourse:
                                    type: string
                                    format: date-time
                                    description: Date and time when the student registered for the course
                                  studentEmail:
                                    type: string
                                    description: Email address of the student
                                  studentLastEntry:
                                    type: string
                                    format: date-time
                                    description: Date and time of student's last access to the course
                                  courseAvailableDate:
                                    type: string
                                    format: date-time
                                    description: Date and time when the course becomes available to the student
                                  studentMetadata:
                                    type: object
                                    description: Additional metadata related to the student in the context of this course
                                  landingUrl:
                                    type: string
                                    description: URL of the course landing page
                                  feedback:
                                    type:
                                    - object
                                    - 'null'
                                    description: Student's feedback for the course
                                    properties:
                                      rate:
                                        type: integer
                                        description: Rating given by the student (typically 1-5)
                                      message:
                                        type: string
                                        description: Feedback message from the student
                                      date:
                                        type: string
                                        format: date-time
                                        description: Date and time when feedback was submitted
                                  sections:
                                    type: array
                                    description: List of course sections
                                    items:
                                      type: object
                                      properties:
                                        id:
                                          type: integer
                                          description: Identifier of the section
                                        name:
                                          type: string
                                          description: Name of the section
                                        order:
                                          type: integer
                                          description: Order of the section within the course
                                        status:
                                          type: string
                                          description: Current status of the section
                                          enum:
                                          - closed
                                          - opened
                                          - deleted
                                          - planned
                                        lessons:
                                          type: array
                                          description: List of lessons in the section
                                          items:
                                            type: object
                                            properties:
                                              id:
                                                type: integer
                                                description: Identifier of the lesson
                                              name:
                                                type: string
                                                description: Name of the lesson
                                              statusStudentOnLesson:
                                                type: object
                                                description: Student's progress status for this lesson
                                                properties:
                                                  status:
                                                    type: string
                                                    description: Current status of the student in the lesson
                                                    enum:
                                                    - doNotStarted
                                                    - started
                                                    - completed
                                                  updatedAt:
                                                    type: string
                                                    description: Last update time of the student's lesson status
                                              status:
                                                type: string
                                                description: Current status of the lesson
                                                enum:
                                                - closed
                                                - opened
                                                - deleted
                                                - planned
                                              feedback:
                                                type:
                                                - object
                                                - 'null'
                                                description: Student's feedback for the lesson
                                                properties:
                                                  rate:
                                                    type: integer
                                                    description: Rating given by the student for the lesson
                                                  message:
                                                    type: string
                                                    description: Feedback message for the lesson
                                                  date:
                                                    type: string
                                                    format: date-time
                                                    description: Date and time when lesson feedback was submitted
                                        certificateSections:
                                          type: array
                                          description: List of certificate sections in the course
                                          items:
                                            properties:
                                              id:
                                                type: integer
                                                description: Identifier of the certificate section
                                              name:
                                                type: string
                                                description: Name of the certificate section
                                              sectionId:
                                                type: integer
                                                description: Identifier of the associated section
                                              order:
                                                type: integer
                                                description: Order of the certificate section within the course
                                              dateReceived:
                                                type: string
                                                format: date-time
                                                description: Date and time when the certificate section was received
                                              status:
                                                type: string
                                                description: Current status of the certificate section
                                                enum:
                                                - active
                                                - inactive
                                                - planned
                                                - hidden
                                              questionsCount:
                                                type: integer
                                                description: Number of questions in the certificate section
                                              answeredQuestionsCount:
                                                type: integer
                                                description: Number of questions answered by the student in the certificate section
                                              studentStatus:
                                                type: string
                                                description: Current status of the student in the certificate section
                                                enum:
                                                - null
                                                - running
                                                - finished
                                                - blocked
                                                - failed
                                        forms:
                                          type: array
                                          description: List of forms associated with the course
                                          items:
                                            properties:
                                              id:
                                                type: integer
                                                description: Identifier of the form
                                              name:
                                                type: string
                                                description: Name of the form
                                              sectionId:
                                                type: integer
                                                description: Identifier of the associated section
                                              order:
                                                type: integer
                                                description: Order of the form within the course
                                              status:
                                                type: string
                                                description: Current status of the form
                                                enum:
                                                - null
                                                - completed
                                                - started
                                  tests:
                                    type: array
                                    description: List of tests associated with the course
                                    items:
                        

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendpulse/refs/heads/main/openapi/sendpulse-students-api-openapi.yml