Aller au contenu
Fipeo

Fipeo for developers

API reference

Early access. The API, the webhooks and the widget are switched off for most accounts while we try them with the first schools and agencies. This documentation is public so you can plan your integration: write to [email protected] and we switch it on for you.

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.

StatusCodeMeaning
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.

Rate limits

LimitPerApplies to
120 per minutekey or OAuth applicationevery request
30 per minutekey or OAuth applicationPOST /students
600 per minuteIP addressevery request, before the key is checked
60 per minuteIP addressPOST /oauth/token and /oauth/revoke
30 per minuteclient_idPOST /oauth/token and /oauth/revoke

Endpoints

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

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

Responses

  • 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

Scope: catalog:readFor: agencies

The schools with an active connection with your agency, 50 per page.

Parameters

FieldTypeDescription
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.

Responses

  • 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

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

FieldTypeDescription
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.

Responses

  • 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

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

FieldTypeDescription
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.

Responses

  • 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

Scope: quotes:readFor: agencies

Parameters

FieldTypeDescription
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.

Responses

  • 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

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

FieldTypeDescription
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.

Responses

  • 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

Scope: bookings:readFor: agencies

One booking of your agency, with its lines and participants. Agency keys only (a school key gets 404).

Parameters

FieldTypeDescription
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.

Responses

  • 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

Scope: students:readFor: agencies

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

Parameters

FieldTypeDescription
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.

Responses

  • 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

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

FieldTypeDescription
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.

Request body 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"
}

Responses

  • 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

Scope: students:readFor: agencies

One student with their opportunities and quotes.

Parameters

FieldTypeDescription
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.

Responses

  • 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

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

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

Request body application/json · object

FieldTypeDescription
grant_type*string"client_credentials"
scopestring
client_idstring
client_secretstring

Responses

  • 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

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

FieldTypeDescription
token*string
client_idstring
client_secretstring

Request body application/json · object

FieldTypeDescription
token*string
client_idstring
client_secretstring

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

Webhooks

How to set them up and verify them: webhooks guide.

Headers

FieldTypeDescription
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 · 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

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

Me

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

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

QuoteOption

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

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

Booking

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

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

Error

FieldTypeDescription
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

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

OAuthToken

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

OAuthError

FieldTypeDescription
error*string"invalid_request""invalid_client""unsupported_grant_type""invalid_scope"
error_descriptionstring

WebhookBookingEvent

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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

FieldTypeDescription
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.

FieldTypeDescription
id*integer
name*string | null