Circuit Auction Backoffice API Documentation

Base URL

https://backoffice.ddev.site/api/v1.0/

Authentication

All API endpoints require authentication using one of the following methods:

Back Office Authentication

Endpoint: POST /api/v1.0/bo_auth

Request:

{
  "username": "[email protected]",
  "password": "securePassword123"
}

Response:

{
  "data": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "user": {
      "id": "1",
      "name": "John Doe",
      "email": "[email protected]",
      "roles": ["administrator"]
    }
  }
}

Include the access token in subsequent requests:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Clients

List Clients (DataTable)

Retrieve a paginated list of clients with advanced filtering and sorting.

Endpoint: GET /api/v1.0/datatable-clients

Query Parameters:

range - Items per page (default: 25)
page - Page number (default: 0)
sort - Sort field and direction (e.g., -id for descending)
filter[field_name] - Filter by field value
filter[field_name][value] - Filter value
filter[field_name][operator] - Filter operator (e.g., IN, BETWEEN, LIKE)
fields - Comma-separated list of fields to return
global_search - Search across multiple fields

Available Filters:

status - Client status (new, pending, approved, unapproved, deleted)
first_name - First name (regex search)
last_name_company - Last name or company name (regex search)
email - Email address (regex search)
phone - Phone number (regex search)
country - Country code (exact match or IN operator)
city - City name (regex search)
state - State/province (regex search)
postal_code - Postal/ZIP code (regex search)
default_payment_method - Payment method ID
source - Client source/origin ID
updated - Last updated date range
philaworksplace_id - Customer ID (regex search)

Example Request - Basic List:

GET /api/v1.0/datatable-clients?range=25&sort=-updated

Example Request - Filter by Status:

GET /api/v1.0/datatable-clients?filter[status]=approved&range=50

Example Request - Multiple Filters:

GET /api/v1.0/datatable-clients?filter[status]=approved&filter[country]=US&sort=-updated&range=25

Example Request - Search by Name:

GET /api/v1.0/datatable-clients?global_search=john&range=25

Example Request - Filter by Multiple UUIDs (IN operator):

GET /api/v1.0/datatable-clients?filter[uuid][value][0]=abc123&filter[uuid][value][1]=def456&filter[uuid][operator]=IN&fields=id,uuid,first_name,last_name,philaworksplace_id

Example Request - Date Range Filter:

GET /api/v1.0/datatable-clients?filter[updated][value][from]=2025-01-01&filter[updated][value][to]=2025-12-31

Response:

{
  "data": [
    {
      "id": "123",
      "uuid": "abc-def-123",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "+1-555-0123",
      "philaworksplace_id": "C12345",
      "status": {
        "id": "approved",
        "label": "Approved"
      },
      "address": {
        "country": "US",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "street": "123 Main St"
      },
      "balance": {
        "value": 1250.50,
        "formatted": "$1,250.50"
      },
      "default_payment_method": {
        "id": "3",
        "label": "Credit Card"
      },
      "source": {
        "id": "5",
        "label": "Website"
      },
      "updated": "2025-10-15T14:30:00Z"
    }
  ],
  "count": 342
}

Get Single Client

Endpoint: GET /api/v1.0/datatable-clients/{id}

Example:

GET /api/v1.0/datatable-clients/123

Response:

{
  "data": [{
    "id": "123",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "tax_id": "123-45-6789",
    "categories": [
      {"id": "10", "label": "Modern Art"},
      {"id": "15", "label": "Antiques"}
    ],
    "additional_charges": [],
    "consignor_commissions": [
      {
        "consignor_commission": "15.00",
        "step_from": "0.00"
      }
    ],
    ...
  }]
}

Create Client

Endpoint: POST /api/v1.0/datatable-clients

Request:

{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "[email protected]",
  "phone": "+1-555-0199",
  "mobile": "+1-555-0200",
  "status": "new",
  "categories": ["10", "15"],
  "subscription_type": "email"
}

Response:

{
  "data": [{
    "id": "456",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]",
    "philaworksplace_id": "C12348",
    "status": {
      "id": "new",
      "label": "New"
    },
    "created": "2025-10-30T10:00:00Z"
  }]
}

Note: Client addresses are managed separately via the /client-address endpoint. After creating a client, use POST /api/v1.0/client-address to add addresses for the client.

Update Client

Endpoint: PATCH /api/v1.0/datatable-clients/{id}

Request:

{
  "status": "approved",
  "phone": "+1-555-0200",
  "categories": ["10", "15", "20"]
}

Update Client Status

Endpoint: PATCH /api/v1.0/datatable-clients/{id}

Request:

{
  "status": "approved"
}

Client Connect

Connect two or more client records together.

Endpoint: POST /api/v1.0/client-connect

Request:

{
  "clients": ["123", "456"],
  "primary_client": "123"
}

Client Merge

Merge multiple client records into one.

Endpoint: POST /api/v1.0/client-merge

Request:

{
  "source_clients": ["456", "789"],
  "target_client": "123",
  "merge_transactions": true,
  "merge_orders": true,
  "merge_items": true
}

Response:

{
  "data": {
    "merged_client_id": "123",
    "merged_count": 2,
    "deleted_clients": ["456", "789"]
  }
}

Client Address

Get formatted client address.

Endpoint: GET /api/v1.0/client-address

Query Parameters:

client_id - Client ID

Client Statistics

Endpoint: GET /api/v1.0/client-stat

Query Parameters:

filter[client] - Client ID
filter[sale] - Sale ID (optional)

Response:

{
  "data": [{
    "total_orders": 15,
    "total_spent": "12500.00",
    "total_items_won": 42,
    "average_order_value": "833.33",
    "last_purchase_date": "2025-10-01"
  }]
}

Connected Entities

Get entities connected to a client.

Endpoint: GET /api/v1.0/connected-entities

Query Parameters:

uuid - Client UUID

Example:

GET /api/v1.0/connected-entities?uuid=abc-def-123

Client Addresses

List Client Addresses

Retrieve addresses for a specific client.

Endpoint: GET /api/v1.0/client-address

Query Parameters:

filter[client] - Client ID to filter addresses
sort - Sort field and direction

Example:

GET /api/v1.0/client-address?filter[client]=123

Response:

{
  "data": [
    {
      "id": "501",
      "label": "Default address - US - 10001",
      "client": "123",
      "address": {
        "country": "US",
        "administrative_area": "NY",
        "locality": "New York",
        "postal_code": "10001",
        "thoroughfare": "123 Main St",
        "premise": "",
        "name_line": "John Doe",
        "first_name": "John",
        "last_name": "Doe"
      },
      "address_types": [
        {
          "id": "billing",
          "label": "Billing"
        },
        {
          "id": "shipping",
          "label": "Shipping"
        }
      ],
      "default_address": true,
      "validated": true,
      "rendered": "John Doe\n123 Main St\nNew York, NY 10001\nUnited States",
      "created": "2025-10-01T10:00:00Z",
      "updated": "2025-10-15T14:30:00Z"
    }
  ],
  "count": 1
}

Get Single Address

Endpoint: GET /api/v1.0/client-address/{id}

Example:

GET /api/v1.0/client-address/501

Create Client Address

Endpoint: POST /api/v1.0/client-address

Request:

{
  "client": "123",
  "address": {
    "country": "US",
    "administrative_area": "NY",
    "locality": "New York",
    "postal_code": "10001",
    "thoroughfare": "123 Main St",
    "premise": "Apt 4B",
    "first_name": "John",
    "last_name": "Doe"
  },
  "address_types": ["billing", "shipping"],
  "default_address": true
}

Response:

{
  "data": [{
    "id": "502",
    "client": "123",
    "address": {
      "country": "US",
      "administrative_area": "NY",
      "locality": "New York",
      "postal_code": "10001",
      "thoroughfare": "123 Main St",
      "premise": "Apt 4B",
      "first_name": "John",
      "last_name": "Doe",
      "name_line": "John Doe"
    },
    "address_types": [
      {
        "id": "billing",
        "label": "Billing"
      },
      {
        "id": "shipping",
        "label": "Shipping"
      }
    ],
    "default_address": true,
    "created": "2025-10-30T10:00:00Z"
  }]
}

Update Client Address

Endpoint: PATCH /api/v1.0/client-address/{id}

Request:

{
  "address": {
    "thoroughfare": "456 Broadway",
    "premise": "Suite 100"
  },
  "default_address": true
}

Delete Client Address

Endpoint: DELETE /api/v1.0/client-address/{id}

Response:

{
  "data": [],
  "status": 204
}

Notes:

You cannot delete a client's default address if it's the only address
If you delete the default address and other addresses exist, the system will automatically assign another address as the default
Addresses must be associated with a client using the client field

Orders

List Orders

Retrieve a paginated list of orders with filtering.

Endpoint: GET /api/v1.0/orders

Query Parameters:

range - Items per page
page - Page number
sort - Sort field and direction
filter[type] - Order type (bidder, consignor, credit_note, transport_invoice)
filter[status] - Order status (new, in_process, finished, locked, canceled)
filter[sale] - Sale ID
filter[owner] - Client ID
filter[order_id] - Order/invoice number
filter[customer_number] - Customer number
filter[total_invoice][value][from] - Min amount
filter[total_invoice][value][to] - Max amount
filter[payment_received][value][from] - Min paid amount
filter[payment_received][value][to] - Max paid amount
filter[bidder_ids] - Bidder number search
filter[payment_type_letter] - Payment method
filter[sale_name] - Sale name search
filter[shipping_weight][value][from] - Min weight (in kg)
filter[shipping_weight][value][to] - Max weight (in kg)
fields - Specific fields to return

Example Request - Bidder Orders for a Sale:

GET /api/v1.0/orders?filter[type]=bidder&filter[sale]=456&filter[status]=new&range=25&sort=-order_id

Example Request - Orders with Amount Range:

GET /api/v1.0/orders?filter[type]=bidder&filter[total_invoice][value][from]=100&filter[total_invoice][value][to]=1000

Example Request - Search by Bidder Number:

GET /api/v1.0/orders?filter[bidder_ids]=12345&range=50

Response:

{
  "data": [
    {
      "id": "789",
      "label": "Order #12345",
      "order_id": "12345",
      "type": "bidder",
      "status": {
        "id": "new",
        "label": "New"
      },
      "sale": {
        "id": "456",
        "label": "Summer Auction 2025"
      },
      "owner": {
        "id": "123",
        "label": "John Doe",
        "email": "[email protected]"
      },
      "grand_total": "1250.00",
      "amount_due": "1250.00",
      "payment_received": "0.00",
      "customer_number": "C12345",
      "bidder_ids": ["12345", "12346"],
      "item_count": 5,
      "shipping_weight": 2.5,
      "payment_type_letter": "CC",
      "invoice_data": {
        "header_left": {...},
        "header_right": {...},
        "items": {...},
        "totals_for_display": [...]
      },
      "created": "2025-10-01T10:00:00Z",
      "changed": "2025-10-15T14:30:00Z"
    }
  ],
  "count": 42
}

Get Single Order

Endpoint: GET /api/v1.0/orders/{id}

Example:

GET /api/v1.0/orders/789

Response:

{
  "data": [{
    "id": "789",
    "order_id": "12345",
    "type": "bidder",
    "status": {
      "id": "new",
      "label": "New"
    },
    "sale": {...},
    "owner": {...},
    "invoice_data": {
      "header_left": {
        "buyer_address": {...},
        "shipping_address": {...}
      },
      "header_right": {
        "invoice_number": "12345",
        "customer_number": "C12345",
        "bidder_number": "12345",
        "vat_number": "123-45-6789"
      },
      "items": {
        "12345": [
          {
            "nid": "345",
            "lot": "1234",
            "description": "Beautiful antique vase",
            "hammer_price": "250.00",
            "commission": "50.00",
            "tax_id": "6",
            "consignment_number": "A-100"
          }
        ]
      },
      "totals_for_display": [
        [
          {"label": "Subtotal", "value": "$1,000.00"},
          {"label": "Buyer's Premium", "value": "$200.00"}
        ],
        [
          {"label": "Tax", "value": "$50.00"},
          {"label": "Grand Total", "value": "$1,250.00"}
        ]
      ]
    },
    "additional_charges": [
      {
        "term": {
          "id": "5",
          "label": "Shipping Fee"
        },
        "amount": "25.00",
        "tax": "21.00",
        "description": "Standard shipping",
        "date": "2025-10-01"
      }
    ],
    ...
  }]
}

Create Order

Endpoint: POST /api/v1.0/orders

Request:

{
  "type": "bidder",
  "sale": "456",
  "owner": "123",
  "status": "new",
  "items": ["345", "346", "347"],
  "additional_charges": []
}

Update Order

Endpoint: PATCH /api/v1.0/orders/{id}

Request:

{
  "status": "in_process",
  "additional_charges": [
    {
      "term": "5",
      "amount": "25.00",
      "tax": "21.00",
      "description": "Shipping fee"
    }
  ],
  "use_custom_address": true,
  "custom_address": {
    "name_line": "Jane Smith",
    "thoroughfare": "789 Pine St",
    "locality": "Boston",
    "administrative_area": "MA",
    "postal_code": "02101",
    "country": "US"
  }
}

Update Order Status

Endpoint: PATCH /api/v1.0/orders/{id}

Request:

{
  "status": "finished"
}

Split Order

Split items from an order into a new or existing order.

Endpoint: PATCH /api/v1.0/order-split

Request:

{
  "order": "789",
  "items": ["345", "346", "347"]
}

Response:

{
  "data": {
    "new_order_id": "890",
    "original_order_id": "789",
    "moved_items": ["345", "346", "347"]
  }
}

Note: If there's an existing open order for the same client in the same sale, items will be merged into that order instead of creating a new one.

Create Credit Note

Create a credit note for specific items in a finished/locked order.

Endpoint: POST /api/v1.0/order-create-credit-note/{order_id}

Request:

{
  "items": ["345", "346"]
}

Response:

{
  "data": {
    "credit_note_order_nid": "891"
  }
}

Note: Maximum 100 items per credit note. Order must be in 'finished' or 'locked' status.

Cancel and Reissue Order

Cancel a locked order and create a new one with all items (creates credit note + new order).

Endpoint: POST /api/v1.0/order-cancel-and-reissue/{order_id}

Request Body: None required

Response:

{
  "data": {
    "new_order_nid": "892",
    "credit_note_nid": "893"
  }
}

Note: Only works on locked orders. Used when an invoice needs to be corrected after being exported to accounting system.

Print Order

Generate a printable order/invoice.

Endpoint: POST /api/v1.0/order-print

Request:

{
  "order_id": "789",
  "signal": "white_bidder_invoice",
  "withDescription": true,
  "with_letterhead": 1
}

Signals:

white_bidder_invoice - Standard bidder invoice
accounting - Accounting format
via_bulk - Bulk print format

Orders Attached Text

Get prepend/append text for orders.

Endpoint: GET /api/v1.0/orders-attached-text

Query Parameters:

filter[order] - Order ID

Reset Additional Charges

Reset order additional charges to match consignment charges.

Endpoint: PATCH /api/v1.0/reset-statement-charges/{order_id}

Request Body: None required

Response:

{
  "data": {
    "success": true,
    "charges_reset": 3
  }
}

Consignments

List Consignments (DataTable)

Retrieve a paginated list of consignments.

Endpoint: GET /api/v1.0/datatable-consignments

Query Parameters:

range - Items per page
page - Page number
sort - Sort field and direction
filter[sale] - Sale ID
filter[symbol] - Consignment symbol
filter[owner] - Consignor client ID
filter[status] - Consignment status
fields - Specific fields to return

Example Request:

GET /api/v1.0/datatable-consignments?filter[sale]=456&sort=symbol&range=50

Response:

{
  "data": [
    {
      "id": "234",
      "label": "Consignment #567",
      "symbol": "A",
      "sub_symbol": "1",
      "sale": {
        "id": "456",
        "label": "Summer Auction 2025"
      },
      "owner": {
        "id": "789",
        "label": "Art Gallery LLC"
      },
      "consignor_commission": "15.00",
      "payment_instructions": "Wire transfer to account...",
      "item_count": 25,
      "total_hammer_price": "15000.00",
      "status": "active"
    }
  ],
  "count": 15
}

Consignment Statements (DataTable)

Get consignment statements.

Endpoint: GET /api/v1.0/datatable-consignment-statements

Query Parameters:

filter[sale] - Sale ID
filter[owner] - Consignor ID
filter[status] - Statement status

Consignments Underbids Inquiries

Get inquiries about items that didn't meet reserve/minimum.

Endpoint: GET /api/v1.0/consignments-underbids-inquiries

Query Parameters:

filter[sale] - Sale ID
filter[consignment] - Consignment ID

Control List Consigner

Get control list for consigners.

Endpoint: GET /api/v1.0/control-list-consigner

Query Parameters:

filter[sale] - Sale ID

Example - Search by Customer Number:

GET /api/v1.0/datatable-consignment-statements?filter[customer_number]=12345&range=50

Example Response:

{
  "data": [
    {
      "consignment_id": "123",
      "customer_number": "12345",
      "consignor_label": "John Doe",
      "order_id": "456",
      "status": "finished",
      "owner_email": "[email protected]",
      "total": "5000.00",
      "actually_paid": "4500.00",
      "received_from_buyers": "5000.00"
    }
  ],
  "count": 1,
  "recordsTotal": 100,
  "recordsFiltered": 1
}

Notes:

The prepare function handles special fields: additional_charges, append_text, prepend_text, label
Table name: consignment_statements
Supports multiple status filters simultaneously
All text filters support regex pattern matching

Items

List Items (DataTable)

Retrieve a paginated list of items with extensive filtering.

Endpoint: GET /api/v1.0/datatable-items

Query Parameters:

range - Items per page
page - Page number
sort - Sort field and direction
filter[sale] - Sale ID
filter[consignment] - Consignment ID
filter[category] - Category ID
filter[status] - Item status (available, sold, unsold, passed, withdrawn)
filter[lot] - Lot number search
filter[description] - Description search (regex)
filter[estimate_low][value][from] - Min low estimate
filter[estimate_low][value][to] - Max low estimate
filter[estimate_high][value][from] - Min high estimate
filter[estimate_high][value][to] - Max high estimate
filter[hammer_price][value][from] - Min hammer price
filter[hammer_price][value][to] - Max hammer price
filter[consignor_symbol] - Consignment symbol search
fields - Specific fields

Example Request - Items in Sale:

GET /api/v1.0/datatable-items?filter[sale]=456&filter[status]=available&range=50&sort=lot

Example Request - Sold Items with Price Range:

GET /api/v1.0/datatable-items?filter[sale]=456&filter[status]=sold&filter[hammer_price][value][from]=100&filter[hammer_price][value][to]=1000&sort=-hammer_price

Example Request - Search by Category:

GET /api/v1.0/datatable-items?filter[sale]=456&filter[category]=10&range=100

Response:

{
  "data": [
    {
      "id": "345",
      "label": "Item #1234",
      "lot": "1234",
      "description": "Beautiful antique vase from the Ming Dynasty",
      "sale": {
        "id": "456",
        "label": "Summer Auction 2025"
      },
      "consignment": {
        "id": "234",
        "symbol": "A",
        "sub_symbol": "1"
      },
      "category": {
        "id": "10",
        "label": "Ceramics"
      },
      "estimate_low": "100.00",
      "estimate_high": "200.00",
      "reserve_price": "80.00",
      "hammer_price": "250.00",
      "status": "sold",
      "winner": {
        "id": "123",
        "label": "John Doe",
        "bidder_number": "12345"
      },
      "images": [
        {
          "id": "1001",
          "url": "https://.../files/item-images/vase-1.jpg",
          "thumbnail": "https://.../files/item-images/vase-1-thumb.jpg"
        }
      ],
      "dimensions": {
        "height": "30cm",
        "width": "15cm",
        "depth": "15cm"
      },
      "created": "2025-09-01T10:00:00Z",
      "updated": "2025-10-15T14:30:00Z"
    }
  ],
  "count": 250
}

Get Single Item

Endpoint: GET /api/v1.0/datatable-items/{id}

Items List (Simple)

Get a simpler list of items without full datatable features.

Endpoint: GET /api/v1.0/items-list

Query Parameters:

filter[sale] - Sale ID
range - Items per page

Items JSON

Get items in JSON format with specific formatting.

Endpoint: GET /api/v1.0/items-json

Query Parameters:

filter[sale] - Sale ID
fields - Comma-separated field list

Example:

GET /api/v1.0/items-json?filter[sale]=456&fields=id,lot,description,estimate_low,estimate_high

Items Public

Get publicly available items (for frontend/catalog).

Endpoint: GET /api/v1.0/items-public

Query Parameters:

filter[sale] - Sale ID
range - Items per page
sort - Sort order

Example:

GET /api/v1.0/items-public?filter[sale]=456&range=100&sort=lot

Items Lots

Get items with lot number information.

Endpoint: GET /api/v1.0/items-lots

Query Parameters:

sale - Sale ID

Example:

GET /api/v1.0/items-lots?sale=456

Response:

{
  "data": [
    {
      "id": "345",
      "lot": "1234",
      "position": 1
    },
    {
      "id": "346",
      "lot": "1235",
      "position": 2
    }
  ]
}

Items Bulk Operations

Perform bulk operations on multiple items.

Endpoint: POST /api/v1.0/items-bulk

Request - Update Status:

{
  "operation": "update_status",
  "items": ["345", "346", "347"],
  "values": {
    "status": "withdrawn"
  }
}

Request - Update Category:

{
  "operation": "update_field",
  "items": ["345", "346"],
  "field": "category",
  "value": "15"
}

Request - Delete Items:

{
  "operation": "delete",
  "items": ["345", "346"]
}

Items Bulk Edit (Lot Numbers)

Update lot numbers for multiple items.

Endpoint: PATCH /api/v1.0/items-bulk-edit

Request:

{
  "items": [
    {"id": "345", "lot": "1234"},
    {"id": "346", "lot": "1235"},
    {"id": "347", "lot": "1236"}
  ]
}

Clone or Move Items

Clone or move items between sales/consignments.

Endpoint: POST /api/v1.0/item-clone-or-move

Request - Move Items:

{
  "items": ["345", "346", "347"],
  "operation": "move",
  "target_sale": "457",
  "target_consignment": "235"
}

Request - Clone Items:

{
  "items": ["345", "346"],
  "operation": "clone",
  "target_sale": "457",
  "target_consignment": "235"
}

Response:

{
  "data": {
    "success": true,
    "operation": "move",
    "items_processed": 3,
    "new_item_ids": ["445", "446", "447"]
  }
}

Item Dimensions

Get/update item dimensions.

Endpoint: GET /api/v1.0/item-dimensions

Query Parameters:

filter[item] - Item ID

Endpoint: PATCH /api/v1.0/item-dimensions/{dimension_id}

Request:

{
  "height": "30",
  "width": "15",
  "depth": "15",
  "weight": "2.5",
  "unit": "cm"
}

Items Histories

Get item history/audit trail.

Endpoint: GET /api/v1.0/items-histories

Query Parameters:

filter[item] - Item ID
sort - Sort order (default: -created)

Response:

{
  "data": [
    {
      "id": "5001",
      "item": "345",
      "action": "status_change",
      "old_value": "available",
      "new_value": "sold",
      "user": {
        "id": "10",
        "name": "Clerk Name"
      },
      "created": "2025-10-15T14:30:00Z",
      "details": "Item sold to bidder 12345 for $250.00"
    }
  ]
}

Delete Winning Bid

Remove the winning bid from an item.

Endpoint: DELETE /api/v1.0/delete-winning-bid/{item_id}

Request Body: None required

Response:

{
  "data": {
    "success": true,
    "item_id": "345",
    "previous_winner": "12345",
    "previous_hammer_price": "250.00"
  }
}

Save Single Lot Number

Update a single item's lot number.

Endpoint: GET /api/v1.0/invoke-function/save_single_lot_number

Query Parameters:

params[0] - Sale ID
params[1] - Item position
params[2] - Lot number
params[3] - Force override (0 or 1)

Example:

GET /api/v1.0/invoke-function/save_single_lot_number?params[0]=456&params[1]=10&params[2]=1234&params[3]=0

Sales

List Sales (DataTable)

Retrieve a paginated list of sales/auctions.

Endpoint: GET /api/v1.0/datatable-sales

Query Parameters:

range - Items per page
page - Page number
sort - Sort field and direction
filter[status] - Sale status (draft, published, closed)
filter[sale_date][value][from] - Min sale date
filter[sale_date][value][to] - Max sale date
filter[catalog] - Catalog ID
fields - Specific fields

Example Request:

GET /api/v1.0/datatable-sales?filter[status]=published&sort=-sale_date&range=25

Response:

{
  "data": [
    {
      "id": "456",
      "label": "Summer Auction 2025",
      "sale_date": "2025-06-15T19:00:00Z",
      "status": "published",
      "catalog": {
        "id": "78",
        "label": "Summer 2025 Catalog"
      },
      "item_count": 250,
      "consignment_count": 15,
      "total_estimates": "250000.00",
      "total_hammer_price": "280000.00",
      "lots_locked": false,
      "venue": "Main Auction House",
      "created": "2025-03-01T10:00:00Z"
    }
  ],
  "count": 12
}

Get Single Sale

Endpoint: GET /api/v1.0/datatable-sales/{id}

Update Sale

Endpoint: PATCH /api/v1.0/datatable-sales/{id}

Request - Lock Lots:

{
  "lots_locked": true
}

Sales Public

Get publicly available sales for frontend/website.

Endpoint: GET /api/v1.0/sales-public

Query Parameters:

filter[status] - published
range - Items per page
sort - Sort order

Example:

GET /api/v1.0/sales-public?filter[status]=published&sort=-sale_date

Sale Statistics

Get detailed statistics for a sale.

Endpoint: GET /api/v1.0/sale-stats/{sale_id}

Query Parameters:

refresh - Force refresh (0 or 1)

Response:

{
  "data": [{
    "sale_id": "456",
    "total_items": 250,
    "sold_items": 200,
    "unsold_items": 50,
    "sell_through_rate": 80.0,
    "total_hammer_price": "280000.00",
    "total_estimates_low": "200000.00",
    "total_estimates_high": "300000.00",
    "performance_vs_estimate": 112.0,
    "total_buyers": 85,
    "total_bidders": 120,
    "online_bidders": 45,
    "phone_bidders": 15,
    "floor_bidders": 60,
    "average_lot_price": "1400.00",
    "top_lot": {
      "id": "345",
      "lot": "1234",
      "hammer_price": "15000.00"
    }
  }]
}

Sale Sessions

Get sale session information.

Endpoint: GET /api/v1.0/sale-sessions

Query Parameters:

filter[sale] - Sale ID

Example:

GET /api/v1.0/sale-sessions?filter[sale]=456

Response:

{
  "data": [
    {
      "id": "501",
      "sale": "456",
      "session_date": "2025-06-15T19:00:00Z",
      "session_number": 1,
      "item_range_start": "1",
      "item_range_end": "125",
      "auctioneer": {
        "id": "25",
        "name": "Jane Auctioneer"
      }
    }
  ]
}

Create/Update Sale Session

Endpoint: POST /api/v1.0/sale-sessions

Request:

{
  "sale": "456",
  "session_date": "2025-06-15T19:00:00Z",
  "session_number": 1,
  "auctioneer": "25"
}

Endpoint: PATCH /api/v1.0/sale-sessions/{session_id}

Sale Session Phone Bidders Card

Get phone bidder cards for printing.

Endpoint: GET /api/v1.0/sale-session-phone-bidders-card

Query Parameters:

filter[session] - Session ID

Transactions

List Transactions

Get payment transactions for an order.

Endpoint: GET /api/v1.0/transactions

Query Parameters:

filter[order] - Order ID
filter[client] - Client ID
sort - Sort order (default: -created)

Response:

{
  "data": [
    {
      "id": "901",
      "order": "789",
      "transaction_type": "Payment",
      "amount": "500.00",
      "transferred_currency": "USD",
      "transferred_amount": "500.00",
      "bank": {
        "id": "5",
        "name": "Main Bank"
      },
      "bank_account_number": "****1234",
      "credit_card_type": "Visa",
      "credit_card_last_4_digits": "4567",
      "transaction_date": "2025-10-15",
      "cheque_number": null,
      "cheque_date": null,
      "info": "Online payment",
      "cheque_url": null,
      "illustrated_cheque_url": null,
      "created": "2025-10-15T10:30:00Z"
    }
  ]
}

Create Transaction

Endpoint: POST /api/v1.0/transactions

Request - Credit Card Payment:

{
  "order": "789",
  "transaction_type": "Payment",
  "amount": "500.00",
  "credit_card_type": "Visa",
  "credit_card_last_4_digits": "4567",
  "transaction_date": "2025-10-15",
  "info": "Credit card payment"
}

Request - Cheque Payment:

{
  "order": "789",
  "transaction_type": "Cheque",
  "amount": "1250.00",
  "bank": "5",
  "bank_account_number": "123456789",
  "cheque_number": "001234",
  "cheque_date": "2025-10-15",
  "transaction_date": "2025-10-15",
  "info": "Cheque payment"
}

Request - Wire Transfer:

{
  "order": "789",
  "transaction_type": "Wire Transfer",
  "amount": "1250.00",
  "bank": "5",
  "bank_account_number": "987654321",
  "bank_branch": "Main Branch",
  "transaction_date": "2025-10-15",
  "info": "Wire transfer received"
}

Update Transaction

Endpoint: PATCH /api/v1.0/transactions/{id}

Request:

{
  "amount": "550.00",
  "info": "Updated payment amount"
}

Delete Transaction

Endpoint: DELETE /api/v1.0/transactions/{id}

Generate Cheque

Generate a printable cheque for a transaction.

Endpoint: POST /api/v1.0/generate-cheque

Request:

{
  "id": "901"
}

Response:

{
  "data": {
    "transaction_id": "901",
    "cheque_url": "https://backoffice.ddev.site/sites/default/files/cheques/cheque-901.pdf",
    "illustrated_cheque_url": "https://backoffice.ddev.site/sites/default/files/cheques/cheque-901-illustrated.png"
  }
}

Error Response:

{
  "title": "Transaction must be of type 'Cheque'",
  "status": 400
}

Activities & History

List Activities

Get activity logs for content.

Endpoint: GET /api/v1.0/activities

Query Parameters:

filter[content] - Content ID (item, order, client, etc.)
filter[type] - Activity type ID
filter[user] - User ID
sort - Sort order (default: -updated)
range - Items per page

Example:

GET /api/v1.0/activities?filter[content]=345&sort=-updated&range=50

Response:

{
  "data": [
    {
      "id": "7001",
      "type": {
        "id": "status_change",
        "label": "Status Change"
      },
      "content": {
        "id": "345",
        "type": "item",
        "label": "Item #1234"
      },
      "user": {
        "id": "10",
        "name": "Clerk Name"
      },
      "message": "Status changed from 'available' to 'sold'",
      "details": {
        "old_value": "available",
        "new_value": "sold",
        "hammer_price": "250.00",
        "winner_bidder": "12345"
      },
      "created": "2025-10-15T14:30:00Z",
      "updated": "2025-10-15T14:30:00Z"
    }
  ],
  "count": 25
}

Activities List (Simplified)

Get a simplified activity list.

Endpoint: GET /api/v1.0/activities-list

Query Parameters:

filter[user] - User ID
filter[date][value][from] - Start date
filter[date][value][to] - End date
range - Items per page

Create Activity

Endpoint: POST /api/v1.0/activities

Request:

{
  "type": "note_added",
  "content": "345",
  "message": "Added note to item",
  "details": {
    "note_text": "Item requires special packing"
  }
}

Notes

List Notes

Get notes for content (items, orders, clients, etc.).

Endpoint: GET /api/v1.0/notes

Query Parameters:

filter[reference] - Content ID
sort - Sort order (default: -created)

Example:

GET /api/v1.0/notes?filter[reference]=345&sort=-created

Response:

{
  "data": [
    {
      "id": "6001",
      "reference": "345",
      "note": "Item requires special handling during packing",
      "user": {
        "id": "10",
        "name": "Staff Member"
      },
      "created": "2025-10-10T09:00:00Z"
    }
  ]
}

Create Note

Endpoint: POST /api/v1.0/notes

Request:

{
  "reference": "345",
  "note": "Customer requested additional photos"
}

Tasks

List Tasks

Get tasks for content.

Endpoint: GET /api/v1.0/tasks

Query Parameters:

filter[reference] - Content ID
filter[status] - Task status (open, in_progress, completed)
filter[assigned_to] - User ID
sort - Sort order (default: created)

Example:

GET /api/v1.0/tasks?filter[reference]=345&filter[status]=open

Response:

{
  "data": [
    {
      "id": "8001",
      "reference": "345",
      "task_type": {
        "id": "photography",
        "label": "Photography"
      },
      "title": "Take additional photos",
      "description": "Customer requested more detailed images",
      "status": "open",
      "priority": "high",
      "assigned_to": {
        "id": "15",
        "name": "Photographer"
      },
      "due_date": "2025-10-20",
      "created": "2025-10-15T10:00:00Z"
    }
  ]
}

Create Task

Endpoint: POST /api/v1.0/tasks

Request:

{
  "reference": "345",
  "task_type": "photography",
  "title": "Take additional photos",
  "description": "Customer requested close-ups",
  "assigned_to": "15",
  "due_date": "2025-10-20",
  "priority": "high"
}

Update Task

Endpoint: PATCH /api/v1.0/tasks/{id}

Request:

{
  "status": "completed",
  "completion_notes": "Photos uploaded to item"
}

Calls

List Calls

Get call logs for a client.

Endpoint: GET /api/v1.0/calls

Query Parameters:

filter[client] - Client ID
sort - Sort order (default: -date)

Example:

GET /api/v1.0/calls?filter[client]=123&sort=-date

Response:

{
  "data": [
    {
      "id": "9001",
      "client": "123",
      "date": "2025-10-15T11:30:00Z",
      "notes": "Customer inquired about upcoming sales",
      "user": {
        "id": "10",
        "name": "Staff Member"
      },
      "created": "2025-10-15T11:35:00Z"
    }
  ]
}

Create Call Log

Endpoint: POST /api/v1.0/calls

Request:

{
  "client": "123",
  "date": "2025-10-15T11:30:00Z",
  "notes": "Discussed consignment opportunities"
}

Shipping

List Shipments

Get shipments for orders.

Endpoint: GET /api/v1.0/shipments

Query Parameters:

filter[order] - Order ID
filter[status] - Shipment status

Create Shipment

Endpoint: POST /api/v1.0/shipments

Request:

{
  "order": "789",
  "items": ["345", "346", "347"],
  "shipping_method": "FedEx Ground",
  "tracking_number": "123456789012",
  "shipping_cost": "25.00",
  "weight": "2.5",
  "dimensions": {
    "length": "30",
    "width": "20",
    "height": "15",
    "unit": "cm"
  }
}

Shipping Areas

Get available shipping areas/zones.

Endpoint: GET /api/v1.0/shipping-areas

Response:

{
  "data": [
    {
      "id": "10",
      "label": "Local",
      "description": "Within 50 miles",
      "base_rate": "10.00"
    },
    {
      "id": "11",
      "label": "National",
      "description": "Within country",
      "base_rate": "25.00"
    },
    {
      "id": "12",
      "label": "International",
      "description": "Outside country",
      "base_rate": "50.00"
    }
  ]
}

Create Shipping Box

Create or update shipping box information.

Endpoint: POST /api/v1.0/shipping-box

Request:

{
  "order": "789",
  "items": ["345", "346"],
  "box_number": "1",
  "weight": "2.5",
  "dimensions": "30x20x15cm"
}

Taxonomy Terms

Update Category

Endpoint: PATCH /api/v1.0/categories/{id}

Request:

{
  "label": "Ceramics & Pottery",
  "weight": 5
}

Additional Charges Terms

Endpoint: GET /api/v1.0/additional_charges

Response:

{
  "data": [
    {
      "id": "5",
      "label": "Shipping Fee",
      "default_amount": "25.00",
      "default_vat": "21.00"
    }
  ]
}

Bank Accounts

Endpoint: GET /api/v1.0/bank_accounts

Payment Types

Endpoint: GET /api/v1.0/payment_types

Bid Steps

Endpoint: GET /api/v1.0/bid_steps

Catalogues

Endpoint: GET /api/v1.0/catalogs

Catalogue Parts

Endpoint: GET /api/v1.0/catalogue-parts

Query Parameters:

filter[catalog] - Catalog ID
sort - Sort order

Example:

GET /api/v1.0/catalogue-parts?filter[catalog]=78&sort=weight

Create Catalogue Part

Endpoint: POST /api/v1.0/catalogue-parts

Request:

{
  "catalog": "78",
  "label": "Section A: Modern Art",
  "description": "Contemporary paintings and sculptures",
  "weight": 1
}

Update Catalogue Part

Endpoint: PATCH /api/v1.0/catalogue-parts/{id}

Delete Catalogue Part

Endpoint: DELETE /api/v1.0/catalogue-parts/{id}

Catalogue Parts Public

Get publicly available catalogue parts.

Endpoint: GET /api/v1.0/catalogue-parts-public

Users & Staff

List Staff

Get staff/user list.

Endpoint: GET /api/v1.0/staff

Query Parameters:

filter[role] - User role
filter[status] - User status (active, blocked)
fields - Specific fields

Example:

GET /api/v1.0/staff?filter[role]=clerk&fields=id,name,email

Response:

{
  "data": [
    {
      "id": "10",
      "name": "Staff Member",
      "email": "[email protected]",
      "roles": ["clerk"],
      "status": "active"
    }
  ]
}

Get Current User (Me)

Endpoint: GET /api/v1.0/me

Response:

{
  "data": [{
    "id": "1",
    "name": "John Admin",
    "email": "[email protected]",
    "roles": ["administrator"],
    "permissions": [...]
  }]
}

Update User

Endpoint: PATCH /api/v1.0/staff/{id}

Clerk Statistics

Endpoint: GET /api/v1.0/clerk-stats

Query Parameters:

filter[user] - User ID
filter[date][value][from] - Start date
filter[date][value][to] - End date

Files & Images

Upload File

Upload a file or image.

Endpoint: POST /api/v1.0/files

Content-Type: multipart/form-data

Form Data:

file - The file to upload
field_name - Field name (e.g., 'field_images')
entity_type - Entity type (e.g., 'node')
bundle - Bundle name (e.g., 'item')

Example using curl:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/image.jpg" \
  -F "field_name=field_images" \
  -F "entity_type=node" \
  -F "bundle=item" \
  https://backoffice.ddev.site/api/v1.0/files

Response:

{
  "data": [{
    "id": "1001",
    "fid": "1001",
    "url": "https://backoffice.ddev.site/sites/default/files/item-images/image.jpg",
    "filename": "image.jpg",
    "filesize": "125000",
    "filemime": "image/jpeg"
  }]
}

Get File

Endpoint: GET /api/v1.0/get-file/{fid}

Response:

{
  "data": [{
    "id": "1001",
    "url": "https://backoffice.ddev.site/sites/default/files/item-images/image.jpg",
    "filename": "image.jpg",
    "filesize": "125000"
  }]
}

Advanced Queue

Get Queue Item

Get information about a queued background job.

Endpoint: GET /api/v1.0/advancedqueue_item

Query Parameters:

filter[item_id] - Queue item ID

Bulk Operations

Bulk Dispatcher

Dispatch bulk operations.

Endpoint: POST /api/v1.0/bulk-dispatcher

Request:

{
  "operation": "print_labels",
  "entity_type": "item",
  "ids": ["345", "346", "347"]
}

Common Query Parameters

Pagination

?range=25              # Items per page (default: 25)
?page=2                # Page number (0-indexed)

Sorting

?sort=field_name       # Ascending
?sort=-field_name      # Descending
?sort=-created,id      # Multiple fields

Filtering

Simple Filter:

?filter[field_name]=value

IN Operator (multiple values):

?filter[field_name][value][0]=value1
?filter[field_name][value][1]=value2
?filter[field_name][operator]=IN

Range Filter:

?filter[field_name][value][from]=100
?filter[field_name][value][to]=1000

Date Range:

?filter[created][value][from]=2025-01-01
?filter[created][value][to]=2025-12-31

Regex Search:

?filter[field_name][value]=search.*term
?filter[field_name][operator]=REGEXP

Field Selection

?fields=id,label,status,created

Global Search

?global_search=search+term

Error Responses

Standard Error Format

{
  "title": "Validation error",
  "status": 400,
  "detail": "The field 'email' is required",
  "errors": {
    "email": ["This field is required"]
  }
}

Common HTTP Status Codes

200 OK - Request successful
201 Created - Resource created successfully
204 No Content - Success with no response body (e.g., DELETE)
400 Bad Request - Invalid request data
401 Unauthorized - Authentication required or failed
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
422 Unprocessable Entity - Validation error
500 Internal Server Error - Server error

Error Examples

Missing Required Field:

{
  "title": "The field 'email' is required",
  "status": 400
}

Invalid Data Format:

{
  "title": "Invalid email format",
  "status": 422,
  "errors": {
    "email": ["Please enter a valid email address"]
  }
}

Permission Denied:

{
  "title": "Access denied",
  "status": 403,
  "detail": "You do not have permission to perform this action"
}

Resource Not Found:

{
  "title": "Resource not found",
  "status": 404,
  "detail": "Order with ID 999 does not exist"
}

Rate Limiting

API requests may be rate-limited based on IP address or access token.

Response Headers:

X-RateLimit-Limit - Maximum requests per window
X-RateLimit-Remaining - Remaining requests in current window
X-RateLimit-Reset - Unix timestamp when limit resets

Rate Limit Exceeded:

{
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Too many requests. Please try again later.",
  "retry_after": 60
}

Data Types & Formats

Dates

All dates are in ISO 8601 format (UTC):

2025-10-15T14:30:00Z

For date-only fields:

2025-10-15

Currency

Currency amounts are strings to preserve precision:

{
  "amount": "1250.50"
}

Formatted amounts include currency symbol:

{
  "amount": "1250.50",
  "formatted": "$1,250.50"
}

Booleans

Boolean values can be:

true / false
1 / 0
"1" / "0"

NULL Values

Missing optional fields may be omitted
Explicitly null fields: null
Empty strings: ""

Versioning

The API uses URL-based versioning. Current version: v1.0

All endpoints include the version in the path:

/api/v1.0/resource

Best Practices

Efficient Filtering

Combine filters to reduce payload:

GET /api/v1.0/orders?filter[type]=bidder&filter[status]=new&filter[sale]=456&range=25

Field Selection

Request only needed fields:

GET /api/v1.0/datatable-clients?fields=id,first_name,last_name,email

Batch Operations

Use bulk endpoints for multiple updates:

POST /api/v1.0/items-bulk

Pagination

Use reasonable page sizes:

GET /api/v1.0/orders?range=50    # Good
GET /api/v1.0/orders?range=1000  # Avoid

Error Handling

Always check HTTP status codes and handle errors appropriately.

Caching

Use ETags when available
Cache reference data (categories, payment types, etc.)

Support

For API support, questions, or bug reports, contact the development team.

Last Updated: October 30, 2025 API Version: 1.0

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.claude		.claude
.grok		.grok
.idea		.idea
addresses		addresses
bulk		bulk
clients		clients
files		files
items		items
orders		orders
queue		queue
sales		sales
transactions		transactions
CNAME		CNAME
README.md		README.md
common.html		common.html
data-types.html		data-types.html
errors.html		errors.html
index.html		index.html

Gizra/circuit-api-documentation

Folders and files

Latest commit

History

Repository files navigation

Circuit Auction Backoffice API Documentation

Base URL

Authentication

Back Office Authentication

Clients

List Clients (DataTable)

Get Single Client

Create Client

Update Client

Update Client Status

Client Connect

Client Merge

Client Address

Client Statistics

Connected Entities

Client Addresses

List Client Addresses

Get Single Address

Create Client Address

Update Client Address

Delete Client Address

Orders

List Orders

Get Single Order

Create Order

Update Order

Update Order Status

Split Order

Create Credit Note

Cancel and Reissue Order

Print Order

Orders Attached Text

Reset Additional Charges

Consignments

List Consignments (DataTable)

Consignment Statements (DataTable)

Consignments Underbids Inquiries

Control List Consigner

Items

List Items (DataTable)

Get Single Item

Items List (Simple)

Items JSON

Items Public

Items Lots

Items Bulk Operations

Items Bulk Edit (Lot Numbers)

Clone or Move Items

Item Dimensions

Items Histories

Delete Winning Bid

Save Single Lot Number

Sales

List Sales (DataTable)

Get Single Sale

Update Sale

Sales Public

Sale Statistics

Sale Sessions

Create/Update Sale Session

Sale Session Phone Bidders Card

Transactions

List Transactions

Create Transaction

Update Transaction

Delete Transaction

Generate Cheque

Activities & History

List Activities

Activities List (Simplified)

Create Activity

Notes

List Notes

Create Note

Tasks