Skip to content
English
More support Customer portal Sign in
  • There are no suggestions because the search field is empty.

Dragonfruit APIs - Common API Guide

A quick-start reference for Dragonfruit APIs covering base URLs, authentication and token refresh, customer scoping, request/response content types, and common conventions for validation and error handling.

Overview

This guide covers the shared conventions and requirements for calling Dragonfruit’s external REST APIs. Individual API documents will describe endpoint-specific behavior (paths, request/response schemas, and examples), but the items below apply broadly across Dragonfruit APIs unless stated otherwise.

Base URL

Dragonfruit exposes APIs from different services/environments. Your API documentation or account manager will confirm which base URL applies to your use case.

Primary External API Base URL

  • https://api-external.dragonfruit.ai/

Some endpoints may be hosted under a different base URL depending on product area or region. Always follow the base URL specified in the endpoint-specific documentation.

Authentication

All endpoints require a Bearer token (JWT).

Header

Authorization: Bearer <token>

Getting a token

Tokens are issued and managed by Dragonfruit. Please contact your account manager or Dragonfruit Support to obtain credentials and onboarding instructions.

Token Expiry and Refresh

Token expiry

Dragonfruit ID tokens expire after a predetermined period of time. When an ID token expires, you must generate a fresh set of tokens using a refresh token.

Generate new tokens

Use the endpoint below to exchange a refresh token for a new set of tokens.

API Reference
POST /get_new_tokens

Request

Headers

  • Content-Type: application/json

  • Authorization: Bearer <token> (if required for your setup; follow your issued credentials)

Body Parameters

Name In Type Notes
refreshToken body string Required. Refresh token issued by Dragonfruit.

Example (cURL)

curl --location 'https://df-services.dragonfruit.ai/get_new_tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ••••••' \
--data '{
"refreshToken": "••••••"
}'
 

Response (200)

Returns a fresh set of tokens for subsequent API calls.

Example Response

 
{
    "data": {
        "AccessToken": "••••••",
        "ExpiresIn": 3600,
        "IdToken": "••••••",
        "TokenType": "Bearer"
    },
    "success": true
}
 

Usage notes

  • Use the returned AccessToken/IdToken for future API calls as instructed in your endpoint documentation.

  • ExpiresIn is the token lifetime in seconds (example: 3600 = 1 hour).

  • Keep refresh tokens secure and store them server-side wherever possible.

Content Types

Dragonfruit APIs may support different content types depending on the endpoint:

  • JSON requests: application/json

  • File uploads (bulk import): commonly multipart/form-data (often with CSV attachments)

  • Binary downloads: some endpoints may return files (e.g., CSV exports) where applicable

Each endpoint document will specify required headers, body format, and examples.

Common Concepts

Customer ID (Organization Scope)

Most endpoints are scoped to a customer and require a customer_id path parameter (sometimes called an Organization ID).

You can find your Organization/Customer ID in:

  • https://app.dragonfruit.ai → User → Settings → Organization

If your API uses different scoping (e.g., project/site scoping), it will be documented per endpoint.

Identifiers and Naming

  • IDs are typically stable, unique identifiers used to reference resources (e.g., sites, contacts).

  • Some resources also support human-readable names, but IDs should be used for integration logic whenever available.

Success, Partial Success, and Validation Errors

Some endpoints—especially bulk import—may return an HTTP 200 response even if one or more rows fail validation.

  • A request can be “successful” at the request level while containing row-level validation errors.

  • Validation feedback is typically returned in a structured field such as data.errors (exact location depends on the API).

Integration guidance

  • Always check both:

    1. HTTP status code

    2. The response body fields indicating per-item or per-row success/failure

Endpoint docs will specify the success and error fields to inspect.

Error Handling

In addition to normal “success” responses, APIs may return standard HTTP error codes including (but not limited to):

  • 400 Bad Request (malformed input)

  • 401 Unauthorized (missing/invalid token)

  • 403 Forbidden (token lacks permission)

  • 404 Not Found

  • 409 Conflict (state/duplicate constraints)

  • 413 Payload Too Large (upload too large)

  • 429 Too Many Requests (rate-limited)

  • 500 / 502 / 503 Server errors

Important

  • When an error occurs, the response body format may differ from the success schema.

  • Your client should be resilient: log the status code, headers, and raw response body for troubleshooting.

Rate Limiting and Retries

Some APIs may enforce rate limits.

Recommended client behavior

  • On 429: retry with backoff (respect any Retry-After header if present).

  • On 5xx: retry with exponential backoff and jitter.

  • Avoid retrying 4xx errors other than 429 unless the client can correct the request.

If an endpoint has stricter limits or specific retry guidance, it will be described in that API’s documentation.

Support

If you encounter repeated validation errors, unexpected responses, or need the latest CSV templates/field requirements:

When contacting support, include:

  • Endpoint path and method

  • Timestamp (with timezone)

  • Request ID header (if returned)

  • HTTP status code

  • Response body (redact sensitive data)

  • A sample payload (redacted) or the CSV causing the issue