Getting Started with daisyBill API

The daisyBill API is organized around REST. It has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP status codes, authentication and verbs.

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:

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

An API Token belongs to the user who created it. It reaches every billing provider that user can access, with that user's permissions. Tokens have no separate scopes, so a token cannot be made read-only.

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.

StatusWhenBody
400The record failed model validation{"errors": {"field_name": ["can't be blank"]}}
400The JSON body cannot be parsed, or a POST/PUT/PATCH request has URL query parameters{"error": "..."}
401The 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"}
402The organization is locked for an overdue invoice{"error": "Your organization is locked for overdue invoice."}
403A 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"}
404The record does not exist or your user cannot access it{"error": "404 not found"}
405The HTTP method is not allowed on the path{"error": "..."}
408The request timed out{"error": "Request timeout"}
422A state conflict, for example updating a task that is already resolved{"error": "..."}
429The rate limit was exceeded{"error": "Rate limit exceeded"}
500An 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:

ParameterDefaultDescription
page1Page to fetch
per_page25Results 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.
offset0Skip this many results before the first page

Every list response carries the pagination in headers:

HeaderDescription
X-TotalTotal number of records
X-Total-PagesTotal number of pages
X-Per-PageRecords per page
X-PageCurrent page
X-Next-PageNext page number, empty on the last page
X-Prev-PagePrevious page number, empty on the first page
X-OffsetThe 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.

OperatorMeaning
eqOn the given date and time
gt / gteqAfter / on or after
lt / lteqBefore / on or before
is_nulltrue or false; the only operator that may not be combined

A value is a date (2024-01-01) or a date and time (2024-01-01T08:00:00-08:00). A value without a time zone offset is read as UTC, so 2024-01-01 means midnight UTC. Timestamps in responses carry a time zone offset; keep the offset when you pass one back as a filter.

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

Syncing changes

To keep a copy of the data up to date, poll the list endpoints with the updated_at filter, or read the events.

  • Bills. A bill's updated_at changes when the bill record changes, when a payment on the bill is posted, changed or voided, and when the bill is closed with a write-off. A change of status alone does not change updated_at. It changes status_updated_at, which you filter with bill_status_updated_at. To catch every change, poll with both filters.
  • Remittances. A remittance's updated_at changes when deposited_on is set and when the remittance is voided. A remittance returns all of its bill payments, including voided ones; the nested list is not paginated.
  • Bill payments. There is no list of bill payments across bills. Read them from the remittance list, or per bill with GET /bills/{bill_id}/bill_payments. A change to a bill payment alone, for example matching it to a bill, updates the bill payment and the bill, not the remittance.
  • Deletions. A deleted record sends a deleted event, for example bill.deleted, patient.deleted or injury.deleted. Bill payments and remittances are never deleted; a void sends remittance.updated and bill_payment.updated, and the resource has void_date set.
  • Merges. When two patients or two injuries are merged, the duplicate sends a patient.deleted or injury.deleted event. The injuries and bills moved to the surviving record send injury.updated and bill.updated events.
  • Overlap your polls. updated_at is the time a change started, not the time it was saved, so a record can show up in a list shortly after its updated_at. Start each poll a few minutes before the previous one started, and update the records you already have by id.
  • Events can be read for 30 days.

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:

HeaderDescription
X-Rate-Limit-LimitRequests allowed per minute
X-Rate-Limit-RemainingRequests remaining in the current minute
X-Rate-Limit-ResetUTC time when the window resets

Security Recommendations

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

  1. Keep your API Token confidential and do not share it with unauthorized individuals.
  2. Regularly rotate your API Tokens to minimize the risk of unauthorized access.
  3. 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