Saltar al contenido
Fipeo

Fipeo para desarrolladores

Referencia de la API

Acceso anticipado. La API, los webhooks y el widget están apagados para la mayoría de las cuentas mientras los probamos con las primeras escuelas y agencias. Esta documentación es pública para que puedas planear tu integración: escríbenos a [email protected] y te lo encendemos.

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.

EstadoCódigoQué significa
401unauthenticatedNo key, or the key/token is malformed, revoked, expired, or its account is no longer active.
403insufficient_scopeThe key is valid but lacks the scope of this route (see scope).
403dpa_requiredstudents and quotes: the organization has not accepted the data processing agreement in the panel yet.
404not_foundIt 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.
405method_not_allowedThe method is not allowed on this path (see Allow).
400invalid_jsonThe body is not valid JSON.
422errorsValidation: errors maps each field to its message (no error code).
422idempotency_key_reusedThis Idempotency-Key was already used (in the last 24 hours) with a different request.
409idempotency_key_in_useA request with this Idempotency-Key is still being processed: retry in a moment.
429too_many_requestsRate limit reached; wait retry_after seconds (also in Retry-After).
503busyOverloaded for a moment; retry after retry_after seconds.
400invalid_requestOAuth: missing or duplicated parameters (e.g. client credentials both in Basic and in the body), or too many active tokens.
401invalid_clientOAuth: the client could not be authenticated.
400unsupported_grant_typeOAuth: only client_credentials is supported.
400invalid_scopeOAuth: a requested scope is not one of the application’s.

Límites de uso

LímitePorSe aplica a
120 por minutokey or OAuth applicationevery request
30 por minutokey or OAuth applicationPOST /students
600 por minutoIP addressevery request, before the key is checked
60 por minutoIP addressPOST /oauth/token and /oauth/revoke
30 por minutoclient_idPOST /oauth/token and /oauth/revoke

Rutas

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

CampoTipoDescripción
Accept-Language (header)stringLanguage of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent.

Respuestas

  • 200MeOK
  • 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.
  • 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), and GET /bookings/{reference} with a school key.
  • 429Errortoo_many_requests: rate limit reached (with reason and retry_after in seconds).
  • 503Errorbusy: Fipeo is overloaded for a moment. Retry after retry_after seconds.

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

CampoTipoDescripción
page (query)integerPage number, from 1.
Accept-Language (header)stringLanguage of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent.

Respuestas

  • 200SchoolListOK
  • 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 (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).
  • 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), and GET /bookings/{reference} with a school key.
  • 422ValidationErrorA 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.
  • 429Errortoo_many_requests: rate limit reached (with reason and retry_after in seconds).
  • 503Errorbusy: Fipeo is overloaded for a moment. Retry after retry_after seconds.

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

CampoTipoDescripción
school_id (query)integerOnly this school (its id).
country (query)stringISO 3166-1 alpha-2 country of the school.
city (query)stringCity of the school.
language (query)stringLanguage taught (en, es…).
type (query)stringCourse type (general, intensive…).
level (query)stringCEFR level of the student."A1""A2""B1""B2""C1""C2"
weeks (query)integerNumber of weeks (default: the minimum of each course).
start (query)string (date)Start date (default: the Monday about two weeks from today).
age (query)integerAge of the student.
accommodation (query)booleanOnly schools that offer accommodation.
lang (query)stringLanguage of the course names."en""es""fr""it""de""pt"
page (query)integerPage number, from 1.
Accept-Language (header)stringLanguage of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent.

Respuestas

  • 200CourseListOK
  • 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 (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).
  • 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), and GET /bookings/{reference} with a school key.
  • 422ValidationErrorA 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.
  • 429Errortoo_many_requests: rate limit reached (with reason and retry_after in seconds).
  • 503Errorbusy: Fipeo is overloaded for a moment. Retry after retry_after seconds.

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

CampoTipoDescripción
status (query)QuoteStatusOnly quotes in this status. Any other value gives 422.
student_id (query)string (uuid)Only the quotes of this student.
page (query)integerPage number, from 1.
Accept-Language (header)stringLanguage of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent.

Respuestas

  • 200QuoteListOK
  • 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 (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).
  • 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), and GET /bookings/{reference} with a school key.
  • 422ValidationErrorA 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.
  • 429Errortoo_many_requests: rate limit reached (with reason and retry_after in seconds).
  • 503Errorbusy: Fipeo is overloaded for a moment. Retry after retry_after seconds.

GET/quotes/{id}

Get a quote

Permiso: quotes:readPara: agencias

Parámetros

CampoTipoDescripción
id (path)*string (uuid)Quote id.
Accept-Language (header)stringLanguage of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent.

Respuestas

  • 200QuoteOK
  • 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 (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).
  • 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), and GET /bookings/{reference} with a school key.
  • 429Errortoo_many_requests: rate limit reached (with reason and retry_after in seconds).
  • 503Errorbusy: Fipeo is overloaded for a moment. Retry after retry_after seconds.

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

CampoTipoDescripción
status (query)BookingStatusOnly bookings in this status. Any other value gives 422, with an agency or a school key.
page (query)integerPage number, from 1.
Accept-Language (header)stringLanguage of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent.

Respuestas

  • 200BookingList | SchoolBookingListOK
  • 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 (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).
  • 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), and GET /bookings/{reference} with a school key.
  • 422ValidationErrorA 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.
  • 429Errortoo_many_requests: rate limit reached (with reason and retry_after in seconds).
  • 503Errorbusy: Fipeo is overloaded for a moment. Retry after retry_after seconds.

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

CampoTipoDescripción
reference (path)*stringBooking reference.
Accept-Language (header)stringLanguage of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent.

Respuestas

  • 200BookingOK
  • 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 (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).
  • 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), and GET /bookings/{reference} with a school key.
  • 429Errortoo_many_requests: rate limit reached (with reason and retry_after in seconds).
  • 503Errorbusy: Fipeo is overloaded for a moment. Retry after retry_after seconds.

GET/students

List students

Permiso: students:readPara: agencias

The students of your CRM, 50 per page. Internal notes never leave Fipeo.

Parámetros

CampoTipoDescripción
q (query)stringSearch in name, email and phone.
tag (query)stringOnly students with this tag.
consent (query)stringOnly students who gave (yes) or did not give (no) consent."yes""no"
page (query)integerPage number, from 1.
Accept-Language (header)stringLanguage of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent.

Respuestas

  • 200StudentListOK
  • 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 (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).
  • 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), and GET /bookings/{reference} with a school key.
  • 422ValidationErrorA 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.
  • 429Errortoo_many_requests: rate limit reached (with reason and retry_after in seconds).
  • 503Errorbusy: Fipeo is overloaded for a moment. Retry after retry_after seconds.

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

CampoTipoDescripción
Idempotency-Key (header)stringOptional. 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)stringLanguage 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

json
{
  "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 (see result).
  • 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 (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).
  • 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), and GET /bookings/{reference} with a school key.
  • 409Erroridempotency_key_in_use: a request with the same Idempotency-Key is still being processed. Retry in a moment.
  • 422ValidationError | ErrorA field is not valid (errors: field → message), or idempotency_key_reused: this Idempotency-Key was already used with a different request.
  • 429Errortoo_many_requests: rate limit reached (with reason and retry_after in seconds).
  • 503Errorbusy: Fipeo is overloaded for a moment. Retry after retry_after seconds.

GET/students/{id}

Get a student

Permiso: students:readPara: agencias

One student with their opportunities and quotes.

Parámetros

CampoTipoDescripción
id (path)*string (uuid)Student id.
Accept-Language (header)stringLanguage of message in errors (en, es, fr, it, de, pt). X-Fipeo-Lang wins if both are sent.

Respuestas

  • 200StudentDetailOK
  • 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 (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).
  • 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), and GET /bookings/{reference} with a school key.
  • 429Errortoo_many_requests: rate limit reached (with reason and retry_after in seconds).
  • 503Errorbusy: Fipeo is overloaded for a moment. Retry after retry_after seconds.

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

CampoTipoDescripción
grant_type*string"client_credentials"
scopestringScopes separated by spaces, a subset of the application’s (empty = all of them).
client_idstring
client_secretstring

Cuerpo de la petición application/json · object

CampoTipoDescripción
grant_type*string"client_credentials"
scopestring
client_idstring
client_secretstring

Respuestas

  • 200OAuthTokenThe token.
  • 400OAuthErrorinvalid_request, unsupported_grant_type or invalid_scope (RFC 6749 §5.2).
  • 401OAuthErrorinvalid_client: unknown client, wrong secret, revoked or expired application, or account no longer active. With Basic, also WWW-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), and GET /bookings/{reference} with a school key.
  • 429Errortoo_many_requests: rate limit reached (with reason and retry_after in 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

CampoTipoDescripción
token*string
client_idstring
client_secretstring

Cuerpo de la petición application/json · object

CampoTipoDescripción
token*string
client_idstring
client_secretstring

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), and GET /bookings/{reference} with a school key.
  • 429Errortoo_many_requests: rate limit reached (with reason and retry_after in seconds).

Webhooks

Cómo se configuran y se comprueban: guía de webhooks.

Cabeceras

CampoTipoDescripción
X-Fipeo-Signature*stringt=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body" with your webhook secret>
X-Fipeo-Event*stringThe event type, as in type.
X-Fipeo-Event-Id*stringThe event id, as in id (the same in a resend).
X-Fipeo-Delivery*stringThe 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

CampoTipoDescripción
type*string"agency""school"
id*string | integerAgency: the UUID of its account. School: its numeric id.

Me

CampoTipoDescripció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*stringFirst 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

CampoTipoDescripción
connection_id*string (uuid)The connection between your agency and the school.
status*stringOnly active connections are listed."active"
can_book*booleanWhether 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

CampoTipoDescripción
items*array of ConnectedSchool
total*integerAll the results with these filters, in every page.
page*integer
pages*integer
next*string | nullPath 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

CampoTipoDescripción
school*object
school.id*integer
school.name*string
school.city*string | null
school.country*string | nullISO 3166-1 alpha-2.
school.accommodation*booleanWhether 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*stringPrice 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 | nullWhat 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*booleantrue: the booking is confirmed at once; false: it is a request the school answers.

CourseList

CampoTipoDescripción
items*array of CourseResult
total*integerAll the results with these filters, in every page.
page*integer
pages*integer
next*string | nullPath 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

CampoTipoDescripció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 | nullFull 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 | nullThe lowest option total for the student. In cents (minor units) of currency.
currency*string | null

QuoteList

CampoTipoDescripción
items*array of QuoteSummary
total*integerAll the results with these filters, in every page.
page*integer
pages*integer
next*string | nullPath 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

CampoTipoDescripción
lineinteger
namestring
textstring | null
typestring
startstring | null (date)Date, YYYY-MM-DD.
endstring | null (date)Date, YYYY-MM-DD.
unitsinteger | null

QuoteOption

CampoTipoDescripción
number*integer
titlestring | null
currencystring
availabilitystring | null
unconfirmed_pricesboolean
school*object
school.idinteger
school.namestring
school.citystring | null
school.countrystring | null
total*integer | nullWhat the student pays for this option. In cents (minor units) of currency.
lines*array of Line

Quote

CampoTipoDescripción
id*string (uuid)
owner_id*string (uuid)
number*string
student_id*string (uuid)
student*string | nullFull 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

CampoTipoDescripció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 | nullTotal of the booking (what the student pays). In cents (minor units) of currency.
currency*string | null
owner_id*string

BookingList

CampoTipoDescripción
items*array of BookingSummary
total*integerAll the results with these filters, in every page.
page*integer
pages*integer
next*string | nullPath 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

CampoTipoDescripción
numberinteger
first_namestring | null
last_namestring | null
namestring | null
nationalitystring | null
birth_datestring | null (date)Date, YYYY-MM-DD.

Booking

CampoTipoDescripció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 | nullTotal of the booking (what the student pays). In cents (minor units) of currency.
currency*string | null
lines*array of LineWhat was booked, line by line (course, accommodation, extras), without amounts.
participants*array of Participant

SchoolBooking

CampoTipoDescripción
id*string
reference*string
status*BookingStatus
modality*stringon_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 | nullGross total of the booking. In cents (minor units) of currency.
currency*string | null
channel*stringWhere the booking came from: agency (an agency on Fipeo), languagebookings, direct (your website or booking form) or another channel code.

SchoolBookingList

CampoTipoDescripción
items*array of SchoolBooking
total*integerAll the results with these filters, in every page.
page*integer
pages*integer
next*string | nullPath 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

CampoTipoDescripción
id*string (uuid)
owner_idstring (uuid)The user of your agency responsible for the student.
first_name*string
last_namestring | null
email*string | null (email)
phonestring | null
nationalitystring | nullISO 3166-1 alpha-2.
birth_datestring | null (date)Date, YYYY-MM-DD.
ageinteger | null
languagestring | null
study_languagestring | null
levelstring | null
budgetinteger | nullBudget. In cents (minor units) of currency.
currencystring | null
start_fromstring | null (date)Date, YYYY-MM-DD.
start_tostring | null (date)Date, YYYY-MM-DD.
weeksinteger | null
interestsstring | null
sourcestring | null
tagsarray of string
consent*boolean
consent_atstring | null (date-time)Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z).
consent_textstring | null
stageOpportunityStage | nullStage 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

CampoTipoDescripción
id*string (uuid)
owner_idstring (uuid)The user of your agency responsible for the student.
first_name*string
last_namestring | null
email*string | null (email)
phonestring | null
nationalitystring | nullISO 3166-1 alpha-2.
birth_datestring | null (date)Date, YYYY-MM-DD.
ageinteger | null
languagestring | null
study_languagestring | null
levelstring | null
budgetinteger | nullBudget. In cents (minor units) of currency.
currencystring | null
start_fromstring | null (date)Date, YYYY-MM-DD.
start_tostring | null (date)Date, YYYY-MM-DD.
weeksinteger | null
interestsstring | null
sourcestring | null
tagsarray of string
consent*boolean
consent_atstring | null (date-time)Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z).
consent_textstring | null
stageOpportunityStage | nullStage 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

CampoTipoDescripción
items*array of Student
total*integerAll the results with these filters, in every page.
page*integer
pages*integer
next*string | nullPath 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

CampoTipoDescripción
first_name*string
last_namestring
email*string (email)
phonestring
nationalitystringISO 3166-1 alpha-2.
birth_datestring (date)
languagestringLanguage the student speaks (en, es, pt-BR…).
study_languagestringLanguage the student wants to study.
start_fromstring (date)
weeksinteger
budgetintegerIn cents of currency.
currencystring
interestsstring
consent_text*stringThe exact consent text the student accepted on your website. Required.
notestringAdded to the student’s timeline.
opportunity_titlestringTitle of the opportunity created in your pipeline (default: «API enquiry»).
if_existsstringIf 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"
tagstringA tag added to the student.

NewStudentResult

CampoTipoDescripción
id*string (uuid)The student.
result*string"created""updated""skipped"
opportunity_id*string | null (uuid)The opportunity created (null when skipped).

Error

CampoTipoDescripción
errorstringStable error code (see the error catalogue).
message*stringA readable message in the language of the request (Accept-Language or X-Fipeo-Lang: en, es, fr, it, de, pt).
reasonstring
reason_sourcestringThe original English reason when reason was translated.
scopeScope
retry_afterintegerSeconds.
organization_typestring"agency""school"

ValidationError

CampoTipoDescripción
errors*objectField → message (translated).
errors_sourceobjectThe original English messages when they were translated.
message*string

OAuthToken

CampoTipoDescripción
access_token*string
token_type*string"Bearer"
expires_in*integer3600
scope*stringThe granted scopes, separated by spaces.

OAuthError

CampoTipoDescripción
error*string"invalid_request""invalid_client""unsupported_grant_type""invalid_scope"
error_descriptionstring

WebhookBookingEvent

CampoTipoDescripción
id*stringEvent 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

CampoTipoDescripción
id*stringEvent 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

CampoTipoDescripción
id*stringEvent 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

CampoTipoDescripción
id*stringEvent 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_idstring (uuid)
data.student.first_name*string
data.student.last_namestring | null
data.student.emailstring | null
data.student.phonestring | null
data.student.nationalitystring | null
data.student.languagestring | null
data.student.study_languagestring | null
data.student.start_fromstring | null (date)Date, YYYY-MM-DD.
data.student.weeksinteger | null
data.student.sourcestring | null
data.student.tagsarray of string
data.student.consentboolean
data.student.created_at*string (date-time)Date and time, ISO 8601 in UTC (2026-11-11T10:00:00Z).

WebhookMessageCreatedEvent

CampoTipoDescripción
id*stringEvent 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*stringschool (to an agency), agency or channel (to a school)."school""agency""channel"

WebhookPingEvent

CampoTipoDescripción
id*stringEvent 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

CampoTipoDescripción
id*stringEvent 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*stringThe 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.

CampoTipoDescripción
id*integer
name*string | null