Dragonfruit Sites API

Sites Import and Export

Overview

This document describes the customer-facing REST APIs for importing and exporting Sites and Site Contacts in bulk.

Base URL

These endpoints are served from Dragonfruit’s core service. The base url will be https://api-external.dragonfruit.ai/

Authentication

All endpoints require a Bearer token (JWT). Please get in touch with your account manager to get these.

Header:

Authorization: Bearer <token>

Content Types

• Import uses multipart/form-data with CSV file uploads.
• Export returns application/json.

Common Concepts

Customer ID

Most endpoints are scoped to a customer and require a customer_id path parameter. Your customer_id (Organization ID) can be accessed using the User > Settings > Organization section on the https://app.dragonfruit.ai

Success vs Validation Errors

The import endpoint may return success=true even when some rows contain validation errors. Validation feedback is returned in data.errors per uploaded sheet.

API Reference

Import Sites and/or Site Contacts

POST /customer/{customer_id}/sites/import

Upload one or two CSV files to create or update sites and site contacts in bulk. If both files are provided, they are processed together and any validation errors are returned per sheet.

Path parameters

Name	Type	Required
customer_id	integer	Yes

Request

• Content-Type: multipart/form-data
• Form fields:
•   - sites (file, optional): CSV containing sites.
•   - site_contacts (file, optional): CSV containing site contacts.
• You must provide at least one of the two files.

Sample CSV Files

site_template.csv

site_contacts_templage.csv

Example (sites only)

curl -X POST \
  "$BASE_URL/customer/123/sites/import" \
  -H "Authorization: Bearer $TOKEN" \
  -F "sites=@sites.csv"

Example (sites + contacts)

curl -X POST \
  "$BASE_URL/customer/123/sites/import" \
  -H "Authorization: Bearer $TOKEN" \
  -F "sites=@sites.csv" \
  -F "site_contacts=@site_contacts.csv"

Response (200)

Returns an import result with validation feedback.

• success (boolean)
• data.data (object): reserved for additional data.
• data.errors.sites (array of CsvErrorObject): validation errors for the sites sheet.
• data.errors.site_contacts (array of CsvErrorObject): validation errors for the site_contacts sheet.

CsvErrorObject

• row (integer): CSV row number (row numbering depends on your template).
• column (string): column/header name.
• value (string): raw value provided.
• error_msg (string): human-readable error.

Example: success with no errors

{
  "success": true,
  "data": {
    "data": {},
    "errors": {
      "sites": [],
      "site_contacts": []
    }
  }
}

Example: success with validation errors

{
  "success": true,
  "data": {
    "data": {},
    "errors": {
      "sites": [
        {
          "error_msg": "Invalid Operational Hours for Site ID 123 on row 5: Invalid JSON",
          "row": 5,
          "column": "Operational Hours",
          "value": "[{bad json]"
        }
      ],
      "site_contacts": []
    }
  }
}

Operational Hours format

When using an Operational Hours column, the value is expected to be a JSON array of objects with days, start, and end values.

• days (array of strings, e.g., Mon, Tue, ...)
• start (string, HH:MM)
• end (string, HH:MM)

Example:

[
  {"days": ["Mon","Tue","Wed","Thu","Fri"], "start": "09:00", "end": "18:59"},
  {"days": ["Sat","Sun"], "start": "07:00", "end": "20:00"}
]

Export Sites Data

GET /customer/{customer_id}/sites/export

Export sites in JSON format. Supports pagination and optional filtering by external IDs.

Parameters

Name	In	Type	Notes
customer_id	path	integer	Required
p_number	query	integer	Optional, default 1 (page number, 1-based)
p_size	query	integer	Optional (page size)
site_external_ids	query	string	Optional; comma-separated list of external IDs

Example:

curl -X GET \
  "$BASE_URL/customer/123/sites/export?p_number=1&p_size=100" \
  -H "Authorization: Bearer $TOKEN"

Response (200)

• success (boolean)
• data (array of ExportedSite)
• p_number (integer)
• p_size (integer)
• total (integer): total matching records
• total_pages (integer)

ExportedSite fields

Field	Type
Site ID	string
Site Name	string
Address Street	string
Address City	string
Address State	string
Address Country	string
Address Postal Code	string
Shipping Address Street	string
Shipping Address City	string
Shipping Address State	string
Shipping Address Country	string
Shipping Address Postal Code	string
Site Groups	string
Escalation Path	string
Timezone	string
Currency	string
Operational Hours	array of OperationalHours

Example response

{
  "success": true,
  "data": [
    {
      "Site ID": "site-123",
      "Site Name": "Downtown Store",
      "Address Street": "1 Main St",
      "Address City": "San Francisco",
      "Address State": "CA",
      "Address Country": "USA",
      "Address Postal Code": "94105",
      "Shipping Address Street": "1 Main St",
      "Shipping Address City": "San Francisco",
      "Shipping Address State": "CA",
      "Shipping Address Country": "USA",
      "Shipping Address Postal Code": "94105",
      "Site Groups": "Retail,West",
      "Escalation Path": "Ops Team",
      "Timezone": "America/Los_Angeles",
      "Currency": "USD",
      "Operational Hours": [
        {
          "days": [
            "Mon",
            "Tue",
            "Wed",
            "Thu",
            "Fri"
          ],
          "start": "09:00",
          "end": "18:59"
        }
      ]
    }
  ],
  "p_number": 1,
  "p_size": 100,
  "total_pages": 3,
  "total": 250
}

Token Expiry

ID tokens expire after a predetermined period of time. You can generate a new ID token using the refresh tokens. Please use the following API to generate new tokens.

API Reference

POST /get_new_tokens

Parameters

Name	In	Type	Notes
refresh_token	body	string	Required

Example:

Response (200)

Returns a fresh set of tokens to use for APIs calls.

Example Response:

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

Error Handling

This document mentions only 200 responses for these endpoints. APIs may also return standard HTTP error codes such as 401, 403, 413, and 500. When an error occurs, the response body format may differ from the success schema.

Support

If you encounter repeated validation errors, request the latest CSV templates and field requirements from Dragonfruit Support on support@dragonfruit.ai.