{
  "openapi": "3.1.0",
  "info": {
    "title": "Fipeo public API",
    "version": "1.0.0",
    "summary": "Read your schools, courses, quotes, bookings and students, add students, and get events by webhook.",
    "description": "The public API of [Fipeo](https://fipeo.net) for language schools and agencies. Each key or token only sees the data of its own organization and only with its scopes. Prices are what the student pays: commissions and net prices never leave Fipeo.\n\n**Status:** early access. The API is switched off for most accounts: write to support@fipeo.net to use it.\n\n**Version.** The version is in the path (`/v1`). v1 was settled before the launch (November 2026): from now on, within v1 we only add things (new routes, fields, events, statuses and error codes), and your client must ignore fields it does not know. Breaking changes go to a new version, announced in the changelog. Webhook bodies carry `api_version` (today `2026-11-09`).\n\n**Formats.** JSON in UTF-8. Amounts are integers in cents (minor units) of `currency`. Dates are `YYYY-MM-DD`; date-times are ISO 8601 in UTC with `Z` (`2026-11-11T10:00:00Z`) everywhere, in responses and in webhooks. Statuses are stable English codes. Every response has `Cache-Control: no-store`.\n\n**Errors.** JSON with a stable `error` code and a readable `message` in the language of the request (`Accept-Language` or `X-Fipeo-Lang`: en, es, fr, it, de, pt). Validation errors (422) have `errors`: field → message. See `x-fipeo-error-codes`.\n\n**Rate limits.** 120 requests per minute per key (or OAuth application), 30 of them writes, and 600 per minute per IP address. Every response to a recognised key carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds) and `RateLimit-Policy` (`120;w=60`). Over the limit: 429 with `Retry-After`.\n\n**Pagination.** Every list (`/schools`, `/courses`, `/quotes`, `/bookings`, `/students`) takes `page` (from 1) and answers `items`, `total`, `page`, `pages` and `next` (the path of the next page with the same filters, or null). Page sizes: 20 for `/courses`, 50 for the rest. Nothing is cut silently: follow `next` until it is null.\n\n**Idempotency.** Send an `Idempotency-Key` header with `POST /students` (the OAuth token endpoints follow RFC 6749 and ignore it): for 24 hours the same key and the same request return the stored response (with `Idempotent-Replayed: true`) without running it again. The same key with a different request gives `422 idempotency_key_reused`. Webhooks carry an event `id` that stays the same when an event is resent.",
    "contact": {
      "name": "Fipeo support",
      "email": "support@fipeo.net",
      "url": "https://fipeo.net/en/developers"
    },
    "termsOfService": "https://fipeo.net/en/legal"
  },
  "externalDocs": {
    "description": "Developer guides",
    "url": "https://fipeo.net/en/developers"
  },
  "servers": [
    {
      "url": "https://fipeo.net/api/public/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKey": []
    },
    {
      "OAuth2": []
    }
  ],
  "tags": [
    {
      "name": "Account",
      "description": "The key and its organization."
    },
    {
      "name": "Catalog",
      "description": "Agencies: the schools you are connected to and their courses."
    },
    {
      "name": "Quotes",
      "description": "Agencies: the quotes of your CRM."
    },
    {
      "name": "Bookings",
      "description": "Agencies: your bookings. Schools: your booking inbox."
    },
    {
      "name": "Students",
      "description": "Agencies: the students of your CRM."
    },
    {
      "name": "OAuth",
      "description": "OAuth 2.0 client credentials, for software that only speaks OAuth."
    },
    {
      "name": "Webhooks",
      "description": "Events Fipeo sends to your URL."
    }
  ],
  "paths": {
    "/me": {
      "get": {
        "summary": "The key and its organization",
        "operationId": "getMe",
        "tags": [
          "Account"
        ],
        "x-fipeo-organization": "both",
        "security": [
          {
            "ApiKey": []
          },
          {
            "OAuth2": []
          }
        ],
        "description": "Who you are: the organization that owns the key (or OAuth token), the key and its scopes. Needs no scope.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/schools": {
      "get": {
        "summary": "Schools you are connected to",
        "operationId": "listSchools",
        "tags": [
          "Catalog"
        ],
        "x-fipeo-organization": "agency",
        "security": [
          {
            "ApiKey": [
              "catalog:read"
            ]
          },
          {
            "OAuth2": [
              "catalog:read"
            ]
          }
        ],
        "description": "The schools with an **active** connection with your agency, 50 per page.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SchoolList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/courses": {
      "get": {
        "summary": "Search courses with the price for the student",
        "operationId": "listCourses",
        "tags": [
          "Catalog"
        ],
        "x-fipeo-organization": "agency",
        "security": [
          {
            "ApiKey": [
              "catalog:read"
            ]
          },
          {
            "OAuth2": [
              "catalog:read"
            ]
          }
        ],
        "description": "The courses of your connected schools, each priced for one student with the given start date and weeks (the same search as «Find courses» in the panel). The price is what the student pays: never your commission or the net price. 20 results per page.",
        "parameters": [
          {
            "name": "school_id",
            "in": "query",
            "required": false,
            "description": "Only this school (its id).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "ISO 3166-1 alpha-2 country of the school.",
            "schema": {
              "type": "string",
              "maxLength": 2
            }
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "description": "City of the school.",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "Language taught (en, es…).",
            "schema": {
              "type": "string",
              "maxLength": 5
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Course type (general, intensive…).",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "level",
            "in": "query",
            "required": false,
            "description": "CEFR level of the student.",
            "schema": {
              "type": "string",
              "enum": [
                "A1",
                "A2",
                "B1",
                "B2",
                "C1",
                "C2"
              ]
            }
          },
          {
            "name": "weeks",
            "in": "query",
            "required": false,
            "description": "Number of weeks (default: the minimum of each course).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 104
            }
          },
          {
            "name": "start",
            "in": "query",
            "required": false,
            "description": "Start date (default: the Monday about two weeks from today).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "age",
            "in": "query",
            "required": false,
            "description": "Age of the student.",
            "schema": {
              "type": "integer",
              "minimum": 3,
              "maximum": 120
            }
          },
          {
            "name": "accommodation",
            "in": "query",
            "required": false,
            "description": "Only schools that offer accommodation.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language of the course names.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "es",
                "fr",
                "it",
                "de",
                "pt"
              ],
              "default": "en"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CourseList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/quotes": {
      "get": {
        "summary": "List quotes",
        "operationId": "listQuotes",
        "tags": [
          "Quotes"
        ],
        "x-fipeo-organization": "agency",
        "security": [
          {
            "ApiKey": [
              "quotes:read"
            ]
          },
          {
            "OAuth2": [
              "quotes:read"
            ]
          }
        ],
        "description": "The quotes of your agency, newest first, 50 per page. Each quote shows what the student pays (`from_total`), never the school price or your commission.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only quotes in this status. Any other value gives 422.",
            "schema": {
              "$ref": "#/components/schemas/QuoteStatus"
            }
          },
          {
            "name": "student_id",
            "in": "query",
            "required": false,
            "description": "Only the quotes of this student.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuoteList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/quotes/{id}": {
      "get": {
        "summary": "Get a quote",
        "operationId": "getQuote",
        "tags": [
          "Quotes"
        ],
        "x-fipeo-organization": "agency",
        "security": [
          {
            "ApiKey": [
              "quotes:read"
            ]
          },
          {
            "OAuth2": [
              "quotes:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Quote id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/bookings": {
      "get": {
        "summary": "List bookings",
        "operationId": "listBookings",
        "tags": [
          "Bookings"
        ],
        "x-fipeo-organization": "both",
        "security": [
          {
            "ApiKey": [
              "bookings:read"
            ]
          },
          {
            "OAuth2": [
              "bookings:read"
            ]
          }
        ],
        "description": "Agency key: your bookings, newest first, as `BookingSummary`. School key: your booking inbox, newest first, as `SchoolBooking`. 50 per page.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only bookings in this status. Any other value gives 422, with an agency or a school key.",
            "schema": {
              "$ref": "#/components/schemas/BookingStatus"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/BookingList"
                    },
                    {
                      "$ref": "#/components/schemas/SchoolBookingList"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/bookings/{reference}": {
      "get": {
        "summary": "Get a booking",
        "operationId": "getBooking",
        "tags": [
          "Bookings"
        ],
        "x-fipeo-organization": "agency",
        "security": [
          {
            "ApiKey": [
              "bookings:read"
            ]
          },
          {
            "OAuth2": [
              "bookings:read"
            ]
          }
        ],
        "description": "One booking of your agency, with its lines and participants. Agency keys only (a school key gets 404).",
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "description": "Booking reference.",
            "schema": {
              "type": "string",
              "pattern": "^FA-[A-Z0-9]{10}$"
            }
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Booking"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/students": {
      "get": {
        "summary": "List students",
        "operationId": "listStudents",
        "tags": [
          "Students"
        ],
        "x-fipeo-organization": "agency",
        "security": [
          {
            "ApiKey": [
              "students:read"
            ]
          },
          {
            "OAuth2": [
              "students:read"
            ]
          }
        ],
        "description": "The students of your CRM, 50 per page. Internal notes never leave Fipeo.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search in name, email and phone.",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "description": "Only students with this tag.",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "consent",
            "in": "query",
            "required": false,
            "description": "Only students who gave (yes) or did not give (no) consent.",
            "schema": {
              "type": "string",
              "enum": [
                "yes",
                "no"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StudentList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      },
      "post": {
        "summary": "Add a student",
        "operationId": "createStudent",
        "tags": [
          "Students"
        ],
        "x-fipeo-organization": "agency",
        "security": [
          {
            "ApiKey": [
              "students:write"
            ]
          },
          {
            "OAuth2": [
              "students:write"
            ]
          }
        ],
        "description": "Adds a student to your CRM as if they had filled in one of your forms: with the exact consent text, an opportunity in your pipeline and a notification to your team. If a student with the same email exists, `if_exists` decides. Calling it again with the same email does not create a duplicate, and with an `Idempotency-Key` a retry returns the same response for 24 hours. Limit: 30 writes per minute per key.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewStudent"
              },
              "example": {
                "first_name": "Lucía",
                "last_name": "Pérez",
                "email": "lucia@example.org",
                "nationality": "AR",
                "consent_text": "I agree that Agencia Sol keeps my details to send me course offers.",
                "opportunity_title": "Dublin summer"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created, updated or skipped (see `result`).",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewStudentResult"
                }
              }
            }
          },
          "400": {
            "description": "`invalid_json`: the body is not valid JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "description": "A field is not valid (`errors`: field → message), or `idempotency_key_reused`: this `Idempotency-Key` was already used with a different request.",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ValidationError"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/students/{id}": {
      "get": {
        "summary": "Get a student",
        "operationId": "getStudent",
        "tags": [
          "Students"
        ],
        "x-fipeo-organization": "agency",
        "security": [
          {
            "ApiKey": [
              "students:read"
            ]
          },
          {
            "OAuth2": [
              "students:read"
            ]
          }
        ],
        "description": "One student with their opportunities and quotes.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Student id.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StudentDetail"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/oauth/token": {
      "post": {
        "summary": "Get an OAuth access token",
        "operationId": "oauthToken",
        "tags": [
          "OAuth"
        ],
        "x-fipeo-organization": "both",
        "security": [],
        "description": "OAuth 2.0 client credentials (RFC 6749 §4.4). Authenticate the client with HTTP Basic (`client_id:client_secret`) **or** with `client_id` and `client_secret` in the body, never both. The token lasts one hour; there is no refresh token: ask for a new one. At most 20 active tokens per application. Limits: 60 requests per minute per IP and 30 per application.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type"
                ],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "client_credentials"
                    ]
                  },
                  "scope": {
                    "type": "string",
                    "description": "Scopes separated by spaces, a subset of the application’s (empty = all of them)."
                  },
                  "client_id": {
                    "type": "string",
                    "pattern": "^fpc_[A-Za-z0-9_-]{20,36}$"
                  },
                  "client_secret": {
                    "type": "string",
                    "pattern": "^fps_[A-Za-z0-9_-]{40,60}$"
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type"
                ],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "client_credentials"
                    ]
                  },
                  "scope": {
                    "type": "string"
                  },
                  "client_id": {
                    "type": "string"
                  },
                  "client_secret": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The token.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              },
              "Pragma": {
                "schema": {
                  "type": "string",
                  "const": "no-cache"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthToken"
                }
              }
            }
          },
          "400": {
            "description": "`invalid_request`, `unsupported_grant_type` or `invalid_scope` (RFC 6749 §5.2).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthError"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_client`: unknown client, wrong secret, revoked or expired application, or account no longer active. With Basic, also `WWW-Authenticate: Basic realm=\"fipeo\"`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthError"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/oauth/revoke": {
      "post": {
        "summary": "Revoke an OAuth access token",
        "operationId": "oauthRevoke",
        "tags": [
          "OAuth"
        ],
        "x-fipeo-organization": "both",
        "security": [],
        "description": "RFC 7009. The client (authenticated as in /oauth/token) revokes one of its tokens. If the token does not exist or is not the client’s, the answer is also 200.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "client_id": {
                    "type": "string"
                  },
                  "client_secret": {
                    "type": "string"
                  }
                }
              }
            },
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "client_id": {
                    "type": "string"
                  },
                  "client_secret": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Revoked (or nothing to revoke).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "description": "`invalid_request`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthError"
                }
              }
            }
          },
          "401": {
            "description": "`invalid_client`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthError"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    }
  },
  "webhooks": {
    "booking.created": {
      "post": {
        "summary": "A booking was created",
        "operationId": "webhook_booking_created",
        "tags": [
          "Webhooks"
        ],
        "x-fipeo-organization": "both",
        "parameters": [
          {
            "name": "X-Fipeo-Signature",
            "in": "header",
            "required": true,
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256 of \"t.body\" with your webhook secret>",
            "schema": {
              "type": "string",
              "pattern": "^t=\\d{1,12},v1=[0-9a-f]{64}$"
            }
          },
          {
            "name": "X-Fipeo-Event",
            "in": "header",
            "required": true,
            "description": "The event type, as in `type`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Event-Id",
            "in": "header",
            "required": true,
            "description": "The event id, as in `id` (the same in a resend).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Delivery",
            "in": "header",
            "required": true,
            "description": "The id of this delivery (a resend has a new one).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookBookingEvent"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Answer any 2xx within 10 seconds. Anything else (or a timeout) is retried."
          }
        }
      }
    },
    "booking.status_changed": {
      "post": {
        "summary": "A booking changed status",
        "operationId": "webhook_booking_status_changed",
        "tags": [
          "Webhooks"
        ],
        "x-fipeo-organization": "both",
        "parameters": [
          {
            "name": "X-Fipeo-Signature",
            "in": "header",
            "required": true,
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256 of \"t.body\" with your webhook secret>",
            "schema": {
              "type": "string",
              "pattern": "^t=\\d{1,12},v1=[0-9a-f]{64}$"
            }
          },
          {
            "name": "X-Fipeo-Event",
            "in": "header",
            "required": true,
            "description": "The event type, as in `type`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Event-Id",
            "in": "header",
            "required": true,
            "description": "The event id, as in `id` (the same in a resend).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Delivery",
            "in": "header",
            "required": true,
            "description": "The id of this delivery (a resend has a new one).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookBookingStatusEvent"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Answer any 2xx within 10 seconds. Anything else (or a timeout) is retried."
          }
        }
      }
    },
    "message.created": {
      "post": {
        "summary": "A new message in a conversation",
        "operationId": "webhook_message_created",
        "tags": [
          "Webhooks"
        ],
        "x-fipeo-organization": "both",
        "parameters": [
          {
            "name": "X-Fipeo-Signature",
            "in": "header",
            "required": true,
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256 of \"t.body\" with your webhook secret>",
            "schema": {
              "type": "string",
              "pattern": "^t=\\d{1,12},v1=[0-9a-f]{64}$"
            }
          },
          {
            "name": "X-Fipeo-Event",
            "in": "header",
            "required": true,
            "description": "The event type, as in `type`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Event-Id",
            "in": "header",
            "required": true,
            "description": "The event id, as in `id` (the same in a resend).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Delivery",
            "in": "header",
            "required": true,
            "description": "The id of this delivery (a resend has a new one).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookMessageCreatedEvent"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Answer any 2xx within 10 seconds. Anything else (or a timeout) is retried."
          }
        }
      }
    },
    "quote.accepted": {
      "post": {
        "summary": "A student accepted a quote",
        "operationId": "webhook_quote_accepted",
        "tags": [
          "Webhooks"
        ],
        "x-fipeo-organization": "agency",
        "parameters": [
          {
            "name": "X-Fipeo-Signature",
            "in": "header",
            "required": true,
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256 of \"t.body\" with your webhook secret>",
            "schema": {
              "type": "string",
              "pattern": "^t=\\d{1,12},v1=[0-9a-f]{64}$"
            }
          },
          {
            "name": "X-Fipeo-Event",
            "in": "header",
            "required": true,
            "description": "The event type, as in `type`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Event-Id",
            "in": "header",
            "required": true,
            "description": "The event id, as in `id` (the same in a resend).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Delivery",
            "in": "header",
            "required": true,
            "description": "The id of this delivery (a resend has a new one).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookQuoteAcceptedEvent"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Answer any 2xx within 10 seconds. Anything else (or a timeout) is retried."
          }
        }
      }
    },
    "student.created": {
      "post": {
        "summary": "A student was added to the CRM",
        "operationId": "webhook_student_created",
        "tags": [
          "Webhooks"
        ],
        "x-fipeo-organization": "agency",
        "parameters": [
          {
            "name": "X-Fipeo-Signature",
            "in": "header",
            "required": true,
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256 of \"t.body\" with your webhook secret>",
            "schema": {
              "type": "string",
              "pattern": "^t=\\d{1,12},v1=[0-9a-f]{64}$"
            }
          },
          {
            "name": "X-Fipeo-Event",
            "in": "header",
            "required": true,
            "description": "The event type, as in `type`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Event-Id",
            "in": "header",
            "required": true,
            "description": "The event id, as in `id` (the same in a resend).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Delivery",
            "in": "header",
            "required": true,
            "description": "The id of this delivery (a resend has a new one).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookStudentCreatedEvent"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Answer any 2xx within 10 seconds. Anything else (or a timeout) is retried."
          }
        }
      }
    },
    "automation.run": {
      "post": {
        "summary": "An automation of the CRM ran its «webhook» action",
        "operationId": "webhook_automation_run",
        "tags": [
          "Webhooks"
        ],
        "x-fipeo-organization": "agency",
        "parameters": [
          {
            "name": "X-Fipeo-Signature",
            "in": "header",
            "required": true,
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256 of \"t.body\" with your webhook secret>",
            "schema": {
              "type": "string",
              "pattern": "^t=\\d{1,12},v1=[0-9a-f]{64}$"
            }
          },
          {
            "name": "X-Fipeo-Event",
            "in": "header",
            "required": true,
            "description": "The event type, as in `type`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Event-Id",
            "in": "header",
            "required": true,
            "description": "The event id, as in `id` (the same in a resend).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Delivery",
            "in": "header",
            "required": true,
            "description": "The id of this delivery (a resend has a new one).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookAutomationEvent"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Answer any 2xx within 10 seconds. Anything else (or a timeout) is retried."
          }
        }
      }
    },
    "ping": {
      "post": {
        "summary": "Test event («Send a test» in the panel)",
        "operationId": "webhook_ping",
        "tags": [
          "Webhooks"
        ],
        "x-fipeo-organization": "both",
        "parameters": [
          {
            "name": "X-Fipeo-Signature",
            "in": "header",
            "required": true,
            "description": "t=<unix seconds>,v1=<hex HMAC-SHA256 of \"t.body\" with your webhook secret>",
            "schema": {
              "type": "string",
              "pattern": "^t=\\d{1,12},v1=[0-9a-f]{64}$"
            }
          },
          {
            "name": "X-Fipeo-Event",
            "in": "header",
            "required": true,
            "description": "The event type, as in `type`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Event-Id",
            "in": "header",
            "required": true,
            "description": "The event id, as in `id` (the same in a resend).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Fipeo-Delivery",
            "in": "header",
            "required": true,
            "description": "The id of this delivery (a resend has a new one).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPingEvent"
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Answer any 2xx within 10 seconds. Anything else (or a timeout) is retried."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "fpk_…",
        "description": "An API key of your organization, created in Integrations › API keys: `Authorization: Bearer fpk_…`. Shown once; Fipeo only keeps its SHA-256 hash. Never put it in a URL."
      },
      "OAuth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 client credentials. Create an application in Integrations › OAuth applications, ask for a token at /oauth/token and send `Authorization: Bearer fpt_…`. The token lasts one hour.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://fipeo.net/api/public/v1/oauth/token",
            "scopes": {
              "catalog:read": "Agencies: read the connected schools and their courses.",
              "quotes:read": "Agencies: read quotes.",
              "bookings:read": "Agencies and schools: read bookings.",
              "students:read": "Agencies: read students.",
              "students:write": "Agencies: add students (with their consent)."
            }
          }
        }
      }
    },
    "parameters": {
      "Page": {
        "name": "page",
        "in": "query",
        "required": false,
        "description": "Page number, from 1.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        }
      },
      "AcceptLanguage": {
        "name": "Accept-Language",
        "in": "header",
        "required": false,
        "description": "Language of `message` in errors (en, es, fr, it, de, pt). `X-Fipeo-Lang` wins if both are sent.",
        "schema": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Optional. A unique value you choose for this request (1 to 255 visible ASCII characters; a UUID is a good choice). For 24 hours, the same key with the same request returns the stored response without running it again (with `Idempotent-Replayed: true`); with a different request it answers `422 idempotency_key_reused`, and while the first is still running, `409 idempotency_key_in_use`. Errors are not stored: you can retry them with the same key.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "`unauthenticated`: no key, a malformed key, or a key that is revoked or expired, or whose account is no longer active. The same answer for all of them.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "`insufficient_scope` (with `scope`: the key lacks the permission this route needs) or `dpa_required` (students and quotes: the organization has not accepted the data processing agreement yet; with `organization_type`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "`not_found`: it does not exist **or it is not yours** (Fipeo never says whose it is). Also every route while the API is switched off, any path that does not match a route (for example a malformed id), and `GET /bookings/{reference}` with a school key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unprocessable": {
        "description": "A field or a filter is not valid (also `page` and `status`): `errors` maps each field to its message. The same for agency and school keys.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ValidationError"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "`too_many_requests`: rate limit reached (with `reason` and `retry_after` in seconds).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait.",
            "schema": {
              "type": "integer"
            }
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimit-Limit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimit-Remaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimit-Reset"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        }
      },
      "Busy": {
        "description": "`busy`: Fipeo is overloaded for a moment. Retry after `retry_after` seconds.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        }
      },
      "Conflict": {
        "description": "`idempotency_key_in_use`: a request with the same `Idempotency-Key` is still being processed. Retry in a moment.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Organization": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "id"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "agency",
              "school"
            ]
          },
          "id": {
            "type": [
              "string",
              "integer"
            ],
            "description": "Agency: the UUID of its account. School: its numeric id."
          }
        }
      },
      "Me": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "organization",
          "key",
          "scopes"
        ],
        "properties": {
          "organization": {
            "$ref": "#/components/schemas/Organization"
          },
          "key": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "prefix",
              "expires_at"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "Key id (for OAuth tokens: the id of the OAuth application)."
              },
              "name": {
                "type": "string"
              },
              "prefix": {
                "type": "string",
                "description": "First 12 characters of the key (or of the OAuth client id), to recognise it."
              },
              "expires_at": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
                "description": "When the key (or the OAuth token) expires; null = never. Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
                "format": "date-time"
              }
            }
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          }
        }
      },
      "Scope": {
        "type": "string",
        "enum": [
          "catalog:read",
          "quotes:read",
          "bookings:read",
          "students:read",
          "students:write"
        ]
      },
      "ConnectedSchool": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "connection_id",
          "status",
          "can_book",
          "school",
          "activated_at"
        ],
        "properties": {
          "connection_id": {
            "type": "string",
            "format": "uuid",
            "description": "The connection between your agency and the school."
          },
          "status": {
            "type": "string",
            "enum": [
              "active"
            ],
            "description": "Only active connections are listed."
          },
          "can_book": {
            "type": "boolean",
            "description": "Whether your agency can send bookings to this school today."
          },
          "school": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name"
            ],
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              }
            }
          },
          "activated_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "When the connection became active. Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          }
        }
      },
      "SchoolList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items",
          "total",
          "page",
          "pages",
          "next"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConnectedSchool"
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "All the results with these filters, in every page."
          },
          "page": {
            "type": "integer",
            "minimum": 1
          },
          "pages": {
            "type": "integer",
            "minimum": 1
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "Path and query of the next page with the same filters (e.g. `/api/public/v1/bookings?status=accepted&page=3`), or null on the last page."
          }
        }
      },
      "CourseResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "school",
          "course",
          "start",
          "weeks",
          "price"
        ],
        "properties": {
          "school": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "city",
              "country",
              "accommodation"
            ],
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ISO 3166-1 alpha-2."
              },
              "accommodation": {
                "type": "boolean",
                "description": "Whether the school offers accommodation."
              }
            }
          },
          "course": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "type",
              "language",
              "lessons_per_week",
              "min_age",
              "weeks_min",
              "weeks_max"
            ],
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "type": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "language": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "lessons_per_week": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "min_age": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "weeks_min": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "weeks_max": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            }
          },
          "start": {
            "type": "string",
            "format": "date",
            "description": "Start date used for the price."
          },
          "weeks": {
            "type": "integer"
          },
          "price": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "status",
              "total",
              "currency",
              "availability",
              "instant"
            ],
            "properties": {
              "status": {
                "type": "string",
                "description": "Price status: `ok` (priced), `price_on_request` (the school shares prices on request), `blocked` (this combination cannot be priced; see the panel), or another status of the price engine."
              },
              "total": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "What the student pays. null when there is no price. In cents (minor units) of `currency`."
              },
              "currency": {
                "type": "string",
                "pattern": "^[A-Z]{3}$"
              },
              "availability": {
                "type": "string",
                "enum": [
                  "available",
                  "on_request",
                  "sold_out"
                ]
              },
              "instant": {
                "type": "boolean",
                "description": "true: the booking is confirmed at once; false: it is a request the school answers."
              }
            }
          }
        }
      },
      "CourseList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items",
          "total",
          "page",
          "pages",
          "next"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CourseResult"
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "All the results with these filters, in every page."
          },
          "page": {
            "type": "integer",
            "minimum": 1
          },
          "pages": {
            "type": "integer",
            "minimum": 1
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "Path and query of the next page with the same filters (e.g. `/api/public/v1/bookings?status=accepted&page=3`), or null on the last page."
          }
        }
      },
      "QuoteStatus": {
        "type": "string",
        "enum": [
          "draft",
          "sent",
          "opened",
          "accepted",
          "expired",
          "withdrawn"
        ]
      },
      "QuoteSummary": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "owner_id",
          "number",
          "student_id",
          "student",
          "opportunity_id",
          "status",
          "language",
          "valid_until",
          "public_url",
          "accepted_option",
          "booking_reference",
          "created_at",
          "updated_at",
          "sent_at",
          "opened_at",
          "accepted_at",
          "option_count",
          "from_total",
          "currency"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "owner_id": {
            "type": "string",
            "format": "uuid",
            "description": "The user of your agency responsible for the quote."
          },
          "number": {
            "type": "string"
          },
          "student_id": {
            "type": "string",
            "format": "uuid"
          },
          "student": {
            "type": [
              "string",
              "null"
            ],
            "description": "Full name of the student."
          },
          "opportunity_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "status": {
            "$ref": "#/components/schemas/QuoteStatus"
          },
          "language": {
            "type": "string"
          },
          "valid_until": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          },
          "public_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "The page where the student sees and accepts the quote (null while it is a draft)."
          },
          "accepted_option": {
            "type": [
              "integer",
              "null"
            ]
          },
          "booking_reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "sent_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "opened_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "accepted_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "option_count": {
            "type": "integer"
          },
          "from_total": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The lowest option total for the student. In cents (minor units) of `currency`."
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "QuoteList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items",
          "total",
          "page",
          "pages",
          "next"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteSummary"
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "All the results with these filters, in every page."
          },
          "page": {
            "type": "integer",
            "minimum": 1
          },
          "pages": {
            "type": "integer",
            "minimum": 1
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "Path and query of the next page with the same filters (e.g. `/api/public/v1/bookings?status=accepted&page=3`), or null on the last page."
          }
        }
      },
      "Line": {
        "type": "object",
        "additionalProperties": false,
        "required": [],
        "properties": {
          "line": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "text": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "type": "string"
          },
          "start": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          },
          "end": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          },
          "units": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "QuoteOption": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "number",
          "school",
          "total",
          "lines"
        ],
        "properties": {
          "number": {
            "type": "integer"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "currency": {
            "type": "string"
          },
          "availability": {
            "type": [
              "string",
              "null"
            ]
          },
          "unconfirmed_prices": {
            "type": "boolean"
          },
          "school": {
            "type": "object",
            "additionalProperties": false,
            "required": [],
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "total": {
            "type": [
              "integer",
              "null"
            ],
            "description": "What the student pays for this option. In cents (minor units) of `currency`."
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Line"
            }
          }
        }
      },
      "Quote": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "owner_id",
          "number",
          "student_id",
          "student",
          "opportunity_id",
          "status",
          "language",
          "valid_until",
          "public_url",
          "accepted_option",
          "booking_reference",
          "created_at",
          "updated_at",
          "sent_at",
          "opened_at",
          "accepted_at",
          "options"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "owner_id": {
            "type": "string",
            "format": "uuid"
          },
          "number": {
            "type": "string"
          },
          "student_id": {
            "type": "string",
            "format": "uuid"
          },
          "student": {
            "type": [
              "string",
              "null"
            ],
            "description": "Full name of the student."
          },
          "opportunity_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "status": {
            "$ref": "#/components/schemas/QuoteStatus"
          },
          "language": {
            "type": "string"
          },
          "valid_until": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          },
          "public_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "accepted_option": {
            "type": [
              "integer",
              "null"
            ]
          },
          "booking_reference": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "sent_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "opened_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "accepted_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QuoteOption"
            }
          }
        }
      },
      "BookingStatus": {
        "type": "string",
        "enum": [
          "new",
          "pending",
          "alternative_proposed",
          "accepted",
          "declined",
          "cancelled",
          "expired"
        ],
        "description": "Booking status: `new` (it reached the school and nobody has opened it), `pending` (the school opened it and has not answered), `alternative_proposed` (the school proposed other dates or prices), `accepted`, `declined` (the school cannot take it), `cancelled` (by the agency, the student or the channel), `expired` (nobody answered in time)."
      },
      "BookingSummary": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "reference",
          "school",
          "status",
          "created_at",
          "updated_at",
          "start",
          "end",
          "first_line",
          "total",
          "currency",
          "owner_id"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "reference": {
            "type": "string",
            "pattern": "^FA-[A-Z0-9]{10}$"
          },
          "school": {
            "$ref": "#/components/schemas/SchoolRef"
          },
          "status": {
            "$ref": "#/components/schemas/BookingStatus"
          },
          "created_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "start": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Start of the first line."
          },
          "end": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "End of the first line."
          },
          "first_line": {
            "type": [
              "string",
              "null"
            ]
          },
          "total": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Total of the booking (what the student pays). In cents (minor units) of `currency`."
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "owner_id": {
            "type": "string"
          }
        }
      },
      "BookingList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items",
          "total",
          "page",
          "pages",
          "next"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BookingSummary"
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "All the results with these filters, in every page."
          },
          "page": {
            "type": "integer",
            "minimum": 1
          },
          "pages": {
            "type": "integer",
            "minimum": 1
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "Path and query of the next page with the same filters (e.g. `/api/public/v1/bookings?status=accepted&page=3`), or null on the last page."
          }
        }
      },
      "Participant": {
        "type": "object",
        "additionalProperties": false,
        "required": [],
        "properties": {
          "number": {
            "type": "integer"
          },
          "first_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "nationality": {
            "type": [
              "string",
              "null"
            ]
          },
          "birth_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          }
        }
      },
      "Booking": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "reference",
          "school",
          "status",
          "created_at",
          "updated_at",
          "owner_id",
          "total",
          "currency",
          "lines",
          "participants"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "reference": {
            "type": "string",
            "pattern": "^FA-[A-Z0-9]{10}$"
          },
          "school": {
            "$ref": "#/components/schemas/SchoolRef"
          },
          "status": {
            "$ref": "#/components/schemas/BookingStatus"
          },
          "created_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "owner_id": {
            "type": "string"
          },
          "total": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Total of the booking (what the student pays). In cents (minor units) of `currency`."
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Line"
            },
            "description": "What was booked, line by line (course, accommodation, extras), without amounts."
          },
          "participants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Participant"
            }
          }
        }
      },
      "SchoolBooking": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "reference",
          "status",
          "modality",
          "created_at",
          "seen_at",
          "resolved_at",
          "student",
          "nationality",
          "first_item",
          "start",
          "end",
          "units",
          "total",
          "currency",
          "channel"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "reference": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/BookingStatus"
          },
          "modality": {
            "type": "string",
            "enum": [
              "on_request",
              "instant"
            ],
            "description": "`on_request`: a request you answer; `instant`: booked at once on your allotment."
          },
          "created_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "seen_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "resolved_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "student": {
            "type": "string"
          },
          "nationality": {
            "type": [
              "string",
              "null"
            ]
          },
          "first_item": {
            "type": [
              "string",
              "null"
            ]
          },
          "start": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          },
          "end": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          },
          "units": {
            "type": [
              "integer",
              "null"
            ]
          },
          "total": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Gross total of the booking. In cents (minor units) of `currency`."
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "channel": {
            "type": "string",
            "description": "Where the booking came from: `agency` (an agency on Fipeo), `languagebookings`, `direct` (your website or booking form) or another channel code."
          }
        }
      },
      "SchoolBookingList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items",
          "total",
          "page",
          "pages",
          "next"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SchoolBooking"
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "All the results with these filters, in every page."
          },
          "page": {
            "type": "integer",
            "minimum": 1
          },
          "pages": {
            "type": "integer",
            "minimum": 1
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "Path and query of the next page with the same filters (e.g. `/api/public/v1/bookings?status=accepted&page=3`), or null on the last page."
          }
        }
      },
      "OpportunityStage": {
        "type": "string",
        "enum": [
          "new",
          "contacted",
          "quote_sent",
          "booked",
          "lost"
        ]
      },
      "Student": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "first_name",
          "email",
          "consent",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "owner_id": {
            "type": "string",
            "format": "uuid",
            "description": "The user of your agency responsible for the student."
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "nationality": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 3166-1 alpha-2."
          },
          "birth_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          },
          "age": {
            "type": [
              "integer",
              "null"
            ]
          },
          "language": {
            "type": [
              "string",
              "null"
            ]
          },
          "study_language": {
            "type": [
              "string",
              "null"
            ]
          },
          "level": {
            "type": [
              "string",
              "null"
            ]
          },
          "budget": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Budget. In cents (minor units) of `currency`."
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "start_from": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          },
          "start_to": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          },
          "weeks": {
            "type": [
              "integer",
              "null"
            ]
          },
          "interests": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "consent": {
            "type": "boolean"
          },
          "consent_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "consent_text": {
            "type": [
              "string",
              "null"
            ]
          },
          "stage": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/OpportunityStage"
              },
              {
                "type": "null"
              }
            ],
            "description": "Stage of the student’s open opportunity (or the last closed one)."
          },
          "created_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          }
        }
      },
      "StudentDetail": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "first_name",
          "email",
          "consent",
          "created_at",
          "updated_at",
          "opportunities",
          "quotes"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "owner_id": {
            "type": "string",
            "format": "uuid",
            "description": "The user of your agency responsible for the student."
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "nationality": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 3166-1 alpha-2."
          },
          "birth_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          },
          "age": {
            "type": [
              "integer",
              "null"
            ]
          },
          "language": {
            "type": [
              "string",
              "null"
            ]
          },
          "study_language": {
            "type": [
              "string",
              "null"
            ]
          },
          "level": {
            "type": [
              "string",
              "null"
            ]
          },
          "budget": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Budget. In cents (minor units) of `currency`."
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "start_from": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          },
          "start_to": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Date, `YYYY-MM-DD`."
          },
          "weeks": {
            "type": [
              "integer",
              "null"
            ]
          },
          "interests": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "consent": {
            "type": "boolean"
          },
          "consent_at": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "consent_text": {
            "type": [
              "string",
              "null"
            ]
          },
          "stage": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/OpportunityStage"
              },
              {
                "type": "null"
              }
            ],
            "description": "Stage of the student’s open opportunity (or the last closed one)."
          },
          "created_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
            "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
            "format": "date-time"
          },
          "opportunities": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "title",
                "stage",
                "booking_reference",
                "created_at",
                "updated_at",
                "closed_at"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "title": {
                  "type": "string"
                },
                "stage": {
                  "$ref": "#/components/schemas/OpportunityStage"
                },
                "booking_reference": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "created_at": {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
                  "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
                  "format": "date-time"
                },
                "updated_at": {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
                  "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
                  "format": "date-time"
                },
                "closed_at": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
                  "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
                  "format": "date-time"
                }
              }
            }
          },
          "quotes": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "number",
                "status",
                "valid_until",
                "booking_reference",
                "updated_at"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "number": {
                  "type": "string"
                },
                "status": {
                  "$ref": "#/components/schemas/QuoteStatus"
                },
                "valid_until": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date",
                  "description": "Date, `YYYY-MM-DD`."
                },
                "booking_reference": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "updated_at": {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
                  "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
                  "format": "date-time"
                }
              }
            }
          }
        }
      },
      "StudentList": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "items",
          "total",
          "page",
          "pages",
          "next"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Student"
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "All the results with these filters, in every page."
          },
          "page": {
            "type": "integer",
            "minimum": 1
          },
          "pages": {
            "type": "integer",
            "minimum": 1
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "Path and query of the next page with the same filters (e.g. `/api/public/v1/bookings?status=accepted&page=3`), or null on the last page."
          }
        }
      },
      "NewStudent": {
        "type": "object",
        "required": [
          "first_name",
          "email",
          "consent_text"
        ],
        "properties": {
          "first_name": {
            "type": "string",
            "maxLength": 120
          },
          "last_name": {
            "type": "string",
            "maxLength": 120
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "phone": {
            "type": "string",
            "maxLength": 40
          },
          "nationality": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$",
            "description": "ISO 3166-1 alpha-2."
          },
          "birth_date": {
            "type": "string",
            "format": "date"
          },
          "language": {
            "type": "string",
            "pattern": "^[a-z]{2}(-[A-Za-z]{2})?$",
            "description": "Language the student speaks (en, es, pt-BR…)."
          },
          "study_language": {
            "type": "string",
            "pattern": "^[a-z]{2}(-[A-Za-z]{2})?$",
            "description": "Language the student wants to study."
          },
          "start_from": {
            "type": "string",
            "format": "date"
          },
          "weeks": {
            "type": "integer",
            "minimum": 1,
            "maximum": 104
          },
          "budget": {
            "type": "integer",
            "minimum": 0,
            "description": "In cents of `currency`."
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Za-z]{3}$"
          },
          "interests": {
            "type": "string",
            "maxLength": 2000
          },
          "consent_text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 400,
            "description": "The exact consent text the student accepted on your website. Required."
          },
          "note": {
            "type": "string",
            "maxLength": 5000,
            "description": "Added to the student’s timeline."
          },
          "opportunity_title": {
            "type": "string",
            "maxLength": 190,
            "description": "Title of the opportunity created in your pipeline (default: «API enquiry»)."
          },
          "if_exists": {
            "type": "string",
            "enum": [
              "add",
              "replace",
              "skip"
            ],
            "default": "add",
            "description": "If a student with this email already exists: `add` fills only empty fields, `replace` overwrites them, `skip` changes nothing (and creates no opportunity)."
          },
          "tag": {
            "type": "string",
            "maxLength": 40,
            "description": "A tag added to the student."
          }
        }
      },
      "NewStudentResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "result",
          "opportunity_id"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The student."
          },
          "result": {
            "type": "string",
            "enum": [
              "created",
              "updated",
              "skipped"
            ]
          },
          "opportunity_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "The opportunity created (null when `skipped`)."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable error code (see the error catalogue)."
          },
          "message": {
            "type": "string",
            "description": "A readable message in the language of the request (Accept-Language or X-Fipeo-Lang: en, es, fr, it, de, pt)."
          },
          "reason": {
            "type": "string"
          },
          "reason_source": {
            "type": "string",
            "description": "The original English reason when `reason` was translated."
          },
          "scope": {
            "$ref": "#/components/schemas/Scope"
          },
          "retry_after": {
            "type": "integer",
            "description": "Seconds."
          },
          "organization_type": {
            "type": "string",
            "enum": [
              "agency",
              "school"
            ]
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "required": [
          "errors",
          "message"
        ],
        "properties": {
          "errors": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Field → message (translated)."
          },
          "errors_source": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "The original English messages when they were translated."
          },
          "message": {
            "type": "string"
          }
        }
      },
      "OAuthToken": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "access_token",
          "token_type",
          "expires_in",
          "scope"
        ],
        "properties": {
          "access_token": {
            "type": "string",
            "pattern": "^fpt_[A-Za-z0-9_-]{40,60}$"
          },
          "token_type": {
            "type": "string",
            "enum": [
              "Bearer"
            ]
          },
          "expires_in": {
            "type": "integer",
            "enum": [
              3600
            ]
          },
          "scope": {
            "type": "string",
            "description": "The granted scopes, separated by spaces."
          }
        }
      },
      "OAuthError": {
        "type": "object",
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "invalid_request",
              "invalid_client",
              "unsupported_grant_type",
              "invalid_scope"
            ]
          },
          "error_description": {
            "type": "string"
          }
        }
      },
      "WebhookBookingEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "type",
          "created_at",
          "api_version",
          "organization",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[0-9a-f]{32}$",
            "description": "Event id. A resend keeps the same id: use it to ignore duplicates."
          },
          "type": {
            "type": "string",
            "const": "booking.created"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z."
          },
          "api_version": {
            "type": "string",
            "const": "2026-11-09"
          },
          "organization": {
            "$ref": "#/components/schemas/Organization"
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "booking"
            ],
            "properties": {
              "booking": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "id",
                  "reference",
                  "status",
                  "previous_status",
                  "school_id",
                  "changed_at"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "reference": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "status": {
                    "$ref": "#/components/schemas/BookingStatus"
                  },
                  "previous_status": {
                    "oneOf": [
                      {
                        "$ref": "#/components/schemas/BookingStatus"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "school_id": {
                    "type": "integer"
                  },
                  "changed_at": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
                    "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        }
      },
      "WebhookBookingStatusEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "type",
          "created_at",
          "api_version",
          "organization",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[0-9a-f]{32}$",
            "description": "Event id. A resend keeps the same id: use it to ignore duplicates."
          },
          "type": {
            "type": "string",
            "const": "booking.status_changed"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z."
          },
          "api_version": {
            "type": "string",
            "const": "2026-11-09"
          },
          "organization": {
            "$ref": "#/components/schemas/Organization"
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "booking"
            ],
            "properties": {
              "booking": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "id",
                  "reference",
                  "status",
                  "previous_status",
                  "school_id",
                  "changed_at"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "reference": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "status": {
                    "$ref": "#/components/schemas/BookingStatus"
                  },
                  "previous_status": {
                    "oneOf": [
                      {
                        "$ref": "#/components/schemas/BookingStatus"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "school_id": {
                    "type": "integer"
                  },
                  "changed_at": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
                    "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        }
      },
      "WebhookQuoteAcceptedEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "type",
          "created_at",
          "api_version",
          "organization",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[0-9a-f]{32}$",
            "description": "Event id. A resend keeps the same id: use it to ignore duplicates."
          },
          "type": {
            "type": "string",
            "const": "quote.accepted"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z."
          },
          "api_version": {
            "type": "string",
            "const": "2026-11-09"
          },
          "organization": {
            "$ref": "#/components/schemas/Organization"
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "quote"
            ],
            "properties": {
              "quote": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "id",
                  "number",
                  "student_id",
                  "accepted_option",
                  "school",
                  "booking_reference",
                  "booking_status",
                  "accepted_at"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "number": {
                    "type": "string"
                  },
                  "student_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "accepted_option": {
                    "type": "integer"
                  },
                  "school": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "id",
                      "name"
                    ],
                    "properties": {
                      "id": {
                        "type": "integer"
                      },
                      "name": {
                        "type": "string"
                      }
                    }
                  },
                  "booking_reference": {
                    "type": "string"
                  },
                  "booking_status": {
                    "$ref": "#/components/schemas/BookingStatus"
                  },
                  "accepted_at": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
                    "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        }
      },
      "WebhookStudentCreatedEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "type",
          "created_at",
          "api_version",
          "organization",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[0-9a-f]{32}$",
            "description": "Event id. A resend keeps the same id: use it to ignore duplicates."
          },
          "type": {
            "type": "string",
            "const": "student.created"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z."
          },
          "api_version": {
            "type": "string",
            "const": "2026-11-09"
          },
          "organization": {
            "$ref": "#/components/schemas/Organization"
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "student"
            ],
            "properties": {
              "student": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "id",
                  "first_name",
                  "created_at"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "owner_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "first_name": {
                    "type": "string"
                  },
                  "last_name": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "email": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "phone": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "nationality": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "language": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "study_language": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "start_from": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date",
                    "description": "Date, `YYYY-MM-DD`."
                  },
                  "weeks": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "source": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "consent": {
                    "type": "boolean"
                  },
                  "created_at": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
                    "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        }
      },
      "WebhookMessageCreatedEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "type",
          "created_at",
          "api_version",
          "organization",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[0-9a-f]{32}$",
            "description": "Event id. A resend keeps the same id: use it to ignore duplicates."
          },
          "type": {
            "type": "string",
            "const": "message.created"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z."
          },
          "api_version": {
            "type": "string",
            "const": "2026-11-09"
          },
          "organization": {
            "$ref": "#/components/schemas/Organization"
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "message"
            ],
            "properties": {
              "message": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "id",
                  "conversation_id",
                  "booking_reference",
                  "subject",
                  "school",
                  "created_at",
                  "from"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "conversation_id": {
                    "type": "string"
                  },
                  "booking_reference": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "subject": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "school": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "id",
                      "name"
                    ],
                    "properties": {
                      "id": {
                        "type": "integer"
                      },
                      "name": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    }
                  },
                  "created_at": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
                    "description": "Date and time, ISO 8601 in UTC (`2026-11-11T10:00:00Z`).",
                    "format": "date-time"
                  },
                  "from": {
                    "type": "string",
                    "enum": [
                      "school",
                      "agency",
                      "channel"
                    ],
                    "description": "`school` (to an agency), `agency` or `channel` (to a school)."
                  }
                }
              }
            }
          }
        }
      },
      "WebhookPingEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "type",
          "created_at",
          "api_version",
          "organization",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[0-9a-f]{32}$",
            "description": "Event id. A resend keeps the same id: use it to ignore duplicates."
          },
          "type": {
            "type": "string",
            "const": "ping"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z."
          },
          "api_version": {
            "type": "string",
            "const": "2026-11-09"
          },
          "organization": {
            "$ref": "#/components/schemas/Organization"
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "message"
            ],
            "properties": {
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "WebhookAutomationEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "type",
          "created_at",
          "api_version",
          "organization",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[0-9a-f]{32}$",
            "description": "Event id. A resend keeps the same id: use it to ignore duplicates."
          },
          "type": {
            "type": "string",
            "const": "automation.run"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z."
          },
          "api_version": {
            "type": "string",
            "const": "2026-11-09"
          },
          "organization": {
            "$ref": "#/components/schemas/Organization"
          },
          "data": {
            "type": "object",
            "required": [
              "automation"
            ],
            "properties": {
              "automation": {
                "type": "object",
                "required": [
                  "trigger"
                ],
                "properties": {
                  "trigger": {
                    "type": "string",
                    "description": "The trigger of the automation (student_created, stage_changed, quote_sent, quote_opened, quote_accepted, quote_expiring, booking_confirmed, birthday, field_date)."
                  }
                }
              }
            }
          }
        }
      },
      "SchoolRef": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "description": "A school: the same object in the list and in the detail of bookings."
      }
    },
    "headers": {
      "RateLimit-Limit": {
        "description": "Requests allowed per window for this key or OAuth application (policy `api_key`).",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimit-Remaining": {
        "description": "Requests left in the current window.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RateLimit-Reset": {
        "description": "Seconds until the current window ends.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RateLimit-Policy": {
        "description": "The policy, as `limit;w=window seconds` (today `120;w=60`).",
        "schema": {
          "type": "string"
        }
      },
      "Idempotent-Replayed": {
        "description": "`true` when the response is the stored one of an earlier request with the same `Idempotency-Key`.",
        "schema": {
          "type": "string",
          "const": "true"
        }
      }
    }
  },
  "x-fipeo-scopes": {
    "catalog:read": {
      "organizations": [
        "agency"
      ],
      "routes": [
        "GET /schools",
        "GET /courses"
      ]
    },
    "quotes:read": {
      "organizations": [
        "agency"
      ],
      "routes": [
        "GET /quotes",
        "GET /quotes/{id}"
      ]
    },
    "bookings:read": {
      "organizations": [
        "agency",
        "school"
      ],
      "routes": [
        "GET /bookings",
        "GET /bookings/{reference}"
      ]
    },
    "students:read": {
      "organizations": [
        "agency"
      ],
      "routes": [
        "GET /students",
        "GET /students/{id}"
      ]
    },
    "students:write": {
      "organizations": [
        "agency"
      ],
      "routes": [
        "POST /students"
      ]
    }
  },
  "x-fipeo-rate-limits": [
    {
      "name": "api_key",
      "limit": 120,
      "window_seconds": 60,
      "per": "key or OAuth application",
      "applies_to": "every request"
    },
    {
      "name": "api_key_write",
      "limit": 30,
      "window_seconds": 60,
      "per": "key or OAuth application",
      "applies_to": "POST /students"
    },
    {
      "name": "api_key_ip",
      "limit": 600,
      "window_seconds": 60,
      "per": "IP address",
      "applies_to": "every request, before the key is checked"
    },
    {
      "name": "oauth_token_ip",
      "limit": 60,
      "window_seconds": 60,
      "per": "IP address",
      "applies_to": "POST /oauth/token and /oauth/revoke"
    },
    {
      "name": "oauth_token_client",
      "limit": 30,
      "window_seconds": 60,
      "per": "client_id",
      "applies_to": "POST /oauth/token and /oauth/revoke"
    }
  ],
  "x-fipeo-error-codes": [
    {
      "code": "unauthenticated",
      "status": 401,
      "meaning": "No key, or the key/token is malformed, revoked, expired, or its account is no longer active."
    },
    {
      "code": "insufficient_scope",
      "status": 403,
      "meaning": "The key is valid but lacks the scope of this route (see `scope`)."
    },
    {
      "code": "dpa_required",
      "status": 403,
      "meaning": "students and quotes: the organization has not accepted the data processing agreement in the panel yet."
    },
    {
      "code": "not_found",
      "status": 404,
      "meaning": "It does not exist or it is not yours. Also every route while the API is off, any path that does not match a route (e.g. a malformed id), and GET /bookings/{reference} with a school key."
    },
    {
      "code": "method_not_allowed",
      "status": 405,
      "meaning": "The method is not allowed on this path (see `Allow`)."
    },
    {
      "code": "invalid_json",
      "status": 400,
      "meaning": "The body is not valid JSON."
    },
    {
      "code": null,
      "status": 422,
      "meaning": "Validation: `errors` maps each field to its message (no `error` code)."
    },
    {
      "code": "idempotency_key_reused",
      "status": 422,
      "meaning": "This `Idempotency-Key` was already used (in the last 24 hours) with a different request."
    },
    {
      "code": "idempotency_key_in_use",
      "status": 409,
      "meaning": "A request with this `Idempotency-Key` is still being processed: retry in a moment."
    },
    {
      "code": "too_many_requests",
      "status": 429,
      "meaning": "Rate limit reached; wait `retry_after` seconds (also in `Retry-After`)."
    },
    {
      "code": "busy",
      "status": 503,
      "meaning": "Overloaded for a moment; retry after `retry_after` seconds."
    },
    {
      "code": "invalid_request",
      "status": 400,
      "meaning": "OAuth: missing or duplicated parameters (e.g. client credentials both in Basic and in the body), or too many active tokens."
    },
    {
      "code": "invalid_client",
      "status": 401,
      "meaning": "OAuth: the client could not be authenticated."
    },
    {
      "code": "unsupported_grant_type",
      "status": 400,
      "meaning": "OAuth: only `client_credentials` is supported."
    },
    {
      "code": "invalid_scope",
      "status": 400,
      "meaning": "OAuth: a requested scope is not one of the application’s."
    }
  ],
  "x-fipeo-webhooks": {
    "signature": "X-Fipeo-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw body)>. Compare in constant time and reject t more than 300 seconds away from your clock.",
    "secret": "whsec_…, shown once when you create the webhook or ask for a new secret (the old one stops working with the next delivery).",
    "timeout_seconds": 10,
    "retries_minutes": [
      1,
      5,
      15,
      60,
      240,
      720,
      1440
    ],
    "max_attempts": 8,
    "auto_disable_after_consecutive_failures": 20,
    "max_webhooks_per_organization": 10,
    "url_rules": "https:// only, public address (no private, local or reserved IP), port 443 or 8443, no user, password or #fragment, up to 500 characters; up to 5 redirects, each checked again.",
    "user_agent": "Fipeo-Webhooks/1.0",
    "events": {
      "agency": [
        "booking.created",
        "booking.status_changed",
        "quote.accepted",
        "student.created",
        "message.created"
      ],
      "school": [
        "booking.created",
        "booking.status_changed",
        "message.created"
      ]
    }
  }
}
