Skip to content
  • There are no suggestions because the search field is empty.

ClickBid API Documentation

Learn how to use our publicly available API.

Audience: Developers with API experience
Support Level: Self-service (limited support available)
API Docs Link: https://cbo.io/docs/api

Overview

ClickBid provides a RESTful API that allows you to integrate with your event data, including bidders, items, bids, tickets, and more. This guide walks you through generating API tokens, understanding the documentation, and making your first API calls.

Note: We assume you have programming knowledge and experience working with APIs. Our account management team is not trained in software development or API integration, so external developer support is limited.

 

Getting Started

Accessing API Settings

  1. Log into your ClickBid admin
  2. Navigate to API Settings
  3. Your user account must have API access permissions

The API Settings page has two sections:

Section Purpose
API Tokens Lists all generated tokens
Logs Shows packets sent/received and any errors for troubleshooting

Creating an API Token

Token Types

Type Use Case
Event Token Access data for a specific event (most common)
Organization Token Access org-level endpoints like keyword lookup or creating new events

Steps to Create a Token

  1. Click Create Token
  2. Select the Event you want to connect
  3. Give the token a descriptive Name (e.g., "4939 Testing")
  4. Click Update
  5. Copy the token immediately — this is the only time you'll see it

⚠️ Important: Store your token in a password manager. Never hard-code tokens in your application or store them in plain text files. If you lose your token, you'll need to generate a new one and delete the old one.

Deleting Tokens

To revoke API access, select any token and click Delete.

Finding Your Event ID and Org ID

Your API token must match the event you're calling. Here's how to find your IDs:

Event ID

  • Log into ClickBid
  • Click the person icon in the top right
  • The dropdown displays your event name and Event ID

Organization ID

  • Navigate to the Account tab
  • Scroll down to find Org ID
  • If you can't locate it, contact support via chat

API Documentation

Click API Docs in the API Settings page to open the interactive documentation in a new tab.

Documentation Structure

Left sidebar: Navigation menu organized by endpoint category
Main content: Detailed documentation with test capabilities

General Information

Topic Details
Authentication Bearer token (the token you generated)
Query Parameters Pagination with page and per_page
Rate Limiting Exceeding limits returns a 429 response code
Response Format JSON with data array and metadata (collection count, path, timestamp)

Making API Calls

Testing Endpoints

Each endpoint has a Test Request button that opens an interactive testing modal.

Required fields for most requests:

  • Auth Type: HTTP Bearer Token
  • Token: Your API token
  • Event ID: Must match the token's event

Example: List Bidders

  1. Navigate to Bidder → List Bidders
  2. Click Test Request
  3. Select HTTP auth type
  4. Paste your Bearer Token
  5. Enter your Event ID
  6. Click Send

Sample Response:

{
  "data": [
    {
      "id": 10135635,
      "first_name": "Matthew",
      "last_name": "Testing"
      // ... additional fields
    }
  ],
  "path": "/api/bidders",
  "per_page": 15,
  "count": 1,
  "timestamp": "2026-01-29T12:00:00Z"
}

Tip: Use the timestamp field to track when you last called the API and fetch only updated records on subsequent calls.

Expanding Data with "With" Parameters

By default, API responses return core fields only. Use the with parameter to include related data.

Available Options

Check the info icon next to the with parameter for available options, such as:

  • emails
  • phones
  • bids
  • bids.item
  • checkouts

Example: Include Emails and Phones

with=emails,phones

Example: Include Bids with Item Details

with=bids.item

This returns nested data—each bid includes its associated item information.

Note: Use plural forms (emails, phones) for parameters. Relationships are one-to-many, so you may receive multiple emails or phones per bidder.

Sorting Results

Use the sort parameter with a comma-separated list of fields.

Ascending order:

sort=first_name

Descending order (prefix with dash):

sort=-created_at

Filtering Results

Use the filter parameter to narrow your results.

Filter Syntax

filter[field_name][operator]=value

Available Operators

Operator Meaning
eq Equal to
neq Not equal to
lt Less than
lte Less than or equal
gt Greater than
gte Greater than or equal
like Pattern match (SQL LIKE)

Example: Filter by First Name

filter[first_name][eq]=Matthew

Example: Filter by Nested Data (Email)

filter[emails.email][eq]=john@example.com

Tip: If you've used SQL before, these operators work similarly to WHERE clauses.

Placing a Bid via API

The API allows you to programmatically place bids, but with guardrails.

Requirements

  • Item must be Active (not Invisible or Closed)
  • Item must be open for bidding (within start/end times)
  • Token must have access to the event

Steps

  1. Get the Bidder ID: Call List Bidders and copy the bidder's id
  2. Get the Item ID: Call List Items and copy the item's id
  3. Place the Bid: Call Place Bid with the required data

Request Body Example

{
  "bidder_id": 10135635,
  "bid_amount": 100
}

Optional fields: max_amount, notes, notify

Common Errors

Error Cause Solution
401 Unauthorized Token doesn't match event ID Verify event ID matches your token
404 Resource Not Found Invalid event, item, or bidder ID Double-check all IDs
422 Item is not open for bidding Item status is not Active Change item status to Active in admin

Tip: Keep a text editor open while testing to store IDs. The documentation caches your inputs, but your clipboard may not.

Understanding Duplicate Endpoints

You may notice some endpoints appear twice (e.g., List Guests appears with different required parameters):

Version Required Parameters
Legacy event_id, ticket_form_id, registration_id
Current event_id, ticket_form_id

This maintains backwards compatibility. Use the simpler version when possible.

Chaining API Calls

Many workflows require multiple API calls in sequence:

Example: Get Ticket Guests

  1. Call List Ticket Forms → get form_id
  2. Call List Guests with form_id → get guest data
  3. Optionally filter by registration_id for specific ticket sales

Troubleshooting

Issue Solution
401 Unauthorized Token doesn't have access to the specified event
404 Resource Not Found Check event ID, item ID, or bidder ID
422 Unprocessable Entity Item not open, invalid data format, or business rule violation
429 Too Many Requests Rate limit exceeded; slow down your requests
Syntax errors in test modal Look for red underlines indicating typos (e.g., trailing commas)

Best Practices

  1. Store tokens securely in a password manager or secrets vault
  2. Never hard-code tokens in your application source code
  3. Use timestamps to fetch only updated records on subsequent calls
  4. Test thoroughly using the interactive documentation before building integrations
  5. Handle errors gracefully — check response codes and messages
  6. Respect rate limits to avoid 429 errors

Need Help?

While our support team has limited capacity for API development questions, you can:

  • Open a chat for help finding IDs or basic questions
  • Submit feature requests if you need additional endpoints
  • Review the API logs in your admin to troubleshoot issues

The API documentation is built alongside the codebase, ensuring it stays current with available endpoints and features.