Getting Started with daisyBill API

This page will help you get started with the daisyBill API.

Authentication

To access the daisyBill API, API Tokens are used for authentication. All API requests must include the API Token in the authorization header.

Obtaining an API Token

To obtain an API Token, please follow these steps:

Log in to your daisyBill account at https://www.daisybill.com.
Navigate and click on the Integration dropdown on the right side of the top nav bar and click API Tokens.
Generate a new API Token by clicking the "Create API Token" button.
Copy the generated API Token securely.

Including the API Token in API Requests

To authorize your API requests, you can include the API Token in either the authorization header

Authorization Header

Include the API Token in the authorization header using the "Bearer" scheme.

Example using cURL:

curl --request GET \
  --url 'https://go.daisybill.com/api/v1/billing_providers' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {API_TOKEN}'

Replace {API_TOKEN} with your actual API Token.

Environment URLs

⚠️ Important: The daisyBill API has separate environments for production and sandbox testing. Make sure you're using the correct base URL for your environment.

Production Environment

API Base URL: https://go.daisybill.com/api/v1/

Sandbox Environment

API Base URL: https://demo-2.daisybill.com/api/v1/
Use this for testing
API tokens must be generated from your sandbox account

Common Mistake: Using production URLs (go.daisybill.com) with sandbox credentials will result in authentication errors. Always ensure your API token and base URL match the same environment.

Requests

Send request bodies as JSON with Content-Type: application/json. Fields go under the resource's wrapper key, for example {"bill": {...}}, {"pharmacy_bill": {...}}, {"remittance": {...}}. Each endpoint page shows its wrapper key.
POST, PUT and PATCH requests must not carry URL query parameters. A request such as POST /bills/1/notes?content=x returns 400.
Dates are ISO 8601 (YYYY-MM-DD); timestamps in responses include the time zone offset.
Nested collections (service_line_items_attributes, bill_payments_attributes, disputed_services_attributes, ...) are JSON arrays of objects.

Responses

Every resource returns created_at, updated_at, id, a links array of related resources, and context with the create_source of the record (API, Web, CSV Import, 837 Import, Background or Internal).
Fields with a null value may be omitted from the JSON.
Creates return 201 Created with the new record. Reads, updates and deletes return 200 OK.

Errors

The API uses standard HTTP status codes. Error bodies are JSON.

Status	When	Body
`400`	The record failed model validation	`{"errors": {"field_name": ["can't be blank"]}}`
`400`	The JSON body cannot be parsed, or a `POST`/`PUT`/`PATCH` request has URL query parameters	`{"error": "..."}`
`401`	The API token is missing or invalid, the user is not active, or the organization has no API access	`{"error": "API Token provided is not valid"}`
`402`	The organization is locked for an overdue invoice	`{"error": "Your organization is locked for overdue invoice."}`
`403`	A required parameter is missing, a parameter has the wrong type or an invalid value, `per_page` is above the maximum, a date filter has no operator, or the path is not a valid endpoint	`{"error": "bill is missing"}`
`404`	The record does not exist or your user cannot access it	`{"error": "404 not found"}`
`405`	The HTTP method is not allowed on the path	`{"error": "..."}`
`408`	The request timed out	`{"error": "Request timeout"}`
`422`	A state conflict, for example updating a task that is already resolved	`{"error": "..."}`
`429`	The rate limit was exceeded	`{"error": "Rate limit exceeded"}`
`500`	An unexpected error; daisyBill is notified automatically	`{"error": "Internal server error"}`

Parameter validation (403) happens before the record is loaded, so a request with a missing required field returns 403 even when the record does not exist.

Pagination

List endpoints are paginated. They accept three query parameters:

Parameter	Default	Description
`page`	`1`	Page to fetch
`per_page`	`25`	Results per page. Each endpoint page states its maximum (`25` for most lists, `100` for payers, claims administrators, users and billing-provider tasks). A larger value returns `403`.
`offset`	`0`	Skip this many results before the first page

Every list response carries the pagination in headers:

Header	Description
`X-Total`	Total number of records
`X-Total-Pages`	Total number of pages
`X-Per-Page`	Records per page
`X-Page`	Current page
`X-Next-Page`	Next page number, empty on the last page
`X-Prev-Page`	Previous page number, empty on the first page
`X-Offset`	The offset that was applied

curl --request GET \
  --url 'https://go.daisybill.com/api/v1/billing_providers/1/patients?page=2&per_page=25' \
  --header 'Authorization: Bearer {API_TOKEN}'

Filtering by date

Date filters on list endpoints (created_at, updated_at, date_of_service, bill_status_updated_at, effective_date, deposited_on, due_date) take an operator key. A bare date returns 403.

Operator	Meaning
`eq`	On the given date and time
`gt` / `gteq`	After / on or after
`lt` / `lteq`	Before / on or before
`is_null`	`true` or `false`; the only operator that may not be combined

Combine gt or gteq with lt or lteq for a range:

curl --request GET \
  --url 'https://go.daisybill.com/api/v1/billing_providers/1/bills?created_at[gteq]=2024-01-01&created_at[lt]=2024-02-01' \
  --header 'Authorization: Bearer {API_TOKEN}'

Rate limiting

Each user may make 100 requests per minute by default. Over the limit, requests return 429 until the minute resets. Every response carries:

Header	Description
`X-Rate-Limit-Limit`	Requests allowed per minute
`X-Rate-Limit-Remaining`	Requests remaining in the current minute
`X-Rate-Limit-Reset`	UTC time when the window resets

Security Recommendations

To maintain the security of your API Token, follow these best practices:

Keep your API Token confidential and do not share it with unauthorized individuals.
Regularly rotate your API Tokens to minimize the risk of unauthorized access.
Use secure methods to store and transmit your API Tokens, such as environment variables or secure credential storage systems.

Ruby Client

For Ruby developers, we offer a Ruby client library that simplifies making API requests and handling authentication. You can find the daisyBill Ruby client on our GitHub repository: https://github.com/daisybill/daisybill_api. The client provides convenient methods for including the API Token in requests and handling everyday tasks.

See the daisybill_api gem docs for more information

Examples

Five steps to submit a bill