API reference
Every route of the API, generated from the OpenAPI 3.1 specification. The base URL is https://fipeo.net/api/public/v1.
Conventions
Versions
The version is in the path (/v1). v1 was settled before the launch; within v1 we only add things and your client must ignore unknown fields. Webhook bodies carry api_version (today 2026-11-09).
Formats
JSON in UTF-8. Amounts: integers in cents of currency. Dates: YYYY-MM-DD. Date-times: ISO 8601 in UTC with Z (2026-11-11T10:00:00Z), in responses and in webhooks. Statuses: stable English codes. Every response carries Cache-Control: no-store.
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 on the last one. 20 per page in /courses, 50 in the rest. Nothing is cut: follow next until it is null.
Idempotency
Send Idempotency-Key (1 to 255 visible characters, a UUID for example) with POST /students: for 24 hours, the same key with the same request returns the stored answer without running it again (Idempotent-Replayed: true); with a different request it answers 422 idempotency_key_reused, and while the first one is still running, 409 idempotency_key_in_use. Errors are not stored, so you can retry them with the same key. The OAuth token endpoint follows RFC 6749 and ignores it. Webhooks keep their event id when they are resent.
Errors
Errors are JSON with a stable error code and a 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.
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthenticated | No key, or the key/token is malformed, revoked, expired, or its account is no longer active. |
| 403 | insufficient_scope | The key is valid but lacks the scope of this route (see scope). |
| 403 | dpa_required | students and quotes: the organization has not accepted the data processing agreement in the panel yet. |
| 404 | not_found | 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. |
| 405 | method_not_allowed | The method is not allowed on this path (see Allow). |
| 400 | invalid_json | The body is not valid JSON. |
| 422 | errors | Validation: errors maps each field to its message (no error code). |
| 422 | idempotency_key_reused | This Idempotency-Key was already used (in the last 24 hours) with a different request. |
| 409 | idempotency_key_in_use | A request with this Idempotency-Key is still being processed: retry in a moment. |
| 429 | too_many_requests | Rate limit reached; wait retry_after seconds (also in Retry-After). |
| 503 | busy | Overloaded for a moment; retry after retry_after seconds. |
| 400 | invalid_request | OAuth: missing or duplicated parameters (e.g. client credentials both in Basic and in the body), or too many active tokens. |
| 401 | invalid_client | OAuth: the client could not be authenticated. |
| 400 | unsupported_grant_type | OAuth: only client_credentials is supported. |
| 400 | invalid_scope | OAuth: a requested scope is not one of the application’s. |
Rate limits
| Limit | Per | Applies to |
|---|---|---|
| 120 per minute | key or OAuth application | every request |
| 30 per minute | key or OAuth application | POST /students |
| 600 per minute | IP address | every request, before the key is checked |
| 60 per minute | IP address | POST /oauth/token and /oauth/revoke |
| 30 per minute | client_id | POST /oauth/token and /oauth/revoke |
Endpoints
- GET/me
- GET/schools
- GET/courses
- GET/quotes
- GET/quotes/{id}
- GET/bookings
- GET/bookings/{reference}
- GET/students
- POST/students
- GET/students/{id}
- POST/oauth/token
- POST/oauth/revoke
GET/me
The key and its organization
Scope: noneFor: agencies and schools
Who you are: the organization that owns the key (or OAuth token), the key and its scopes. Needs no scope.
Parameters
| Field | Type | Description |
|---|---|---|
| Accept-Language (header) | string | Language of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent. |
Responses
200MeOK401Errorunauthenticated: 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.404Errornot_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), andGET /bookings/{reference}with a school key.429Errortoo_many_requests: rate limit reached (withreasonandretry_afterin seconds).503Errorbusy: Fipeo is overloaded for a moment. Retry afterretry_afterseconds.
GET/schools
Schools you are connected to
Scope: catalog:readFor: agencies
The schools with an active connection with your agency, 50 per page.
Parameters
| Field | Type | Description |
|---|---|---|
| page (query) | integer | Page number, from 1. |
| Accept-Language (header) | string | Language of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent. |
Responses
200SchoolListOK401Errorunauthenticated: 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.403Errorinsufficient_scope(withscope: the key lacks the permission this route needs) ordpa_required(students and quotes: the organization has not accepted the data processing agreement yet; withorganization_type).404Errornot_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), andGET /bookings/{reference}with a school key.422ValidationErrorA field or a filter is not valid (alsopageandstatus):errorsmaps each field to its message. The same for agency and school keys.429Errortoo_many_requests: rate limit reached (withreasonandretry_afterin seconds).503Errorbusy: Fipeo is overloaded for a moment. Retry afterretry_afterseconds.
GET/courses
Search courses with the price for the student
Scope: catalog:readFor: agencies
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
| Field | Type | Description |
|---|---|---|
| school_id (query) | integer | Only this school (its id). |
| country (query) | string | ISO 3166-1 alpha-2 country of the school. |
| city (query) | string | City of the school. |
| language (query) | string | Language taught (en, es…). |
| type (query) | string | Course type (general, intensive…). |
| level (query) | string | CEFR level of the student."A1""A2""B1""B2""C1""C2" |
| weeks (query) | integer | Number of weeks (default: the minimum of each course). |
| start (query) | string (date) | Start date (default: the Monday about two weeks from today). |
| age (query) | integer | Age of the student. |
| accommodation (query) | boolean | Only schools that offer accommodation. |
| lang (query) | string | Language of the course names."en""es""fr""it""de""pt" |
| page (query) | integer | Page number, from 1. |
| Accept-Language (header) | string | Language of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent. |
Responses
200CourseListOK401Errorunauthenticated: 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.403Errorinsufficient_scope(withscope: the key lacks the permission this route needs) ordpa_required(students and quotes: the organization has not accepted the data processing agreement yet; withorganization_type).404Errornot_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), andGET /bookings/{reference}with a school key.422ValidationErrorA field or a filter is not valid (alsopageandstatus):errorsmaps each field to its message. The same for agency and school keys.429Errortoo_many_requests: rate limit reached (withreasonandretry_afterin seconds).503Errorbusy: Fipeo is overloaded for a moment. Retry afterretry_afterseconds.
GET/quotes
List quotes
Scope: quotes:readFor: agencies
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
| Field | Type | Description |
|---|---|---|
| status (query) | QuoteStatus | Only quotes in this status. Any other value gives 422. |
| student_id (query) | string (uuid) | Only the quotes of this student. |
| page (query) | integer | Page number, from 1. |
| Accept-Language (header) | string | Language of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent. |
Responses
200QuoteListOK401Errorunauthenticated: 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.403Errorinsufficient_scope(withscope: the key lacks the permission this route needs) ordpa_required(students and quotes: the organization has not accepted the data processing agreement yet; withorganization_type).404Errornot_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), andGET /bookings/{reference}with a school key.422ValidationErrorA field or a filter is not valid (alsopageandstatus):errorsmaps each field to its message. The same for agency and school keys.429Errortoo_many_requests: rate limit reached (withreasonandretry_afterin seconds).503Errorbusy: Fipeo is overloaded for a moment. Retry afterretry_afterseconds.
GET/quotes/{id}
Get a quote
Scope: quotes:readFor: agencies
Parameters
| Field | Type | Description |
|---|---|---|
| id (path)* | string (uuid) | Quote id. |
| Accept-Language (header) | string | Language of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent. |
Responses
200QuoteOK401Errorunauthenticated: 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.403Errorinsufficient_scope(withscope: the key lacks the permission this route needs) ordpa_required(students and quotes: the organization has not accepted the data processing agreement yet; withorganization_type).404Errornot_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), andGET /bookings/{reference}with a school key.429Errortoo_many_requests: rate limit reached (withreasonandretry_afterin seconds).503Errorbusy: Fipeo is overloaded for a moment. Retry afterretry_afterseconds.
GET/bookings
List bookings
Scope: bookings:readFor: agencies and schools
Agency key: your bookings, newest first, as BookingSummary. School key: your booking inbox, newest first, as SchoolBooking. 50 per page.
Parameters
| Field | Type | Description |
|---|---|---|
| status (query) | BookingStatus | Only bookings in this status. Any other value gives 422, with an agency or a school key. |
| page (query) | integer | Page number, from 1. |
| Accept-Language (header) | string | Language of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent. |
Responses
200BookingList | SchoolBookingListOK401Errorunauthenticated: 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.403Errorinsufficient_scope(withscope: the key lacks the permission this route needs) ordpa_required(students and quotes: the organization has not accepted the data processing agreement yet; withorganization_type).404Errornot_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), andGET /bookings/{reference}with a school key.422ValidationErrorA field or a filter is not valid (alsopageandstatus):errorsmaps each field to its message. The same for agency and school keys.429Errortoo_many_requests: rate limit reached (withreasonandretry_afterin seconds).503Errorbusy: Fipeo is overloaded for a moment. Retry afterretry_afterseconds.
GET/bookings/{reference}
Get a booking
Scope: bookings:readFor: agencies
One booking of your agency, with its lines and participants. Agency keys only (a school key gets 404).
Parameters
| Field | Type | Description |
|---|---|---|
| reference (path)* | string | Booking reference. |
| Accept-Language (header) | string | Language of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent. |
Responses
200BookingOK401Errorunauthenticated: 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.403Errorinsufficient_scope(withscope: the key lacks the permission this route needs) ordpa_required(students and quotes: the organization has not accepted the data processing agreement yet; withorganization_type).404Errornot_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), andGET /bookings/{reference}with a school key.429Errortoo_many_requests: rate limit reached (withreasonandretry_afterin seconds).503Errorbusy: Fipeo is overloaded for a moment. Retry afterretry_afterseconds.
GET/students
List students
Scope: students:readFor: agencies
The students of your CRM, 50 per page. Internal notes never leave Fipeo.
Parameters
| Field | Type | Description |
|---|---|---|
| q (query) | string | Search in name, email and phone. |
| tag (query) | string | Only students with this tag. |
| consent (query) | string | Only students who gave (yes) or did not give (no) consent."yes""no" |
| page (query) | integer | Page number, from 1. |
| Accept-Language (header) | string | Language of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent. |
Responses
200StudentListOK401Errorunauthenticated: 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.403Errorinsufficient_scope(withscope: the key lacks the permission this route needs) ordpa_required(students and quotes: the organization has not accepted the data processing agreement yet; withorganization_type).404Errornot_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), andGET /bookings/{reference}with a school key.422ValidationErrorA field or a filter is not valid (alsopageandstatus):errorsmaps each field to its message. The same for agency and school keys.429Errortoo_many_requests: rate limit reached (withreasonandretry_afterin seconds).503Errorbusy: Fipeo is overloaded for a moment. Retry afterretry_afterseconds.
POST/students
Add a student
Scope: students:writeFor: agencies
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
| Field | Type | Description |
|---|---|---|
| Idempotency-Key (header) | string | 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. |
| Accept-Language (header) | string | Language of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent. |
Request body application/json · NewStudent
{
"first_name": "Lucía",
"last_name": "Pérez",
"email": "[email protected]",
"nationality": "AR",
"consent_text": "I agree that Agencia Sol keeps my details to send me course offers.",
"opportunity_title": "Dublin summer"
}Responses
201NewStudentResultCreated, updated or skipped (seeresult).400Errorinvalid_json: the body is not valid JSON.401Errorunauthenticated: 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.403Errorinsufficient_scope(withscope: the key lacks the permission this route needs) ordpa_required(students and quotes: the organization has not accepted the data processing agreement yet; withorganization_type).404Errornot_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), andGET /bookings/{reference}with a school key.409Erroridempotency_key_in_use: a request with the sameIdempotency-Keyis still being processed. Retry in a moment.422ValidationError | ErrorA field is not valid (errors: field → message), oridempotency_key_reused: thisIdempotency-Keywas already used with a different request.429Errortoo_many_requests: rate limit reached (withreasonandretry_afterin seconds).503Errorbusy: Fipeo is overloaded for a moment. Retry afterretry_afterseconds.
GET/students/{id}
Get a student
Scope: students:readFor: agencies
One student with their opportunities and quotes.
Parameters
| Field | Type | Description |
|---|---|---|
| id (path)* | string (uuid) | Student id. |
| Accept-Language (header) | string | Language of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent. |
Responses
200StudentDetailOK401Errorunauthenticated: 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.403Errorinsufficient_scope(withscope: the key lacks the permission this route needs) ordpa_required(students and quotes: the organization has not accepted the data processing agreement yet; withorganization_type).404Errornot_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), andGET /bookings/{reference}with a school key.429Errortoo_many_requests: rate limit reached (withreasonandretry_afterin seconds).503Errorbusy: Fipeo is overloaded for a moment. Retry afterretry_afterseconds.
POST/oauth/token
Get an OAuth access token
Scope: —For: agencies and schools
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.
Request body application/x-www-form-urlencoded · object
| Field | Type | Description |
|---|---|---|
| grant_type* | string | "client_credentials" |
| scope | string | Scopes separated by spaces, a subset of the application’s (empty = all of them). |
| client_id | string | |
| client_secret | string |
Request body application/json · object
| Field | Type | Description |
|---|---|---|
| grant_type* | string | "client_credentials" |
| scope | string | |
| client_id | string | |
| client_secret | string |
Responses
200OAuthTokenThe token.400OAuthErrorinvalid_request,unsupported_grant_typeorinvalid_scope(RFC 6749 §5.2).401OAuthErrorinvalid_client: unknown client, wrong secret, revoked or expired application, or account no longer active. With Basic, alsoWWW-Authenticate: Basic realm="fipeo".404Errornot_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), andGET /bookings/{reference}with a school key.429Errortoo_many_requests: rate limit reached (withreasonandretry_afterin seconds).
POST/oauth/revoke
Revoke an OAuth access token
Scope: —For: agencies and schools
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.
Request body application/x-www-form-urlencoded · object
| Field | Type | Description |
|---|---|---|
| token* | string | |
| client_id | string | |
| client_secret | string |
Request body application/json · object
| Field | Type | Description |
|---|---|---|
| token* | string | |
| client_id | string | |
| client_secret | string |
Responses
200objectRevoked (or nothing to revoke).400OAuthErrorinvalid_request.401OAuthErrorinvalid_client.404Errornot_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), andGET /bookings/{reference}with a school key.429Errortoo_many_requests: rate limit reached (withreasonandretry_afterin seconds).
Webhooks
How to set them up and verify them: webhooks guide.
Headers
| Field | Type | Description |
|---|---|---|
| X-Fipeo-Signature* | string | t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body" with your webhook secret> |
| X-Fipeo-Event* | string | The event type, as in type. |
| X-Fipeo-Event-Id* | string | The event id, as in id (the same in a resend). |
| X-Fipeo-Delivery* | string | The id of this delivery (a resend has a new one). |
booking.created
A booking was created · For: agencies and schools · WebhookBookingEvent
booking.status_changed
A booking changed status · For: agencies and schools · WebhookBookingStatusEvent
message.created
A new message in a conversation · For: agencies and schools · WebhookMessageCreatedEvent
quote.accepted
A student accepted a quote · For: agencies · WebhookQuoteAcceptedEvent
student.created
A student was added to the CRM · For: agencies · WebhookStudentCreatedEvent
automation.run
An automation of the CRM ran its «webhook» action · For: agencies · WebhookAutomationEvent
ping
Test event («Send a test» in the panel) · For: agencies and schools · WebhookPingEvent
Schemas
Organization
| Field | Type | Description |
|---|---|---|
| type* | string | "agency""school" |
| id* | string | integer | Agency: the UUID of its account. School: its numeric id. |
Me
| Field | Type | Description |
|---|---|---|
| organization* | Organization | |
| key* | object | |
| key.id* | string (uuid) | Key id (for OAuth tokens: the id of the OAuth application). |
| key.name* | string | |
| key.prefix* | string | First 12 characters of the key (or of the OAuth client id), to recognise it. |
| key.expires_at* | string | null (date-time) | When the key (or the OAuth token) expires; null = never. Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| scopes* | array of Scope |
Scope
string "catalog:read""quotes:read""bookings:read""students:read""students:write"
ConnectedSchool
| Field | Type | Description |
|---|---|---|
| connection_id* | string (uuid) | The connection between your agency and the school. |
| status* | string | Only active connections are listed."active" |
| can_book* | boolean | Whether your agency can send bookings to this school today. |
| school* | object | |
| school.id* | integer | |
| school.name* | string | |
| activated_at* | string | null (date-time) | When the connection became active. Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
SchoolList
| Field | Type | Description |
|---|---|---|
| items* | array of ConnectedSchool | |
| total* | integer | All the results with these filters, in every page. |
| page* | integer | |
| pages* | integer | |
| next* | string | null | 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
| Field | Type | Description |
|---|---|---|
| school* | object | |
| school.id* | integer | |
| school.name* | string | |
| school.city* | string | null | |
| school.country* | string | null | ISO 3166-1 alpha-2. |
| school.accommodation* | boolean | Whether the school offers accommodation. |
| course* | object | |
| course.id* | integer | |
| course.name* | string | |
| course.type* | string | null | |
| course.language* | string | null | |
| course.lessons_per_week* | integer | null | |
| course.min_age* | integer | null | |
| course.weeks_min* | integer | null | |
| course.weeks_max* | integer | null | |
| start* | string (date) | Start date used for the price. |
| weeks* | integer | |
| price* | object | |
| price.status* | string | 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. |
| price.total* | integer | null | What the student pays. null when there is no price. In cents (minor units) of currency. |
| price.currency* | string | |
| price.availability* | string | "available""on_request""sold_out" |
| price.instant* | boolean | true: the booking is confirmed at once; false: it is a request the school answers. |
CourseList
| Field | Type | Description |
|---|---|---|
| items* | array of CourseResult | |
| total* | integer | All the results with these filters, in every page. |
| page* | integer | |
| pages* | integer | |
| next* | string | null | 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
string "draft""sent""opened""accepted""expired""withdrawn"
QuoteSummary
| Field | Type | Description |
|---|---|---|
| id* | string (uuid) | |
| owner_id* | string (uuid) | The user of your agency responsible for the quote. |
| number* | string | |
| student_id* | string (uuid) | |
| student* | string | null | Full name of the student. |
| opportunity_id* | string | null (uuid) | |
| status* | QuoteStatus | |
| language* | string | |
| valid_until* | string | null (date) | Date, YYYY-MM-DD. |
| public_url* | string | null (uri) | The page where the student sees and accepts the quote (null while it is a draft). |
| accepted_option* | integer | null | |
| booking_reference* | string | null | |
| created_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| updated_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| sent_at* | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| opened_at* | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| accepted_at* | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| option_count* | integer | |
| from_total* | integer | null | The lowest option total for the student. In cents (minor units) of currency. |
| currency* | string | null |
QuoteList
| Field | Type | Description |
|---|---|---|
| items* | array of QuoteSummary | |
| total* | integer | All the results with these filters, in every page. |
| page* | integer | |
| pages* | integer | |
| next* | string | null | 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
| Field | Type | Description |
|---|---|---|
| line | integer | |
| name | string | |
| text | string | null | |
| type | string | |
| start | string | null (date) | Date, YYYY-MM-DD. |
| end | string | null (date) | Date, YYYY-MM-DD. |
| units | integer | null |
QuoteOption
| Field | Type | Description |
|---|---|---|
| number* | integer | |
| title | string | null | |
| currency | string | |
| availability | string | null | |
| unconfirmed_prices | boolean | |
| school* | object | |
| school.id | integer | |
| school.name | string | |
| school.city | string | null | |
| school.country | string | null | |
| total* | integer | null | What the student pays for this option. In cents (minor units) of currency. |
| lines* | array of Line |
Quote
| Field | Type | Description |
|---|---|---|
| id* | string (uuid) | |
| owner_id* | string (uuid) | |
| number* | string | |
| student_id* | string (uuid) | |
| student* | string | null | Full name of the student. |
| opportunity_id* | string | null (uuid) | |
| status* | QuoteStatus | |
| language* | string | |
| valid_until* | string | null (date) | Date, YYYY-MM-DD. |
| public_url* | string | null (uri) | |
| accepted_option* | integer | null | |
| booking_reference* | string | null | |
| created_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| updated_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| sent_at* | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| opened_at* | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| accepted_at* | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| options* | array of QuoteOption |
BookingStatus
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).
string "new""pending""alternative_proposed""accepted""declined""cancelled""expired"
BookingSummary
| Field | Type | Description |
|---|---|---|
| id* | string | |
| reference* | string | |
| school* | SchoolRef | |
| status* | BookingStatus | |
| created_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| updated_at* | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| start* | string | null (date) | Start of the first line. |
| end* | string | null (date) | End of the first line. |
| first_line* | string | null | |
| total* | integer | null | Total of the booking (what the student pays). In cents (minor units) of currency. |
| currency* | string | null | |
| owner_id* | string |
BookingList
| Field | Type | Description |
|---|---|---|
| items* | array of BookingSummary | |
| total* | integer | All the results with these filters, in every page. |
| page* | integer | |
| pages* | integer | |
| next* | string | null | 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
| Field | Type | Description |
|---|---|---|
| number | integer | |
| first_name | string | null | |
| last_name | string | null | |
| name | string | null | |
| nationality | string | null | |
| birth_date | string | null (date) | Date, YYYY-MM-DD. |
Booking
| Field | Type | Description |
|---|---|---|
| id* | string | |
| reference* | string | |
| school* | SchoolRef | |
| status* | BookingStatus | |
| created_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| updated_at* | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| owner_id* | string | |
| total* | integer | null | Total of the booking (what the student pays). In cents (minor units) of currency. |
| currency* | string | null | |
| lines* | array of Line | What was booked, line by line (course, accommodation, extras), without amounts. |
| participants* | array of Participant |
SchoolBooking
| Field | Type | Description |
|---|---|---|
| id* | string | |
| reference* | string | |
| status* | BookingStatus | |
| modality* | string | on_request: a request you answer; instant: booked at once on your allotment."on_request""instant" |
| created_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| seen_at* | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| resolved_at* | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| student* | string | |
| nationality* | string | null | |
| first_item* | string | null | |
| start* | string | null (date) | Date, YYYY-MM-DD. |
| end* | string | null (date) | Date, YYYY-MM-DD. |
| units* | integer | null | |
| total* | integer | null | Gross total of the booking. In cents (minor units) of currency. |
| currency* | string | null | |
| channel* | string | Where the booking came from: agency (an agency on Fipeo), languagebookings, direct (your website or booking form) or another channel code. |
SchoolBookingList
| Field | Type | Description |
|---|---|---|
| items* | array of SchoolBooking | |
| total* | integer | All the results with these filters, in every page. |
| page* | integer | |
| pages* | integer | |
| next* | string | null | 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
string "new""contacted""quote_sent""booked""lost"
Student
| Field | Type | Description |
|---|---|---|
| id* | string (uuid) | |
| owner_id | string (uuid) | The user of your agency responsible for the student. |
| first_name* | string | |
| last_name | string | null | |
| email* | string | null (email) | |
| phone | string | null | |
| nationality | string | null | ISO 3166-1 alpha-2. |
| birth_date | string | null (date) | Date, YYYY-MM-DD. |
| age | integer | null | |
| language | string | null | |
| study_language | string | null | |
| level | string | null | |
| budget | integer | null | Budget. In cents (minor units) of currency. |
| currency | string | null | |
| start_from | string | null (date) | Date, YYYY-MM-DD. |
| start_to | string | null (date) | Date, YYYY-MM-DD. |
| weeks | integer | null | |
| interests | string | null | |
| source | string | null | |
| tags | array of string | |
| consent* | boolean | |
| consent_at | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| consent_text | string | null | |
| stage | OpportunityStage | null | Stage of the student’s open opportunity (or the last closed one). |
| created_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| updated_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
StudentDetail
| Field | Type | Description |
|---|---|---|
| id* | string (uuid) | |
| owner_id | string (uuid) | The user of your agency responsible for the student. |
| first_name* | string | |
| last_name | string | null | |
| email* | string | null (email) | |
| phone | string | null | |
| nationality | string | null | ISO 3166-1 alpha-2. |
| birth_date | string | null (date) | Date, YYYY-MM-DD. |
| age | integer | null | |
| language | string | null | |
| study_language | string | null | |
| level | string | null | |
| budget | integer | null | Budget. In cents (minor units) of currency. |
| currency | string | null | |
| start_from | string | null (date) | Date, YYYY-MM-DD. |
| start_to | string | null (date) | Date, YYYY-MM-DD. |
| weeks | integer | null | |
| interests | string | null | |
| source | string | null | |
| tags | array of string | |
| consent* | boolean | |
| consent_at | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| consent_text | string | null | |
| stage | OpportunityStage | null | Stage of the student’s open opportunity (or the last closed one). |
| created_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| updated_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| opportunities* | array of object | |
| opportunities[].id* | string (uuid) | |
| opportunities[].title* | string | |
| opportunities[].stage* | OpportunityStage | |
| opportunities[].booking_reference* | string | null | |
| opportunities[].created_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| opportunities[].updated_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| opportunities[].closed_at* | string | null (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| quotes* | array of object | |
| quotes[].id* | string (uuid) | |
| quotes[].number* | string | |
| quotes[].status* | QuoteStatus | |
| quotes[].valid_until* | string | null (date) | Date, YYYY-MM-DD. |
| quotes[].booking_reference* | string | null | |
| quotes[].updated_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
StudentList
| Field | Type | Description |
|---|---|---|
| items* | array of Student | |
| total* | integer | All the results with these filters, in every page. |
| page* | integer | |
| pages* | integer | |
| next* | string | null | 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
| Field | Type | Description |
|---|---|---|
| first_name* | string | |
| last_name | string | |
| email* | string (email) | |
| phone | string | |
| nationality | string | ISO 3166-1 alpha-2. |
| birth_date | string (date) | |
| language | string | Language the student speaks (en, es, pt-BR…). |
| study_language | string | Language the student wants to study. |
| start_from | string (date) | |
| weeks | integer | |
| budget | integer | In cents of currency. |
| currency | string | |
| interests | string | |
| consent_text* | string | The exact consent text the student accepted on your website. Required. |
| note | string | Added to the student’s timeline. |
| opportunity_title | string | Title of the opportunity created in your pipeline (default: «API enquiry»). |
| if_exists | string | If a student with this email already exists: add fills only empty fields, replace overwrites them, skip changes nothing (and creates no opportunity)."add""replace""skip" |
| tag | string | A tag added to the student. |
NewStudentResult
| Field | Type | Description |
|---|---|---|
| id* | string (uuid) | The student. |
| result* | string | "created""updated""skipped" |
| opportunity_id* | string | null (uuid) | The opportunity created (null when skipped). |
Error
| Field | Type | Description |
|---|---|---|
| error | string | Stable error code (see the error catalogue). |
| message* | string | A readable message in the language of the request (Accept-Language or X-Fipeo-Lang: en, es, fr, it, de, pt). |
| reason | string | |
| reason_source | string | The original English reason when reason was translated. |
| scope | Scope | |
| retry_after | integer | Seconds. |
| organization_type | string | "agency""school" |
ValidationError
| Field | Type | Description |
|---|---|---|
| errors* | object | Field → message (translated). |
| errors_source | object | The original English messages when they were translated. |
| message* | string |
OAuthToken
| Field | Type | Description |
|---|---|---|
| access_token* | string | |
| token_type* | string | "Bearer" |
| expires_in* | integer | 3600 |
| scope* | string | The granted scopes, separated by spaces. |
OAuthError
| Field | Type | Description |
|---|---|---|
| error* | string | "invalid_request""invalid_client""unsupported_grant_type""invalid_scope" |
| error_description | string |
WebhookBookingEvent
| Field | Type | Description |
|---|---|---|
| id* | string | Event id. A resend keeps the same id: use it to ignore duplicates. |
| type* | "booking.created" | |
| created_at* | string (date-time) | ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z. |
| api_version* | "2026-11-09" | |
| organization* | Organization | |
| data* | object | |
| data.booking* | object | |
| data.booking.id* | string | |
| data.booking.reference* | string | null | |
| data.booking.status* | BookingStatus | |
| data.booking.previous_status* | BookingStatus | null | |
| data.booking.school_id* | integer | |
| data.booking.changed_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
WebhookBookingStatusEvent
| Field | Type | Description |
|---|---|---|
| id* | string | Event id. A resend keeps the same id: use it to ignore duplicates. |
| type* | "booking.status_changed" | |
| created_at* | string (date-time) | ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z. |
| api_version* | "2026-11-09" | |
| organization* | Organization | |
| data* | object | |
| data.booking* | object | |
| data.booking.id* | string | |
| data.booking.reference* | string | null | |
| data.booking.status* | BookingStatus | |
| data.booking.previous_status* | BookingStatus | null | |
| data.booking.school_id* | integer | |
| data.booking.changed_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
WebhookQuoteAcceptedEvent
| Field | Type | Description |
|---|---|---|
| id* | string | Event id. A resend keeps the same id: use it to ignore duplicates. |
| type* | "quote.accepted" | |
| created_at* | string (date-time) | ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z. |
| api_version* | "2026-11-09" | |
| organization* | Organization | |
| data* | object | |
| data.quote* | object | |
| data.quote.id* | string (uuid) | |
| data.quote.number* | string | |
| data.quote.student_id* | string (uuid) | |
| data.quote.accepted_option* | integer | |
| data.quote.school* | object | |
| data.quote.school.id* | integer | |
| data.quote.school.name* | string | |
| data.quote.booking_reference* | string | |
| data.quote.booking_status* | BookingStatus | |
| data.quote.accepted_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
WebhookStudentCreatedEvent
| Field | Type | Description |
|---|---|---|
| id* | string | Event id. A resend keeps the same id: use it to ignore duplicates. |
| type* | "student.created" | |
| created_at* | string (date-time) | ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z. |
| api_version* | "2026-11-09" | |
| organization* | Organization | |
| data* | object | |
| data.student* | object | |
| data.student.id* | string (uuid) | |
| data.student.owner_id | string (uuid) | |
| data.student.first_name* | string | |
| data.student.last_name | string | null | |
| data.student.email | string | null | |
| data.student.phone | string | null | |
| data.student.nationality | string | null | |
| data.student.language | string | null | |
| data.student.study_language | string | null | |
| data.student.start_from | string | null (date) | Date, YYYY-MM-DD. |
| data.student.weeks | integer | null | |
| data.student.source | string | null | |
| data.student.tags | array of string | |
| data.student.consent | boolean | |
| data.student.created_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
WebhookMessageCreatedEvent
| Field | Type | Description |
|---|---|---|
| id* | string | Event id. A resend keeps the same id: use it to ignore duplicates. |
| type* | "message.created" | |
| created_at* | string (date-time) | ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z. |
| api_version* | "2026-11-09" | |
| organization* | Organization | |
| data* | object | |
| data.message* | object | |
| data.message.id* | string | |
| data.message.conversation_id* | string | |
| data.message.booking_reference* | string | null | |
| data.message.subject* | string | null | |
| data.message.school* | object | |
| data.message.school.id* | integer | |
| data.message.school.name* | string | null | |
| data.message.created_at* | string (date-time) | Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z). |
| data.message.from* | string | school (to an agency), agency or channel (to a school)."school""agency""channel" |
WebhookPingEvent
| Field | Type | Description |
|---|---|---|
| id* | string | Event id. A resend keeps the same id: use it to ignore duplicates. |
| type* | "ping" | |
| created_at* | string (date-time) | ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z. |
| api_version* | "2026-11-09" | |
| organization* | Organization | |
| data* | object | |
| data.message* | string |
WebhookAutomationEvent
| Field | Type | Description |
|---|---|---|
| id* | string | Event id. A resend keeps the same id: use it to ignore duplicates. |
| type* | "automation.run" | |
| created_at* | string (date-time) | ISO 8601 in UTC, e.g. 2026-11-09T10:00:00Z. |
| api_version* | "2026-11-09" | |
| organization* | Organization | |
| data* | object | |
| data.automation* | object | |
| data.automation.trigger* | string | The trigger of the automation (student_created, stage_changed, quote_sent, quote_opened, quote_accepted, quote_expiring, booking_confirmed, birthday, field_date). |
SchoolRef
A school: the same object in the list and in the detail of bookings.
| Field | Type | Description |
|---|---|---|
| id* | integer | |
| name* | string | null |