Referencia de la API
Todas las rutas de la API, generadas desde la especificación OpenAPI 3.1. La URL base es https://fipeo.net/api/public/v1.
Las descripciones de la referencia están en inglés, como la especificación.
Convenciones
Versiones
La versión va en la ruta (/v1). La v1 quedó cerrada antes del lanzamiento; dentro de v1 solo añadimos cosas y tu cliente tiene que ignorar los campos que no conozca. Los webhooks llevan api_version (hoy 2026-11-09).
Formatos
JSON en UTF-8. Importes: enteros en céntimos de currency. Fechas: YYYY-MM-DD. Fechas con hora: ISO 8601 en UTC con Z (2026-11-11T10:00:00Z), en las respuestas y en los webhooks. Estados: códigos estables en inglés. Todas las respuestas llevan Cache-Control: no-store.
Paginación
Todas las listas (/schools, /courses, /quotes, /bookings, /students) aceptan page (desde 1) y contestan items, total, page, pages y next: la ruta de la página siguiente con los mismos filtros, o null en la última. 20 por página en /courses y 50 en las demás. Nada se corta: sigue next hasta que sea null.
Idempotencia
Manda Idempotency-Key (de 1 a 255 caracteres visibles, por ejemplo un UUID) con POST /students: durante 24 horas, la misma clave con la misma petición devuelve la respuesta guardada sin volver a ejecutarla (Idempotent-Replayed: true); con otra petición contesta 422 idempotency_key_reused, y mientras la primera sigue en curso, 409 idempotency_key_in_use. Los errores no se guardan: puedes reintentarlos con la misma clave. El endpoint de tokens OAuth sigue el RFC 6749 y la ignora. Los webhooks conservan el id del evento al reenviarse.
Errores
Los errores son JSON con un código error estable y un message en el idioma de la petición (Accept-Language o X-Fipeo-Lang: en, es, fr, it, de, pt). Los de validación (422) llevan errors: campo → mensaje.
| Estado | Código | Qué significa |
|---|---|---|
| 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. |
Límites de uso
| Límite | Por | Se aplica a |
|---|---|---|
| 120 por minuto | key or OAuth application | every request |
| 30 por minuto | key or OAuth application | POST /students |
| 600 por minuto | IP address | every request, before the key is checked |
| 60 por minuto | IP address | POST /oauth/token and /oauth/revoke |
| 30 por minuto | client_id | POST /oauth/token and /oauth/revoke |
Rutas
- 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
Permiso: ningunoPara: agencias y escuelas
Who you are: the organization that owns the key (or OAuth token), the key and its scopes. Needs no scope.
Parámetros
| Campo | Tipo | Descripción |
|---|---|---|
| Accept-Language (header) | string | Language of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent. |
Respuestas
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
Permiso: catalog:readPara: agencias
The schools with an active connection with your agency, 50 per page.
Parámetros
| Campo | Tipo | Descripción |
|---|---|---|
| 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. |
Respuestas
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
Permiso: catalog:readPara: agencias
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.
Parámetros
| Campo | Tipo | Descripción |
|---|---|---|
| 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. |
Respuestas
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
Permiso: quotes:readPara: agencias
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.
Parámetros
| Campo | Tipo | Descripción |
|---|---|---|
| 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. |
Respuestas
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
Permiso: quotes:readPara: agencias
Parámetros
| Campo | Tipo | Descripción |
|---|---|---|
| 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. |
Respuestas
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
Permiso: bookings:readPara: agencias y escuelas
Agency key: your bookings, newest first, as BookingSummary. School key: your booking inbox, newest first, as SchoolBooking. 50 per page.
Parámetros
| Campo | Tipo | Descripción |
|---|---|---|
| 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. |
Respuestas
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
Permiso: bookings:readPara: agencias
One booking of your agency, with its lines and participants. Agency keys only (a school key gets 404).
Parámetros
| Campo | Tipo | Descripción |
|---|---|---|
| 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. |
Respuestas
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
Permiso: students:readPara: agencias
The students of your CRM, 50 per page. Internal notes never leave Fipeo.
Parámetros
| Campo | Tipo | Descripción |
|---|---|---|
| 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. |
Respuestas
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
Permiso: students:writePara: agencias
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.
Parámetros
| Campo | Tipo | Descripción |
|---|---|---|
| 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. |
Cuerpo de la petición 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"
}Respuestas
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
Permiso: students:readPara: agencias
One student with their opportunities and quotes.
Parámetros
| Campo | Tipo | Descripción |
|---|---|---|
| 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. |
Respuestas
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
Permiso: —Para: agencias y escuelas
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.
Cuerpo de la petición application/x-www-form-urlencoded · object
| Campo | Tipo | Descripción |
|---|---|---|
| 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 |
Cuerpo de la petición application/json · object
| Campo | Tipo | Descripción |
|---|---|---|
| grant_type* | string | "client_credentials" |
| scope | string | |
| client_id | string | |
| client_secret | string |
Respuestas
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
Permiso: —Para: agencias y escuelas
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.
Cuerpo de la petición application/x-www-form-urlencoded · object
| Campo | Tipo | Descripción |
|---|---|---|
| token* | string | |
| client_id | string | |
| client_secret | string |
Cuerpo de la petición application/json · object
| Campo | Tipo | Descripción |
|---|---|---|
| token* | string | |
| client_id | string | |
| client_secret | string |
Respuestas
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
Cómo se configuran y se comprueban: guía de webhooks.
Cabeceras
| Campo | Tipo | Descripción |
|---|---|---|
| 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 · Para: agencias y escuelas · WebhookBookingEvent
booking.status_changed
A booking changed status · Para: agencias y escuelas · WebhookBookingStatusEvent
message.created
A new message in a conversation · Para: agencias y escuelas · WebhookMessageCreatedEvent
quote.accepted
A student accepted a quote · Para: agencias · WebhookQuoteAcceptedEvent
student.created
A student was added to the CRM · Para: agencias · WebhookStudentCreatedEvent
automation.run
An automation of the CRM ran its «webhook» action · Para: agencias · WebhookAutomationEvent
ping
Test event («Send a test» in the panel) · Para: agencias y escuelas · WebhookPingEvent
Esquemas
Organization
| Campo | Tipo | Descripción |
|---|---|---|
| type* | string | "agency""school" |
| id* | string | integer | Agency: the UUID of its account. School: its numeric id. |
Me
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| id* | string (uuid) | The student. |
| result* | string | "created""updated""skipped" |
| opportunity_id* | string | null (uuid) | The opportunity created (null when skipped). |
Error
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| errors* | object | Field → message (translated). |
| errors_source | object | The original English messages when they were translated. |
| message* | string |
OAuthToken
| Campo | Tipo | Descripción |
|---|---|---|
| access_token* | string | |
| token_type* | string | "Bearer" |
| expires_in* | integer | 3600 |
| scope* | string | The granted scopes, separated by spaces. |
OAuthError
| Campo | Tipo | Descripción |
|---|---|---|
| error* | string | "invalid_request""invalid_client""unsupported_grant_type""invalid_scope" |
| error_description | string |
WebhookBookingEvent
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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
| Campo | Tipo | Descripción |
|---|---|---|
| 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.
| Campo | Tipo | Descripción |
|---|---|---|
| id* | integer | |
| name* | string | null |