Version 1

Hallie API

A read-only HTTP API over the Google reviews of your Business Profiles. It exists so your own website can show them: fetch them, style them, cache them — they are your reviews.

Endpoints

Two, and the first one exists to feed the second.

GET /profiles

List your Business Profiles

Every profile this organization pays for, and the id the reviews endpoint is addressed by.

GET /profiles/{profile_id}/reviews

List a profile's reviews

The reviews Google publishes for one profile, with filtering, sorting and paging.

Base URL

https://api.hallie.app/v1

Every response is JSON. Every request must be made over HTTPS.

Authentication

Send a bearer token. The account owner creates one under Organization → API tokens, and it is shown once at creation — if it is lost, revoke it and issue another.

Authorization: Bearer YOUR_TOKEN
Accept: application/json

The token is a secret

It reads every review of every profile in the organization. Call this API from your server, never from the visitor's browser, or the token ships with the page.

Paging

Both lists page the same way, and both answer with links and meta alongside data. To walk everything, follow links.next until it comes back null — it already carries the query you sent. To show a count instead, meta.to and meta.total tell you how far you are.

Parameter	Values	Default	Description
per_page	1–100	25	Reviews per page.
page	integer	1	Which page to read. The response also links to the next one.

Rate limit

120 requests per minute, counted per organization rather than per token — issuing a second token does not raise the ceiling. Over it, the API answers 429 with a Retry-After header.

Cache on your side

Reviews are refreshed from Google once a day, so calling this on every page view buys nothing. Fetch periodically and serve from your own cache. Responses carry an ETag, so a repeated request costs you nothing when nothing changed.

Errors

Status	Meaning	When
401	Unauthenticated	The token is missing, malformed or has been revoked.
403	Forbidden	The token is valid but lacks the reviews:read ability.
404	Not found	No Business Profile of yours matches that id. A profile belonging to someone else answers the same way.
422	Invalid parameter	A query parameter is outside its allowed values. The body names the offending one.
429	Too many requests	You went over the rate limit. Retry-After tells you how long to wait.

Versioning

The version is in the path. Fields may be added to a response without notice — ignore the ones you do not use — but nothing is removed or renamed inside v1. A breaking change ships as v2.