This page covers authentication, pagination, rate limits, and other essentials for making API requests.

Authentication

All requests require Bearer token authentication via the Authorization header per RFC 6750.

Environment	Base URL
Production Live	`https://api.hint.com`
Production Sandbox (login at app.hint.com) NEW	`https://api.sandbox.hint.com`
Staging Sandbox (login at app.staging.hint.com)	`https://api.staging.hint.com`

curl -X GET "https://api.hint.com/api/provider/patients" \
     -H "Authorization: Bearer {your_api_key}"

📘
Practice API keys for patient and configuration data
Most API work uses the practice API key to access patient information and practice configuration via /api/provider/* endpoints. Partner-level endpoints (integrations, OAuth) use separate credentials. See the overview for credential details.

Pagination

List endpoints return paginated results. Control pagination with query parameters:

Parameter	Description	Default	Range
`limit`	Maximum results to return	10	1-100
`offset`	Number of results to skip	0	0-total

Example: Fetch results 20-29:

GET /api/provider/patients?limit=10&offset=20

Sorting

Use the sort parameter to order results by an attribute. Prepend - for descending order.

GET /api/provider/patients?sort=last_name
GET /api/provider/patients?sort=-created_at

Advanced Querying

Some endpoints support advanced filtering:

Numeric comparisons - Use gt, gte, lt, lte operators for date and number fields:

GET /api/provider/charges?date={"gte":"2015-05-01","lt":"2015-06-01"}
GET /api/provider/charges?created_at={"gt":"2015-02-19T10:49:21.419-08:00"}

String matching - Filter by exact attribute values (case-insensitive):

GET /api/provider/patients?first_name=joe

📘
Advanced querying availability
Advanced querying is available on select endpoints. See List Customer Invoices for a full example. Contact devsupport@hint.com if you need these capabilities on other endpoints.

Rate Limits

Hint enforces the following default limits:

Limit	Threshold
Requests per second	100
Requests per day	500,000

Exceeding these limits returns a 429 Too Many Requests response. Implement exponential backoff with jitter in your retry logic. Security anomalies may return 403 Forbidden.

For bulk operations, throttle requests and schedule during off-hours. Contact devsupport@hint.com to request limit adjustments.

⚠️
Hint reserves the right to modify rate limits without prior notice based on performance, usage, or abuse prevention. We will make reasonable efforts to notify you of changes affecting your integration.

Response Headers

List endpoints include metadata headers to help with pagination:

Header	Description	Example
`x-count`	Number of results in this response	`10`
`x-total-count`	Total number of results available	`342`

Use x-total-count to calculate total pages or determine when you've fetched all records.

Expanding Objects

Some objects contain nested references that can be expanded inline. Use the expand parameter to include full details of related objects in a single request.

curl "https://api.hint.com/api/provider/customer_invoices/inv-4IklwJi23xQ?expand=charges" \
     -H "Authorization: Bearer {token}"

📘
Expandable attributes are noted on each object's API reference page. Webhooks always contain the unexpanded version.

Idempotency & Integration Record IDs

The API supports integration record IDs (integration_record_id) on some objects. Use this field to store the corresponding ID from your system, enabling:

Alternative lookups - Query resources by integration_record_id in addition to Hint's native IDs
Duplicate prevention - Integration record IDs are enforced as unique per object type, preventing accidental duplicate creation
Sync status tracking - Hint uses presence of integration_record_id to surface sync status in the UI

# Create a patient with your system's ID
curl -X POST "https://api.hint.com/api/provider/patients" \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '{"first_name": "Jane", "last_name": "Doe", "integration_record_id": "your-system-id-123"}'

# Later, query by integration_record_id
curl "https://api.hint.com/api/provider/patients?integration_record_id=your-system-id-123" \
     -H "Authorization: Bearer {token}"

For complete guidance on integration records including weblinks, error messages, and sync status, see Best Practices.

HTTP Methods

📘
PUT and PATCH are treated the same
Anywhere you see a "PATCH" method in these docs, the API also accepts "PUT". Since we expect partial updates (not full object replacement), PATCH is preferred, but PUT requests are handled identically.

Errors

API errors include a status code and message. Status codes follow standard HTTP conventions.

Example: Creating a patient without a required field returns:

{
  "status": 422,
  "message": "Validation failed: First name can't be blank"
}

Status	Meaning
`400`	Bad request - malformed syntax or invalid parameters
`401`	Unauthorized - missing or invalid API key
`403`	Forbidden - valid key but insufficient permissions, or security flag
`404`	Not found - resource doesn't exist
`422`	Unprocessable entity - validation failed
`429`	Too many requests - rate limit exceeded
`5xx`	Server error - retry with exponential backoff

Community Libraries

Hint has one community-supported client library written in Go. If you've built your own, let us know at devsupport@hint.com to help other developers.

Go Hint - Maintained by the Spruce Health engineering team

Further Reading

Best Practices - Integration record IDs, sync status, and design patterns
Webhooks - Real-time event notifications