# List Admins & Moderators or Get Details
Source: https://docs.schoolmaker.com/api-reference/endpoints/admins/get

get /admins
Without id/email, returns the list of admins & moderators of your school. If id or email is provided, returns a single admin/moderator.



# Create a Coaching Appointment
Source: https://docs.schoolmaker.com/api-reference/endpoints/coachings/appointments/create

post /coachings/appointments
Creates an appointment with selected members and coaches.



# List Coaching Types
Source: https://docs.schoolmaker.com/api-reference/endpoints/coachings/types/list

get /coachings/types



# Create a Conversation Group
Source: https://docs.schoolmaker.com/api-reference/endpoints/conversations/groups/create

post /conversations/groups
Creates a conversation group and sends its first message to the selected participants. The message can contain plain text or supported Markdown.



# Send a Conversation Message
Source: https://docs.schoolmaker.com/api-reference/endpoints/conversations/groups/send_message

post /conversations/groups/{id}/messages
Sends a message from an admin or moderator account to an existing conversation group. If the user is not already a participant, they will be added to the conversation group. The message can contain plain text or supported Markdown.



# Get Leaderboard Ranking
Source: https://docs.schoolmaker.com/api-reference/endpoints/gamifications/leaderboards/list

get /gamifications/leaderboards
Retrieves leaderboard ranking and filters by time range.



# Get Member Accesses
Source: https://docs.schoolmaker.com/api-reference/endpoints/members/accesses

get /members/accesses
Retrieves all member offer accesses.



# Delete a member
Source: https://docs.schoolmaker.com/api-reference/endpoints/members/delete_member

post /members/delete_member



# List Members or Get a Member
Source: https://docs.schoolmaker.com/api-reference/endpoints/members/get

get /members
Without id/email, returns a paginated list of members. If id or email is provided, returns a single member.



# Set Member Ban Status
Source: https://docs.schoolmaker.com/api-reference/endpoints/members/set_ban

post /members/set_ban



# Set Member Suspend Status
Source: https://docs.schoolmaker.com/api-reference/endpoints/members/set_suspend

post /members/set_suspend



# Set Offer Access for a Member / Add a Member
Source: https://docs.schoolmaker.com/api-reference/endpoints/offers/accesses/create

post /offers/{id}/accesses
Change member access status settings or add a new member.



# Get Offer Details
Source: https://docs.schoolmaker.com/api-reference/endpoints/offers/get

get /offers/{id}
Retrieves details from a specific offer.



# List Offers
Source: https://docs.schoolmaker.com/api-reference/endpoints/offers/list

get /offers
Retrieves all offers of your school.



# Set a Drip Boost
Source: https://docs.schoolmaker.com/api-reference/endpoints/offers/set_drip_boost

post /offers/{id}/accesses/set_drip_boost
Updates the drip boost value for a specific member in a specific offer.



# Set Offer Details
Source: https://docs.schoolmaker.com/api-reference/endpoints/offers/update

patch /offers/{id}
Updates offer's name, description, and publish status.



# Get Program Details
Source: https://docs.schoolmaker.com/api-reference/endpoints/products/get

get /products/{id}



# List Programs
Source: https://docs.schoolmaker.com/api-reference/endpoints/products/list

get /products
Retrieves all programs of your school.



# Create a Webhook
Source: https://docs.schoolmaker.com/api-reference/endpoints/webhooks/create

post /webhooks
Create a webhook for events: `element_completed`, `element_pending`, `member_joining_offer`, `new_payment`, `member_inactivity`, `gamification_level_passed`, `conversation_message_received`

Webhooks will allow you to detect when a specified event occurs. Supported event types include:

* `element_completed` → When a step is completed
  * **extra\_parameters**:
    * `step_type` → One or more step types. Leave empty to include all step types. Supported values are `basic`, `input_text`, `textarea`, `link`, `quiz`, `post`, `topic`, `milestone`, `file_upload`, and `form`
* `element_pending` → When a member submits an answer that needs to be corrected.
  * **extra\_parameters**:
    * `step_type` → One or more step types. Leave empty to include all applicable step types. Supported values are `input_text`, `textarea`, `post`, `topic`, `milestone`, and `file_upload`
* `member_joining_offer` →  When a member is added to an offer
  * **extra\_parameters**:
    * `offerFilter` → An offer ID or multiple offer IDs separated by commas. This event will only trigger if the member is added to an offer that matches the filter
* `new_payment` → When a member initiates a new payment (whether it is on a one-time offer price, a multiple installment price, or a subscription)
* `member_inactivity` → Will trigger at the same time as the member inactivity notification from SchoolMaker
* `gamification_level_passed`  → Which will trigger when a level is passed in the community gamification feature
  * **extra\_parameters**:
    * `activeLevels` → A comma-separated list of level numbers. This event will only trigger if the member has passed a level that is in the list
* `conversation_message_received` → When a User receives a new message in a conversation group
  * **extra\_parameters**:
    * `user_ids` → A list of User IDs. The event will only trigger when one of these Users receives the message. Leave empty to include all Users
    * `author_types` → Use `members` or `users` to filter messages by author type. Leave empty to include messages from both Members and Users

To see the payload for each event, please refer to the [Webhooks Payload](/api-reference/endpoints/webhooks/payload) page.


# Delete a Webhook
Source: https://docs.schoolmaker.com/api-reference/endpoints/webhooks/delete

delete /webhooks/{id}



# List Webhooks
Source: https://docs.schoolmaker.com/api-reference/endpoints/webhooks/list

get /webhooks



# Webhook Payloads
Source: https://docs.schoolmaker.com/api-reference/endpoints/webhooks/payload



Webhooks allow you to receive real-time HTTP notifications when specific events occur in your SchoolMaker instance. When an event is triggered, we'll send a POST request to your configured webhook URL with a JSON payload containing event details.

## Request Format

All webhook notifications are sent as POST requests with the following characteristics:

* Content-Type: `application/json`
* Request body: JSON object containing event data
* Webhook URL: The endpoint URL you configured to receive notifications

<Warning>
  Make sure your webhook endpoint can handle POST requests and process JSON payloads.
</Warning>

<Warning>
  The Webhook pages are still being worked on, naming is not definitive.
</Warning>

## Available Trigger Events

### Step Pending

**Event Name:** `element_pending` \\

**Description:** Triggers when a member submits an answer that needs to be corrected.

**Optional Step Type Filter:** Use `extra_parameters.step_type` to filter by `input_text`, `textarea`, `post`, `topic`, `milestone`, or `file_upload`. Leave empty to include all applicable step types.

**Payload Example:**

```json theme={null}
{
  "id": "string",
  "user_type": "string",
  "email": "string",
  "full_name": "string",
  "program_name": "string",
  "program_completion_percentage": 0,
  "section_name": "string",
  "section_completion_percentage": 0,
  "lesson_name": "string", 
  "lesson_completion_percentage": 0,
  "step_name": "string",
  "step_completion_date": "string",
  "see_in_schoolmaker": "string",
  "status": "string",
  "step_id": "string",
  "step_type": "string",
  "reviewer_id": "string",
  "step_is_optional": "string",
  "answer": "string",
  "quiz_completion_rate": "string",
  "quiz_data": [
    {
      "question": "string",
      "member_answer": "string", 
      "result": "string"
    }
  ],
  "form_data": [
    {
      "question": "string",
      "answer": "string"
    }
  ],
  "comment_text": "string",
  "comment_link": "string",
  "post_link": "string",
  "step_file_upload_url": "string",
  "milestone_proof_url": "string"
}
```

### Step Completion

**Event Name:** `element_completed` \\

**Description:** Triggered when a member completes an element (step, lesson, section, etc.) in a course.

**Optional Step Type Filter:** Use `extra_parameters.step_type` to filter by `basic`, `input_text`, `textarea`, `link`, `quiz`, `post`, `topic`, `milestone`, `file_upload`, or `form`. Leave empty to include all step types.

**Payload Example:**

```json theme={null}
{
  "id": "string",
  "user_type": "string",
  "email": "string",
  "full_name": "string",
  "program_name": "string",
  "program_completion_percentage": 0,
  "section_name": "string",
  "section_completion_percentage": 0,
  "lesson_name": "string", 
  "lesson_completion_percentage": 0,
  "step_name": "string",
  "step_completion_date": "string",
  "see_in_schoolmaker": "string",
  "status": "string",
  "step_id": "string",
  "step_type": "string",
  "reviewer_id": "string",
  "step_is_optional": "string",
  "answer": "string",
  "quiz_completion_rate": "string",
  "quiz_data": [
    {
      "question": "string",
      "member_answer": "string", 
      "result": "string"
    }
  ],
  "form_data": [
    {
      "question": "string",
      "answer": "string"
    }
  ],
  "comment_text": "string",
  "comment_link": "string",
  "post_link": "string",
  "step_file_upload_url": "string",
  "milestone_proof_url": "string"
}
```

### New Member Offer Access

**Event Name:** `member_joining_offer` \\

**Description:** Triggered when a new or existing member gets access to an offer.

**Payload Example:**

```json theme={null}
{
  "email_member": "string",
  "offer_name": "string",
  "offer_id": "string"
}
```

### New Payment

**Event Name:** `new_payment` \\

**Description:** Triggered when a successful payment is processed for an offer, and also triggered for each installment or subscription payment.

**Payload Example:**

```json theme={null}
{
  "email_member": "string",
  "first_name_member": "string",
  "last_name_member": "string",
  "offer_name": "string",
  "offer_id": "string",
  "transaction_creation_date": "string",
  "transaction_status": "string",
  "price": 0,
  "currency": "string",
  "price_type": "one-time | recurring | multiple-installments"
} 
```

### Member Inactivity

**Event Name:** `member_inactivity` \\

**Description:** Triggered when a member is detected as inactive, coinciding with the SchoolMaker inactivity notification.

**Payload Example:**

```json theme={null}
{
  "email_member": "string",
  "first_name_member": "string",
  "last_name_member": "string",
  "offers": [
    {
      "offer_id": "string",
      "offer_name": "string"
    }
  ],
  "programs": [
    {
      "id": "string",
      "name": "string",
      "program_completion_percentage": 0
    }
  ]
}
```

### Gamification Level Passed

**Event Name:** `gamification_level_passed` \\

**Description:** Triggered when a member reaches a new level in the community gamification feature.

**Payload Example:**

```json theme={null}
{
  "email_member": "string",
  "first_name_member": "string",
  "last_name_member": "string",
  "level_unlocked": 0
}
```

### Conversation Message Received

**Event Name:** `conversation_message_received` \\

**Description:** Triggered when a User receives a new message in a conversation group.

The `related_step` field is `null` when the conversation is not associated with a program step. The `participants_preview` field contains up to ten participants, and `recent_messages_preview` contains up to three messages sent before the current message. For system-generated messages, `author_type` and `author_name` may be `null`.

**Payload Example:**

```json theme={null}
{
  "event_type": "conversation_message_received",
  "message": {
    "id": "string",
    "content": "string",
    "created_at": "string",
    "author": {
      "id": "string",
      "type": "Member | User",
      "name": "string",
      "email": "string"
    }
  },
  "received_by_users": [
    {
      "id": "string",
      "type": "User",
      "name": "string",
      "email": "string"
    }
  ],
  "conversation_group": {
    "id": "string",
    "title": "string",
    "participants_count": 0,
    "participants_preview": [
      {
        "id": "string",
        "type": "Member | User",
        "name": "string"
      }
    ],
    "created_at": "string",
    "last_activity_at": "string"
  },
  "related_step": {
    "step_progress_id": "string",
    "step_id": "string",
    "step_name": "string",
    "lesson_id": "string",
    "lesson_name": "string",
    "section_id": "string",
    "section_name": "string",
    "program_id": "string",
    "program_name": "string"
  },
  "recent_messages_preview": [
    {
      "id": "string",
      "author_type": "Member | User",
      "author_name": "string",
      "content": "string",
      "created_at": "string"
    }
  ],
  "url": "string"
}
```


# API Quickstart
Source: https://docs.schoolmaker.com/quickstart

The SchoolMaker REST API lets you manage your members and track your school's activity. 

## Authentication

<Note>
  Only schools on the **Pro** and **Business** plans will get access to the SchoolMaker API. You can upgrade your plan from your school's billing settings or contact our support team if you want to get API access.
</Note>

<Warning>
  Your SchoolMaker API key should never be used client side or exposed to your end users.
</Warning>

Start here if you want to use the SchoolMaker API to manage your members or track your school activity.

<Accordion title="Authentication Steps">
  To get started, you’ll need an API key. Go to `Settings` -> `Integration & API` in your SchoolMaker settings and scroll down to the API Section.

  <img alt="" />

  You will be able to copy your API key by clicking on the clipboard button.

  <Info>
    When making an API call, you will need to add an Authorization header and set the API key as a Bearer token.
  </Info>

  Here’s an example Curl request (replace `YOUR_API_KEY` with your own API key):

  ```bash theme={null}
  curl --request GET \
    --url https://schoolmaker.co/api/v1/products \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```
</Accordion>

## Rate Limiting

<Warning>
  Exceeding rate limits may temporarily block your API access. If you hit the limit, you'll get a 429 Too Many Requests response. Handle limits carefully.
</Warning>

The SchoolMaker API uses rate limits to manage request volumes and ensure fair usage.

<Accordion title="Rate Limiting Details">
  **Rate Limit Headers**:

  Each API response includes headers to help you track your usage:

  * X-RateLimit-Limit: Maximum requests allowed per period.
  * X-RateLimit-Remaining: Requests left in the current period.
  * X-RateLimit-Reset: Time when the limit resets (epoch time).

  **Rate Limiting Rules**:

  General API Requests: 5 requests per second per IP.
</Accordion>

## Base URL

```text theme={null}
https://schoolmaker.co/api/v1
```

## Response Format

All responses are in JSON format. Successful responses will contain the requested data, while error responses will have this structure:

```json theme={null}
{
  "error": "Error message or array of error messages"
}
```

## HTTP Status Codes

* 200: Success
* 201: Created
* 204: No Content
* 400: Bad Request
* 401: Unauthorized
* 404: Not Found
* 422: Unprocessable Entity
* 500: Internal Server Error

## Debugging

Sometimes things go wrong. Here are some tips to help you debug your API requests.

<Accordion title="Debugging Steps">
  If you are having trouble with the API, we recommend using a tool like [Postman](https://www.postman.com/) to test your requests.

  1. Dealing with “Not Authenticated” Codes:
     * Make sure you are using an API key from the SchoolMaker "Integrations & API" settings page and that you are including it in your requests.
     * Your API key should be included in the “Authorization” header of your request, following the format “Authorization: Bearer YOUR\_API\_KEY”.
  2. Authorization Header:
     * Ensure that you are correctly including the “Authorization” header in your requests. The value of this header should follow the format “Bearer YOUR\_API\_KEY”.
  3. Handling 400-level Responses:
     * 400-level responses typically indicate that there was a problem with the request. The response body will contain more information about what went wrong, so be sure to check it for details.
     * Check on your request type (GET, POST, PUT, DELETE) and ensure that you are using the correct one for the endpoint you are trying to access.

  If you have followed these steps and are still experiencing issues, don’t hesitate to [reach out to the SchoolMaker team](mailto:support@schoolmaker.co) for further assistance.
</Accordion>

## Where to find IDs?

<Accordion title="How to find member, offer, or program IDs">
  **✨ New**: It is now possible to easily copy IDs from your school UI in one click. You will usually find this ID when editing or in the settings of the element for which you need an ID.

  <img alt="" />

  To find a **member ID**, go to the member's profile in your admin space, and copy the ID from the current URL:

  <img alt="" />

  To find an **offer ID**, go to the offer in your admin space, and copy the ID from the current URL:

  <img alt="" />

  To find a **program ID**, go to the program in your admin space, and copy the ID from the current URL:

  <img alt="" />
</Accordion>

## Members

The SchoolMaker API allows you to get information about your members:

<CardGroup>
  <Card title="Get member details" icon="user" href="https://docs.schoolmaker.com/api-reference/endpoints/members/get">
    Get details from a member like their first name, last name, email, or creation date
  </Card>

  <Card title="List members" icon="users" href="https://docs.schoolmaker.com/api-reference/endpoints/members/get">
    Get a list of your school's members. Note that this list has pagination
  </Card>

  <Card title="Get member offer accesses" icon="user-magnifying-glass" href="https://docs.schoolmaker.com/api-reference/endpoints/members/accesses">
    Get a detailed list of which offers a specific member has access to
  </Card>

  <Card title="Set Member Suspend Status" icon="user-times" href="https://docs.schoolmaker.com/api-reference/endpoints/members/set_suspend">
    Change a member's suspension status with the API
  </Card>

  <Card title="Set Member Ban Status" icon="user-large-slash" href="https://docs.schoolmaker.com/api-reference/endpoints/members/set_ban">
    Change a member's ban status with the API
  </Card>

  <Card title="Delete a member" icon="trash-alt" href="https://docs.schoolmaker.com/api-reference/endpoints/members/delete_member">
    Delete a member from your school with the API
  </Card>
</CardGroup>

## Admins & Moderators

The SchoolMaker API allows you to get information about admins & moderators in your school:

<CardGroup>
  <Card title="List admins & moderators" icon="user-shield" href="https://docs.schoolmaker.com/api-reference/endpoints/admins/ge">
    Get a list of your school's admins and moderators, with details about each
  </Card>

  <Card title="Get admin or moderator details" icon="user-shield" href="https://docs.schoolmaker.com/api-reference/endpoints/admins/get">
    Get details from a specific admin or moderator from your school
  </Card>
</CardGroup>

## Offers

Configure and list your school's offers:

<CardGroup>
  <Card title="List all offers" icon="boxes-stacked" href="https://docs.schoolmaker.com/api-reference/endpoints/offers/list">
    List all of your school's offers and get their names, descriptions & prices
  </Card>

  <Card title="Get offer details" icon="box-open-full" href="https://docs.schoolmaker.com/api-reference/endpoints/offers/get">
    Get details from a specific offer like its name, description, prices or creation date
  </Card>

  <Card title="Set offer details" icon="box" href="https://docs.schoolmaker.com/api-reference/endpoints/offers/update">
    Updates offer’s name, description, and publish status
  </Card>

  <Card title="Set a drip boost" icon="calendar-circle-plus" href="https://docs.schoolmaker.com/api-reference/endpoints/offers/set_drip_boost">
    Updates the drip boost value for a specific member in a specific offer
  </Card>

  <Card title="Set offer access for a member" icon="box-circle-check" href="https://docs.schoolmaker.com/api-reference/endpoints/offers/accesses/create">
    Change member access status for a specific offer in your school or add a new member
  </Card>
</CardGroup>

## Programs

List school programs and get more information about specific programs and member progressions:

<CardGroup>
  <Card title="List programs" icon="graduation-cap" href="https://docs.schoolmaker.com/api-reference/endpoints/products/list">
    List all of your school's published programs with their IDs, names & descriptions
  </Card>

  <Card title="Get program details" icon="graduation-cap" href="https://docs.schoolmaker.com/api-reference/endpoints/products/get">
    Get details from a specific program and check specific member's progression for a program
  </Card>
</CardGroup>

## Coachings

Create coaching appointments and list coaching types:

<CardGroup>
  <Card title="Create a coaching appointment" icon="phone-plus" href="https://docs.schoolmaker.com/api-reference/endpoints/coachings/appointments/create">
    Create a coaching appointment, for example after a booking is created in Calendly
  </Card>

  <Card title="List coaching types" icon="phone" href="https://docs.schoolmaker.com/api-reference/endpoints/coachings/types/list">
    Get a list of all coaching types you have created in your school
  </Card>
</CardGroup>

## Conversations

Create conversations to communicate with your members directly from your school.

<CardGroup>
  <Card title="Create a Conversation Group" icon="message-plus" href="https://docs.schoolmaker.com/api-reference/endpoints/conversations/groups/create">
    Create a conversation with two or more participants with a custom message
  </Card>

  <Card title="Send a Conversation Message" icon="message-arrow-up-right" href="https://docs.schoolmaker.com/api-reference/endpoints/conversations/groups/send_message">
    Sends a message from an admin or moderator account
  </Card>
</CardGroup>

## Gamification

Retrieves leaderboard ranking and filters by time range.

<Card title="Get Leaderboard Ranking" icon="ranking-star" href="https://docs.schoolmaker.com/api-reference/endpoints/gamifications/leaderboards/list">
  Get the top 10 members in the community gamification leaderboard ranking with filters by time range
</Card>

## Webhooks (Triggers)

Webhooks will allow you to detect when a specified event occurs. Supported event types include:

* `element_completed` → When a step is completed
* `element_pending` → When a member submits an answer that needs to be corrected.
* `member_joining_offer` → When a member is added to an offer
  * **extra\_parameters**:
    * `offerFilter` → An offer ID or multiple offer IDs separated by commas. This event will only trigger if the member is added to an offer that matches the filter
* `new_payment` → When a member initiates a new payment (whether it is on a one-time offer price, a multiple installment price, or a subscription)
* `member_inactivity` → Will trigger at the same time as the member inactivity notification from SchoolMaker
* `gamification_level_passed` → Which will trigger when a level is passed in the community gamification feature
  * **extra\_parameters**:
    * `activeLevels` → A comma-separated list of level numbers. This event will only trigger if the member has passed a level that is in the list
* `conversation_message_received` → When a User receives a new message in a conversation group
  * **extra\_parameters**:
    * `user_ids` → A list of User IDs. The event will only trigger when one of these Users receives the message. Leave empty to include all Users
    * `author_types` → Use `members` or `users` to filter messages by author type. Leave empty to include messages from both Members and Users

<CardGroup>
  <Card title="List webhooks" icon="webhook" href="https://docs.schoolmaker.com/api-reference/endpoints/webhooks/list" />

  <Card title="Create a webhook" icon="webhook" href="https://docs.schoolmaker.com/api-reference/endpoints/webhooks/create" />

  <Card title="Delete a Webhook" icon="webhook" href="https://docs.schoolmaker.com/api-reference/endpoints/webhooks/delete" />
</CardGroup>

To see the payload for each event, please refer to the [Webhooks Payload](/api-reference/endpoints/webhooks/payload) page.