← Back to API Reference

Brilliant Directories API Reference

Version 2.1 — Last updated April 2026

Introduction

https://www.yourdomain.com/api/v2/

Authentication

Verify API Key

Check whether an API key is valid and retrieve the associated website URL and key name.

Example Request

curl -X GET "https://www.yourdomain.com/api/v2/token/verify" \
  -H "X-Api-Key: your-api-key-here"

Example Response

{
  "status": "success",
  "message": {
    "website": "https://www.yourdomain.com",
    "key": "My API Key Name"
  }
}

Rate Limiting

The API enforces rate limiting to prevent abuse. The default limit is 100 requests per 60 seconds. This limit can be adjusted in your website's Admin Panel settings (maximum 1,000 requests per minute).

When you exceed the rate limit, the API returns a 429 Too Many Requests response. Wait for the time window to reset before retrying.

Rate Limit Response

{
  "status": "error",
  "message": "Too many API requests per minute"
}

Errors

All error responses follow the same structure: a status field set to "error" and a message field describing the problem.

Error Response Format

{
  "status": "error",
  "message": "Description of the error"
}

HTTP Status Codes

Pagination

All list endpoints return paginated results. By default, 25 records are returned per page. The maximum is 100 per page.

Pagination Parameters

Pagination Response Fields

Example Paginated Response

{
  "status": "success",
  "total": 156,
  "current_page": 2,
  "total_pages": 7,
  "next_page": "MypfKjI1",
  "prev_page": "MSpfKjI1",
  "message": [ ... ]
}

Pagination Flow

First request — omit the page parameter to start at page 1:

curl -X GET "https://www.yourdomain.com/api/v2/user/get?limit=25" \
  -H "X-Api-Key: your-api-key-here"

Subsequent requests — pass the next_page token from the previous response:

curl -X GET "https://www.yourdomain.com/api/v2/user/get?page=MipfKjI1" \
  -H "X-Api-Key: your-api-key-here"

Filtering and Sorting

All list endpoints support filtering by any field and sorting by any column using query string parameters.

Filter Parameters

Sort Parameters

Filter Example — Exact Match

# Get all active users (active = 2)
curl -X GET "https://www.yourdomain.com/api/v2/user/get?property=active&property_value=2" \
  -H "X-Api-Key: your-api-key-here"

Filter Example — LIKE Search

# Find users whose company name contains "Tech"
curl -X GET "https://www.yourdomain.com/api/v2/user/get?property=company&property_value=%25Tech%25&property_operator=LIKE" \
  -H "X-Api-Key: your-api-key-here"

Filter Example — Multiple Filters

# Get active users in California
curl -X GET "https://www.yourdomain.com/api/v2/user/get?property[]=active&property_value[]=2&property[]=state_code&property_value[]=CA" \
  -H "X-Api-Key: your-api-key-here"

The Fields Endpoint

Each resource exposes a /fields endpoint that returns the list of writable fields for that resource. This is useful for discovering available fields dynamically without consulting the documentation.

Example Request

curl -X GET "https://www.yourdomain.com/api/v2/user/fields" \
  -H "X-Api-Key: your-api-key-here"

Example Response

[
  { "key": "first_name", "label": "first_name", "required": 0 },
  { "key": "last_name",  "label": "last_name",  "required": 0 },
  { "key": "email",      "label": "email",      "required": 0 },
  ...
]

For post types (data_posts and users_portfolio_groups), pass a form_name parameter to retrieve the custom fields specific to that post type:

curl -X GET "https://www.yourdomain.com/api/v2/data_posts/fields?form_name=my-listings-form" \
  -H "X-Api-Key: your-api-key-here"