API reference

Read-only JSON over HTTPS. No authentication. CORS is open, so you can call it from a browser.

Conventions
Communities
Homes
Residents
Packages
Maintenance tickets
Visitors
Amenities
Amenity bookings
Community posts
Feedback
Package summary

Conventions

Base URL: https://takehome.cortile.com/api/v1. An OpenAPI 3 spec is available.

Lists and pagination

List endpoints return { data: T[], nextCursor: string | null }. To get the next page, pass nextCursor back as cursor. When nextCursor is null you have reached the last page. Use limit to set the page size: the default is 25 and the maximum is 100.

curl "https://takehome.cortile.com/api/v1/packages?limit=100"

{
  "data": [ { "id": "pkg_...", ... } ],
  "nextCursor": "bzoxMDA"
}

Single items

GET /api/v1/<resource>/<id> returns { data: T }, or a 404 if the id does not exist.

Filtering

Most lists accept filters as query parameters, listed under each resource. Filters match exactly. Resources with a timestamp also accept since (inclusive) and until (exclusive) as ISO 8601 values.

Times

All timestamps are ISO 8601 in UTC. Front-desk opening hours are in each community's local time, given by its timezone. The data is a snapshot taken at 2026-09-30T08:00:00.000Z, so bookings after that time are future bookings.

Errors

Errors return a non-2xx status and { error: { code: string, message: string } }. The API runs on modest infrastructure, so expect the occasional 500 or 503 and the occasional slow response. A 503 includes a Retry-After header.

Communities

The buildings we manage. Each community has its own front desk with its own opening hours.

GET/api/v1/communities

GET/api/v1/communities/:id

Sorted by name, A to Z.

Fields

Field	Type	Description
`id`	`string`	Unique ID, prefixed com_.
`name`	`string`	Community name.
`city`	`string`	City.
`address`	`string`	Street address.
`timezone`	`string`	IANA timezone the community operates in.
`blocks`	`string[]`	Block names within the community.
`frontDeskHours`	`object`	When the front desk is staffed, in the community timezone.

Homes

Individual flats within a community.

GET/api/v1/homes

GET/api/v1/homes/:id

Sorted by unit, A to Z.

Filters

Parameter	Type	Description
`communityId`	`string`	Only homes in this community.
`block`	`string`	Only homes in this block.

Fields

Field	Type	Description
`id`	`string`	Unique ID, prefixed hom_.
`communityId`	`string`	Community the home belongs to.
`block`	`string`	Block name.
`floor`	`integer`	Floor number.
`unit`	`string`	Unit label as residents know it.
`bedrooms`	`integer`	Number of bedrooms.

Residents

People who live, or have lived, in a home.

GET/api/v1/residents

GET/api/v1/residents/:id

Sorted by id.

Filters

Parameter	Type	Description
`communityId`	`string`	Only residents of this community.
`homeId`	`string`	Only residents of this home.

Fields

Field	Type	Description
`id`	`string`	Unique ID, prefixed res_.
`communityId`	`string`	Community the resident lives in.
`homeId`	`string`	Home the resident lives in.
`firstName`	`string \| null`	First name, if known.
`lastName`	`string \| null`	Last name, if known.
`email`	`string`	Email address.
`phone`	`string \| null`	Phone number, if known.
`moveInDate`	`string (YYYY-MM-DD)`	Date the resident moved in.
`moveOutDate`	`string (YYYY-MM-DD) \| null`	Date the resident moved out, or null if they still live there.

Packages

Parcels received by the front desk on behalf of residents.

GET/api/v1/packages

GET/api/v1/packages/:id

Sorted by receivedAt, newest first. since and until filter on receivedAt.

Filters

Parameter	Type	Description
`communityId`	`string`	Only packages at this community.
`residentId`	`string`	Only packages for this resident.
`status`	`string`	Only packages with this status.

Fields

Field	Type	Description
`id`	`string`	Unique ID, prefixed pkg_.
`communityId`	`string`	Community where the package was received.
`residentId`	`string \| null`	Resident the package is for. null if the front desk has not matched it to a resident.
`carrier`	`string`	Delivery company.
`size`	`'SMALL' \| 'MEDIUM' \| 'LARGE'`	Rough size of the parcel.
`status`	`'DELIVERED' \| 'COLLECTED' \| 'MISSING'`	DELIVERED means it is at the desk waiting to be collected.
`receivedAt`	`string (ISO 8601)`	When the front desk received the package.
`collectedAt`	`string (ISO 8601) \| null`	When the resident collected it, or null.

Maintenance tickets

Repair and maintenance requests, raised by residents or staff.

GET/api/v1/tickets

GET/api/v1/tickets/:id

Sorted by createdAt, newest first. since and until filter on createdAt.

Filters

Parameter	Type	Description
`communityId`	`string`	Only tickets at this community.
`homeId`	`string`	Only tickets for this home.
`category`	`string`	Only tickets in this category.
`status`	`string`	Only tickets with this status.

Fields

Field	Type	Description
`id`	`string`	Unique ID, prefixed tkt_.
`communityId`	`string`	Community the ticket is for.
`homeId`	`string \| null`	Home the ticket is about. null for communal areas.
`reportedByResidentId`	`string \| null`	Resident who raised it. null if raised by staff.
`category`	`'LEAK' \| 'HEATING' \| 'ELECTRICAL' \| 'LIFT' \| 'DOOR_ACCESS' \| 'PEST' \| 'NOISE' \| 'APPLIANCE' \| 'OTHER'`	What kind of problem it is.
`priority`	`'LOW' \| 'MEDIUM' \| 'HIGH' \| 'URGENT'`	Priority set when the ticket was raised.
`status`	`'OPEN' \| 'IN_PROGRESS' \| 'RESOLVED'`	Current status.
`title`	`string`	Short summary, as written by the reporter.
`description`	`string`	Full description, as written by the reporter.
`createdAt`	`string (ISO 8601)`	When the ticket was raised.
`firstResponseAt`	`string (ISO 8601) \| null`	When a member of staff first responded, or null.
`resolvedAt`	`string (ISO 8601) \| null`	When the ticket was marked as resolved, or null.

Visitors

People who visited a home, as recorded by the door entry system.

GET/api/v1/visitors

GET/api/v1/visitors/:id

Sorted by arrivedAt, newest first. since and until filter on arrivedAt.

Filters

Parameter	Type	Description
`communityId`	`string`	Only visitors to this community.
`homeId`	`string`	Only visitors to this home.

Fields

Field	Type	Description
`id`	`string`	Unique ID, prefixed vis_.
`communityId`	`string`	Community visited.
`homeId`	`string`	Home visited.
`visitorName`	`string`	Name given by the visitor.
`purpose`	`'GUEST' \| 'CONTRACTOR' \| 'VIEWING' \| 'CARER' \| 'OTHER'`	Reason for the visit.
`preRegistered`	`boolean`	Whether the resident registered the visitor in advance.
`signedInAtDesk`	`boolean`	Whether the visitor was signed in by the front desk.
`arrivedAt`	`string (ISO 8601)`	When the visitor arrived.
`departedAt`	`string (ISO 8601) \| null`	When the visitor left, or null if no departure was recorded.

Amenities

Shared facilities residents can book.

GET/api/v1/amenities

GET/api/v1/amenities/:id

Sorted by name, A to Z.

Filters

Parameter	Type	Description
`communityId`	`string`	Only amenities at this community.

Fields

Field	Type	Description
`id`	`string`	Unique ID, prefixed amn_.
`communityId`	`string`	Community the amenity is in.
`name`	`string`	Display name.
`type`	`'GYM' \| 'GUEST_SUITE' \| 'MEETING_ROOM' \| 'ROOF_TERRACE' \| 'CINEMA_ROOM'`	Kind of amenity.
`capacity`	`integer`	Maximum people (or, for a guest suite, concurrent bookings).

Amenity bookings

Bookings of shared facilities, including future bookings already made.

GET/api/v1/bookings

GET/api/v1/bookings/:id

Sorted by startsAt, latest first. since and until filter on startsAt.

Filters

Parameter	Type	Description
`communityId`	`string`	Only bookings at this community.
`amenityId`	`string`	Only bookings of this amenity.
`residentId`	`string`	Only bookings made by this resident.

Fields

Field	Type	Description
`id`	`string`	Unique ID, prefixed bkg_.
`communityId`	`string`	Community of the amenity.
`amenityId`	`string`	Amenity booked.
`residentId`	`string`	Resident who made the booking.
`status`	`'CONFIRMED' \| 'CANCELLED'`	Booking status.
`startsAt`	`string (ISO 8601)`	Start of the booking.
`endsAt`	`string (ISO 8601)`	End of the booking.
`createdAt`	`string (ISO 8601)`	When the booking was made.
`checkedInAt`	`string (ISO 8601) \| null`	When the resident checked in, or null.

Community posts

Posts on each community's resident noticeboard.

GET/api/v1/posts

GET/api/v1/posts/:id

Sorted by createdAt, newest first. since and until filter on createdAt.

Filters

Parameter	Type	Description
`communityId`	`string`	Only posts in this community.

Fields

Field	Type	Description
`id`	`string`	Unique ID, prefixed pst_.
`communityId`	`string`	Community the post was made in.
`authorResidentId`	`string`	Resident who wrote the post.
`body`	`string`	Post text.
`reactionCount`	`integer`	Number of reactions.
`replyCount`	`integer`	Number of replies.
`createdAt`	`string (ISO 8601)`	When the post was made.

Feedback

Satisfaction scores from residents, either about a specific ticket or about the building in general.

GET/api/v1/feedback

GET/api/v1/feedback/:id

Sorted by createdAt, newest first. since and until filter on createdAt.

Filters

Parameter	Type	Description
`communityId`	`string`	Only feedback for this community.
`ticketId`	`string`	Only feedback about this ticket.

Fields

Field	Type	Description
`id`	`string`	Unique ID, prefixed fdb_.
`communityId`	`string`	Community the feedback is about.
`residentId`	`string`	Resident who left the feedback.
`ticketId`	`string \| null`	Ticket the feedback is about, or null for general feedback.
`score`	`integer`	Score from 1 (very unhappy) to 5 (very happy).
`comment`	`string \| null`	Optional comment.
`createdAt`	`string (ISO 8601)`	When the feedback was left.

Package summary deprecated

Package counts per community, precomputed once a day so dashboards do not have to page through every package.

GET/api/v1/packages/summary

Deprecated. Kept for older integrations and will be removed. Prefer /api/v1/packages for live data.

Field	Type	Description
`generatedAt`	`string (ISO 8601)`	When the counts were computed.
`communities[].communityId`	`string`	Community the counts are for.
`communities[].received`	`integer`	Packages received.
`communities[].collected`	`integer`	Packages collected.
`communities[].missing`	`integer`	Packages marked missing.
`communities[].awaitingCollection`	`integer`	Packages at the desk waiting to be collected.
`communities[].unassigned`	`integer`	Packages not matched to a resident.