API terms of use

About these terms

These API terms of use apply to anyone who calls the Easycoliv API: a business using its own API keys or OAuth client credentials, a partner such as a property management system acting for businesses that agreed to it, and anyone using the public search API. In these terms, "we" means Easycoliv and "you" means the person or business calling the API.

Our Terms of service also apply, and our Privacy notice explains how we handle personal data. The API reference lists every endpoint.

Keys, client secrets and tokens

API keys, OAuth client secrets, access tokens and webhook signing secrets are credentials. Keep them secret: store them on your own servers only, never in a website, a mobile app or a public code repository, and give each integration only the scopes it needs.

• If a credential may have leaked, rotate or revoke it at once (on the Developers page or through the API) and tell us.
• Access tokens work for one hour. Get a new one with your client secret when it runs out, instead of storing tokens.
• You are responsible for everything done with your credentials.

Partners acting for businesses

A partner may act for a business only while that business lets it, and only within the scopes it was given. Use a business's data only to provide your service to that business.

A business can withdraw a partner's access at any time on its Developers page. From then on the partner's requests for that business are refused, and its webhooks stop receiving that business's events.

Your right to list homes

When a business sends a listing through the API, including a file import made with an API key or access token, it confirms that it owns or manages the home, or that the owner has authorised it to list the home on Easycoliv. This applies to every home it sends, in every request and every import.

• When that authority ends, for example when a management agreement or lease ends or the owner withdraws permission, the business removes the listing straight away, through the API or in its workspace.
• A partner acting for a business confirms the same for every home it sends for that business.
• An API client's keys and access tokens add listings only after an owner or admin of the business accepts these terms for that client on the Developers page. A partner accepts them through the API. We record which version was accepted, by whom and when.

We may refuse, pause or remove a listing, and limit or revoke API access, when a business cannot show its right to list a home.

Public search API

GET /v1/search returns live listings with their public location: the neighbourhood address and an approximate pin, never the exact address. It takes the same filters as the search on Easycoliv (words, city, neighbourhood, landmark, map area, listing type, gender policy, amenities, beds per room, furnishing, length of stay, rent, verified operators, rooms free now and sort order). The API reference lists every parameter.

• Without a key you may make 30 requests a minute from each IP address, in bursts of up to 60. With an API key that has the search:read scope, your client's own rate limit applies instead.
• Each request returns up to 50 listings (24 if you do not ask), and results go up to 2,000 listings deep. Results can be up to a minute old.
• Show that the listings come from Easycoliv wherever you show them, link each home to its page on Easycoliv (the url of each result), and keep the operator's name with its listings.
• Do not present the listings as your own, or change prices, availability or photos in a way that misleads people.

Rate limits and scraping

Stay within the rate limits. Each answer carries RateLimit headers; after a 429 answer, wait for the time in Retry-After before trying again. Limits for API keys follow the plan shown on the pricing page.

Do not scrape Easycoliv pages instead of using the API, and do not use more IP addresses, keys, client secrets or accounts to get around a limit.

Tenant data

Leads, messages and tenants' contact details read through the API are only for answering those tenants on behalf of the business they contacted. The public search API returns no tenant data.

• Do not sell, rent or give tenant data to anyone else, and do not add tenants to marketing lists or combine their data with other data to profile them.
• Handle tenant data under the data protection law that applies to you, keep it safe, and delete it when the business no longer needs it.

Webhooks

Send webhooks only to HTTPS addresses you control, and check the X-Signature of every delivery before you trust it. Endpoints that keep failing are switched off, and we may pause an endpoint that misbehaves.

When we may stop access

We may limit, suspend or revoke API keys, client secrets, access tokens, partner access or webhook endpoints when these terms or the Terms of service are broken, when a credential may have leaked, or to protect tenants, businesses or the service. Where we can, we tell the business's owners and admins why.

Changes to the API and these terms

The API is versioned (/v1). We add to it without notice, and we announce changes that need you to act in the API changelog before they happen. We may update these terms; the date at the top of this page shows the latest version. When they change, an owner or admin accepts the new version for each API client before its keys can add listings again.

Contact

Questions about the API or these terms: contact the Easycoliv support team.