Making Requests

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.

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:

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 [email protected] if you need these capabilities on other endpoints.

Rate Limits

Hint enforces the following default limits:

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 [email protected] 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:

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"
}

Community Libraries

Hint has one community-supported client library written in Go. If you've built your own, let us know at [email protected] 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