Dash API FAQ

1. How do I authenticate and obtain an API token?

The Dash API uses the Client Credentials (RFC-6749) flow of OAuth 2.0 to issue JWTs. These JWTs should be used as bearer tokens when making requests to the API and remain valid for 24 hours.

See Authentication for more info.

2. How do I filter or search for specific data (e.g., customers, events, appointments)?

Use query parameters with filter[...] in your API requests. For example, to find events at a specific facility:

GET /v1/events?filter[resource.facility_id]=26&filter[end__gte]=2025-08-14&filter[start__lte]=2025-08-15

You can combine filters with operators like __gte, __lte, __icontains, and logical groupings (and/or). Check the API documentation for supported filters on each resource.

See Filter for more info.

3. How do I retrieve related data or use relationship routes?

The Dash API follows JSON:API conventions and supports inclusion of related data by using the include query parameter (docs) or relationship endpoints such as:

GET /v1/events/comments

Use these to fetch or update related resources (e.g., comments on events, team rosters). Always confirm that the relationship route is available for the resource you’re targeting.

⚠️ Warning ⚠️ Resources loaded using the include query parameter are not paginated so it is strongly discouraged to load has-many relationships using this method as the server will be prone to returning an error as it tries to process the request and runs out of memory due to the large dataset.

4. Why am I getting a 500 error or unexpected response from the API?

The meaning of the response depends on the HTTP status code. For instance, a status code in the 4xx range indicates an issue with the request with some specific examples laid out below:

• 400 Bad Request - Usually an error with the structure of the request body
• 401 Unauthorized - The request is required to be authorized and the server hasn't been provided a JWT
• 403 Forbidden - The provided JWT doesn't have the required permissions to perform the action
• 404 Not Found - The request was sent to a route or resource that doesn't exist
• 405 Method Not Allowed - The request uses an HTTP verb that is not supported for the route
• 422 Unprocessable Content - The request has valid structure but fails validation constraints
• 429 Too Many Requests - The client has reached the rate limit and must wait to make more requests

A 500 error signifies a server error, which could arise from trying to retrieve too much data at once which would cause the server to run out of memory when processing the request.

5. How do I update or patch nested/related resources (e.g., team rosters, relationships)?

If you want to swap the related resource for another, you can either update it directly on the parent resource:

PATCH /v1/resources/{id} HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "id": "{id}",
    "type": "resources",
    "relationships": {
      "facility": {
        "data": {
          "id": "{facility_id}",
          "type": "facilities"
        }
      }
    }
  }
}

⚠️ Warning ⚠️ Updating has-many relationships using this method performs a complete replacement of the related items. See the JSON:API specification for more details (specification).

Or use the relevant relationship endpoint, typically in the form:

PATCH /v1/resources/{id}/relationships/facility HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "id": "{facility_id}",
    "type": "facilities"
  }
}

See the JSON:API specification for more details (specification).

If you need to update attributes for the related resource, you must use that resource's update route. Following the previous examples, the route would be PATCH /v1/facilities/{facility_id}.

6. How do I handle timezones and date fields in the API?

Date/time values are returned in one of two ISO-8601 format variants.

1. 2025-08-20T23:48:20 - Older format, used most often but working on replacing with new format. Time zone is implied to be local to the resource.
2. 2025-08-20T23:48:20-07:00 - New format, time zone is either local to the resource and explicit, or UTC. Could use Z as timezone offset to denote UTC.

When sending date/times in requests, it is recommended to specify the time zone using the new format. If the provided time zone differs from the resource's local time zone, it will automatically be normalized when stored.

7. What permissions or scopes are required for specific API operations?

Permissions depend on the token’s scopes. • Some endpoints are publicly readable. • Most require authentication and explicit authorization.

8. How do I migrate or update API integrations when breaking changes occur?

Follow the API changelog for upcoming changes. If breaking changes are announced, update your integration promptly to match new endpoints or payloads.

Always regression-test against a sandbox environment before deploying to production.

9. How do I troubleshoot and resolve data integrity or validation issues?

If you get validation errors or inconsistent data: • Inspect the error messages in the API response. • Verify that your request matches the schema (types, required fields, allowed values). • For recurring issues, include example requests and responses when contacting support.

10. Sandbox Access & API Credentials

To experiment safely, request a sandbox environment and test API credentials from your Dash account manager or support team.

Sandbox environments mimic production but isolate your data. You’ll be issued a company code, client ID, and secret key for OAuth 2.0 token generation.

Always confirm whether features available in production are also enabled in sandbox before testing advanced flows.