API conventions

The Fertiligent API is a conventional JSON REST API. Once you know a few cross-cutting patterns — paging, sorting, filtering, identifiers, dates, and errors — every endpoint in the API Reference behaves consistently. This page covers those patterns.

All requests need a bearer token (Authentication) and, for multi-clinic integrations, a resolved tenant (Multi-tenancy). Every response is JSON.

Lists and paging

List endpoints (the GET collection routes) return a paged envelope:

{
  "totalCount": 137,
  "items": [ { "id": "…", "…": "…" } ]
}

Page with two query parameters:

Parameter	Meaning	Default
SkipCount	Number of records to skip (the offset).	0
MaxResultCount	Page size (records to return).	typically 10

For example, the second page of 20 referrals:

curl "https://api.fertiligent.ai/api/care/referrals?SkipCount=20&MaxResultCount=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Use totalCount to know when you've read the whole set.

Sorting

Order a list with the Sorting parameter — a field name and an optional direction:

?Sorting=creationTime desc

Filtering

Most list endpoints accept a general free-text Filter, plus filters specific to that resource. For example, the referrals list accepts Status, NeedsReviewOnly, DateFrom, and DateTo; the patients list accepts Class, IsActive, and more. Each endpoint's exact filters are documented with it in the API Reference.

curl "https://api.fertiligent.ai/api/care/patients?Class=Patient&IsActive=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Identifiers and dates

• Identifiers are GUIDs (for example 3fa85f64-5717-4562-b3fc-2c963f66afa6).
• Dates and times are ISO 8601 and expressed in UTC (for example 2026-07-17T14:30:00Z). Convert to the clinic's local time zone in your own application.

Errors

The API uses standard HTTP status codes. Error responses share a consistent shape:

{
  "error": {
    "code": "…",
    "message": "A human-readable summary.",
    "details": "…",
    "validationErrors": [ { "message": "…", "members": ["…"] } ]
  }
}

Common statuses:

Status	Meaning
400 Bad Request	Validation failed — see validationErrors.
401 Unauthorized	Missing, expired, or invalid access token.
403 Forbidden	The token lacks the required permission — or the feature is not enabled for the tenant (many endpoints are gated per clinic).
404 Not Found	The resource doesn't exist, or isn't visible to your tenant.
409 Conflict	A state conflict — for example trying to book an appointment slot that was just taken.
429 Too Many Requests	You're being rate limited; back off and retry.
500	An unexpected server error.

A 403 on an endpoint you expect to have access to often means the underlying feature isn't enabled for that clinic — see the availability notes on the relevant clinic-staff guide, and contact your Fertiligent representative to enable it.

Staying in sync (webhooks)

Fertiligent does not currently offer outbound event webhooks or subscriptions. To keep an external system in step, poll the relevant list endpoint — sorting by a recency field and filtering by a date range — on a schedule that suits your integration. If your use case needs push-based events, talk to your Fertiligent representative about your requirements.