API V2: Understanding the Framework Basics

Last updated: October 5, 2026

Housing.Cloud provides a collections based REST API for developers to access data freely. Below are some key details and patterns of the API V2 framework.

Authentication and Authorization

Housing.Cloud utilizes scoped, short-lived JSON Web Tokens (JWT) for authentication. A developer must create a new API Agent via the Housing.Cloud admin portal and utilize the Agent id and the provided API key when calling the Authentication endpoint to generate a JWT.

Each JWT is imbued with configured Scopes from the associated Agent. Every Entity endpoint requires one or more scopes to access the resources. It is recommended that ever developer follow the Principle of Least Privilege when assigning Scopes to an Agent.

Rate Limits

Housing.Cloud limits the rate of API requests using the Sliding Window Algorithm. The rate limits are broken down by Agent and by Tenant (i.e. Institution/sub-domain). The rates are:

Per Agent: 10 requests per second
Per Tenant: 50 requests per second

The status of the rate limit details is available in all API responses under the metaData object.

Pagination

Housing.Cloud requires pagination when fetching collections. There are two components to pagination, the pointer/index and the quantity of rows to fetch. By default, the API sets the pointer to 0 (i.e. first item in the collection) and the quantity of rows to 1000.

To customize the pagination details, you must include the arguments:

offset: Represents the pointer
limit: Represents the quantity of rows to fetch (with a maximum of 1000)

The values of the two parameters will be echoed back in the API response for all GET Collection requests under the metaData object.

Example Request URL:

/api/v2/profile-fields?limit=2&offset=0

Common Response Structures

MetaData

Every API V2 response will contain a metaData object. The content of the metaData object will change depending on the entity type, HTTP method, and collection/individual. Below are tables showing possible structure

Field Name	Data Type	Required	Notes
`agentId`	string	Yes
`rateLimits`	RateLimit	Yes	See below for type explanation
`pagnination`	Pagination	No	See below for type explanation
`params`	JSON	No	Dynamic object that will echo details from the request

Rate Limit

The rate limits will be separated by rate limit type.

Field Name	Data Type	Notes
`limit`	number	Maximum number of requests per window
`remaining`	number	Remaining number of requests per window
`reset`	number	The timestamp of the window end

Pagination

Field Name	Data Type	Notes
`offset`	number	The offset of the previous request
`limit`	number	The limit of the previous request

Example Response:

"metaData": {
	"agentId": "ab5f95b2-303a-403b-85fd-ab1d0cd8093c",
	"rateLimits": {
		"tenant": {
			"limit": 50,
			"remaining": 49,
			"reset": 1759760332000
		},
		"agent": {
			"limit": 10,
			"remaining": 9,
			"reset": 1759760332000
		}
	},
	"pagination": {
		"offset": 0,
		"limit": 2
	}
}

GET Collection

In addition to to the metaData object, every request to obtain a Collection will include a field called entities. This field will contain a list of entity specific data types. See the specific Entity data model in its respective Entity Route document.

GET Individual

In addition to to the metaData object, every request to obtain an individual record will include a field called entity. This field will contain a JSON object. See the specific Entity data model in its respective Entity Route document.

POST Collection

In addition to to the metaData object, every request to create a Collection will include a field called details. The structure of the details object is:

Field Name	Data Type	Notes
`numTotal`	number	Total number of entities processed in a batch
`numSuccess`	number	Number of entities that were successfully created or updated
`numErrors`	number	Number of entities that failed to be created or updated
`errors`	EntityError[] or null

EntityError

Field Name	Data Type	Notes
`error`	string	The error message
`entity`	JSON	The failed entity

Example Response

"details": {
	"numTotal": 2,
	"numSuccess": 2,
	"numErrors": 0,
	"errors": null
},