API Overview

Welcome to the Data Builder Public API. This API allows you to access and query your Perfex CRM data using RESTful endpoints. It's designed to be fast, secure, and developer-friendly.

Base URL https://databuilder.polyxgo.com/api/v1/

Getting Started

To use this API, you need a valid Bearer Token. Integration samples are provided for several languages in the sidebar for each endpoint.

Sandbox — Safe & Private
• All response data (names, emails, phones, amounts, …) is randomized — no real system data is returned.
• Passwords, payment details, tokens, and secrets are masked or excluded entirely.
• All write operations (POST, PUT, DELETE) are simulated — nothing is persisted to the database.
• To enable sandbox requests, create a token at Admin → Data Builder → API Tokens and set it in Settings → Public Demo Token.

PUBLIC DEMO TOKEN

dba_51d5••••••••••••••••••••••••••••••••••••••••d186

Authentication

All API requests must include your API token in the `Authorization` HTTP header as a Bearer token.

HTTP Header

Authorization: Bearer YOUR_TOKEN_HERE

HMAC Verification

If your token has HMAC signing enabled, every request must include `X-Timestamp` and `X-Signature` headers to ensure data integrity.

PHP Node.js Python cURL

<?php
$method    = "POST";
$path      = "/api/v1/graphql"; // Always starts with /
$query     = ""; // Data after ? in URL
$body      = json_encode(["query" => "{ ... }"]);
$timestamp = time();
$secret    = "YOUR_HMAC_SECRET";

$bodyHash  = hash('sha256', $body);
$canonical = implode("\n", [$method, $path, $query, $bodyHash, $timestamp]);
$signature = hash_hmac('sha256', $canonical, $secret);

// Headers
$headers = [
    "Authorization: Bearer YOUR_TOKEN",
    "X-Timestamp: " . $timestamp,
    "X-Signature: " . $signature,
    "Content-Type: application/json"
];

const crypto = require('crypto');

const timestamp = Math.floor(Date.now() / 1000).toString();
const method    = "POST";
const path      = "/api/v1/graphql";
const query     = "";
const body      = JSON.stringify({ query: "{ ... }" });
const secret    = "YOUR_HMAC_SECRET";

const bodyHash  = crypto.createHash('sha256').update(body).digest('hex');
const canonical = [method, path, query, bodyHash, timestamp].join("\n");
const signature = crypto.createHmac('sha256', secret).update(canonical).digest('hex');

const headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "X-Timestamp": timestamp,
    "X-Signature": signature,
    "Content-Type": "application/json"
};

import hmac, hashlib, time, json

timestamp = str(int(time.time()))
method    = "POST"
path      = "/api/v1/graphql"
query     = ""
body      = json.dumps({"query": "{ ... }"})
secret    = b"YOUR_HMAC_SECRET" # Must be bytes

body_hash = hashlib.sha256(body.encode()).hexdigest()
canonical = "\n".join([method, path, query, body_hash, timestamp])
signature = hmac.new(secret, canonical.encode(), hashlib.sha256).hexdigest()

headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "X-Timestamp": timestamp,
    "X-Signature": signature,
    "Content-Type": "application/json"
}

# Example: Manual test with pre-calculated values
# Replace timestamps/signatures with values from your local calculator
curl -X POST 'https://your-domain.com/api/v1/graphql' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Timestamp: 1711900000' \
  -H 'X-Signature: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855' \
  -H 'Content-Type: application/json' \
  -d '{"query": "{ ... }"}'

Canonical String Construction Guide

The signature is computed over a strictly ordered string to ensure both client and server validate the exact same data context:

{METHOD}\n{PATH}\n{QUERY}\n{SHA256_BODY}\n{TIMESTAMP}

\n: Represents a literal newline character (LF).
{PATH}: Must begin with a leading slash (e.g. /api/v1/graphql).
{SHA256_BODY}: A lowercase hex-encoded SHA256 hash of the raw request body.

Testing with Postman

Complete guide to export, import, and configure the API collection in Postman for testing all REST and GraphQL endpoints.

Step 1 — Create an API Token

Before you can make any API request, you need a valid API token.

Go to Admin → Data Builder → API Tokens
Click "Create Token"
Fill in the token name (e.g., Postman Testing)
Select Scopes: choose tables, views, and write as needed
Select Allowed Tables and Allowed Views the token can access
Click Save
Copy the token immediately — it is only shown once

Important — The token is stored as a SHA-256 hash. If you lose the plain text token, you must revoke and create a new one. Tokens follow the format dba_{48_hex_characters}.

Step 2 — Export the Postman Collection

Download the pre-built collection with all endpoints, headers, and query parameters.

Postman Collection v2.1

DataBuilder_API.postman_collection.json

Step 3 — Import into Postman

Import the downloaded JSON file into your Postman workspace.

Open Postman (desktop app or web)
Click Import (top-left, or Ctrl+O / ⌘+O)
Drag and drop the .json file or click "Upload Files"
Click "Import" to confirm
The collection "Data Builder API" appears in your sidebar with all folders: Resources, Reports, GraphQL

Step 4 — Configure Collection Variables

The exported collection uses two variables that you must set before testing.

Variable	Value	Description
`{{baseUrl}}`	`https://databuilder.polyxgo.com/api/v1`	API base URL — auto-filled from export, update if your domain changes
`{{api_token}}`	`dba_xxxxxxx...`	Paste the token you created in Step 1
`{{hmac_secret}}`	`Optional secret`	The HMAC Secret key (only if HMAC is enabled for the token)

How to set variables in Postman:

Click the collection name "Data Builder API" in the sidebar
Go to the "Variables" tab
baseUrl is pre-filled — update the CURRENT VALUE column if your server URL differs (e.g., https://yourdomain.com/api/v1)
Set api_token CURRENT VALUE to your token from Step 1
Click Save (Ctrl+S / ⌘+S)

Tip — The collection-level authentication is already configured to use Bearer {{api_token}}. All requests inherit this automatically — no need to set Authorization on each request individually.

Step 5 — Send Your First Request

You're all set! Try a quick test:

Expand Resources folder in the collection sidebar
Click any GET List request
The URL bar shows: {{baseUrl}}/resource_name
Click the Send button
View the JSON response in the Body tab below ✓

Step 6 — Production Security: HMAC Signatures

Security Policy Alert — For development and local testing, you can disable HMAC on your tokens for simplicity. However, for Production Environments, we strongly recommend enabling HMAC Signature Verification to prevent request tampering and replay attacks.

If your token has an HMAC Secret configured, Postman must generate a valid X-Signature for every request. You can automate this using a Pre-request Script:

Postman Pre-request Script:

const timestamp = Math.floor(Date.now() / 1000).toString();
const method = pm.request.method.toUpperCase();
const secret = pm.environment.get("hmac_secret");

if (secret) {
    const url = pm.request.url;
    // Build path: ensure it starts with /
    const path = "/" + url.getPathWithQuery().split('?')[0]; 
    const query = url.getQueryString() || "";
    // Body digest (SHA256)
    const bodyRaw = pm.request.body.raw || "";
    const bodyHash = CryptoJS.SHA256(bodyRaw).toString();

    // Canonical string: METHOD\nPATH\nQUERY\nBODY_HASH\nTIMESTAMP
    const canonical = [method, path, query, bodyHash, timestamp].join("\n");
    const signature = CryptoJS.HmacSHA256(canonical, secret).toString();

    pm.request.headers.add({ key: 'X-Timestamp', value: timestamp });
    pm.request.headers.add({ key: 'X-Signature', value: signature });
}

Paste this script into the "Pre-request Script" tab of the collection (or a specific request) and ensure the {{hmac_secret}} variable is set.

Available Query Parameters

List endpoints include pre-configured query parameters (disabled by default). Enable them in the Params tab:

Param	Example	Description
`page`	`1`	Page number
`per_page`	`25`	Records per page (max 1000)
`sort`	`-id`	Sort field — prefix `-` for DESC
`fields`	`id,name,email`	Sparse fieldset — only return listed columns
`filter`	`status:1`	Filter results by field value

Testing with OpenAPI

Use the exported OpenAPI 3.0 specification to test your REST & GraphQL endpoints in Swagger UI, Insomnia, or integrate with AI platforms like ChatGPT (OpenAI Actions).

Step 1 — Download the OpenAPI Spec

Export the auto-generated OpenAPI 3.0.3 YAML file that includes all your REST and GraphQL endpoints.

All Tables — YAML

DataBuilder_API_OpenAPI3.yaml

Custom Export (OpenAI)

Select specific tables to export

Includes — All REST CRUD operations, Report endpoints, GraphQL mutation/query endpoint, Bearer authentication, and RFC 9457 error schemas.

Step 2 — Import into Your Favorite Tool

The OpenAPI spec can be used with many tools:

Swagger UI

Open editor.swagger.io
Go to File → Import File
Upload the .yaml file
Click Authorize and enter your token
Click Try it out on any endpoint

Insomnia

Open Insomnia and create a new project
Click Import → select the .yaml file
Set Bearer Token in environment
All endpoints appear with parameters pre-filled
Click Send to test

Step 3 — Integrate with ChatGPT (OpenAI Actions)

Use the OpenAPI spec to create a Custom GPT Action that allows ChatGPT to query your CRM data in real-time.

Go to ChatGPT GPT Editor → Create a GPT
In the Configure tab, scroll down to Actions → click "Create new action"
Click "Import from URL" or paste the raw YAML content into the schema editor
Set Authentication: select API Key, Auth Type: Bearer, paste your API token
Click "Save" — ChatGPT can now query your API endpoints

Tip — Your server must be publicly accessible for ChatGPT to reach it. For local development, use a tunnel like ngrok or Cloudflare Tunnel.

Real-World Use Cases

With the right API branches configured, your Custom GPT becomes a powerful AI-powered CRM analyst. Here are some practical scenarios:

Data Analysis — Ask ChatGPT to analyze customer data, identify trends, and surface insights from your CRM

Project Status — "Which projects are overdue?" or "Show project progress for client X"

Client Insights — "Which clients have the most projects?" or "Rank customers by total revenue"

Unpaid Invoices — "List all overdue invoices" or "Total outstanding amount this quarter"

Revenue Reports — "Monthly revenue breakdown by payment method" or "Compare Q1 vs Q2 sales"

AI Reports — Combine multiple API calls to generate comprehensive summaries and actionable recommendations

Step 4 — Testing GraphQL with the OpenAPI Spec

The OpenAPI export includes the POST /graphql endpoint schema. Here's how to use it:

Swagger UI cURL ChatGPT Prompt

# In Swagger UI's "Try it out" for POST /graphql:
# Set the request body to:
{
  "query": "{ staffs(limit: 5) { id email firstname lastname } }",
  "variables": {},
  "operationName": null
}

# For mutations:
{
  "query": "mutation { createProject(input: { name: \"New Project\", clientid: 1 }) { id name } }",
  "variables": {}
}

# List query
curl -X POST 'https://databuilder.polyxgo.com/api/v1/graphql' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "{ staffs(limit: 5) { id email firstname lastname } }"
  }'

# Introspection query (discover all types)
curl -X POST 'https://databuilder.polyxgo.com/api/v1/graphql' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "{ __schema { types { name kind } } }"
  }'

# Mutation example
curl -X POST 'https://databuilder.polyxgo.com/api/v1/graphql' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation { createProject(input: { name: \\"API Test\\", clientid: 1 }) { id name } }"
  }'

# Example prompts you can use with your Custom GPT:

"List all staff members with their email addresses"
→ GPT will call: POST /graphql with query { staffs { id firstname lastname email } }

"Show me the 5 latest projects"
→ GPT will call: GET /projects?sort=-id&per_page=5

"Create a new task for project ID 3 with name 'Review API docs'"
→ GPT will call: POST /tasks with body { rel_type: "project", rel_id: 3, name: "Review API docs" }

"Get the schema of the invoices table"
→ GPT will call: GET /invoices/schema

"Run a monthly revenue report grouped by status"
→ GPT will call: GET /reports/invoices/aggregate?dimension=status&measure=total&aggregation=sum&period=monthly

What's Included in the Spec

Feature	Details
REST CRUD	GET list, GET by ID, POST create, PUT update, DELETE, GET schema — for every allowed table
Reports	Query and Aggregate endpoints for every published View/Report
GraphQL	`POST /graphql` with query, variables, and operationName schema
Authentication	Bearer Token (BearerAuth) security scheme
Query Params	`page`, `per_page`, `sort`, `fields`, `filter` — described with types and defaults
Error Schema	RFC 9457 Problem Details schema for 401, 403, 429 responses

Tips

The spec is dynamically generated based on your current allowed tables and views — export again after changes.
For ChatGPT Actions, keep your token scopes minimal (read-only) for safety.
Use the Postman Collection for more detailed request body samples and pre-configured queries.
If HMAC is enabled on your token, see the Authentication section for signing details.

Deployment Guide

Server-level configuration for production deployments. Some security features require web server configuration — PHP cannot intercept slow HTTP attacks because they occur before PHP receives the request.

Slow HTTP Protection

Protects against Slowloris and similar slow-read/slow-header attacks.

Apache

Add to your VirtualHost or .htaccess. Requires mod_reqtimeout (enabled by default on most Apache installs).

Apache — httpd.conf or .htaccess

# Protects against slow-read and slow-header attacks (Slowloris, etc.)
RequestReadTimeout header=20-40,MinRate=500 body=30,MinRate=500

header=20-40,MinRate=500 — 20s to start headers, 40s max; min 500 B/s transfer rate
body=30,MinRate=500 — 30s total body read time; min 500 B/s

Nginx

Add to your server {} or location /api/ {} block.

Nginx — nginx.conf

# Slow HTTP protection
client_header_timeout  10s;
client_body_timeout    10s;
client_max_body_size   256k;    # Matches application DDoS shield body limit
keepalive_timeout      30s;
send_timeout           10s;

Body Size Limit Alignment

The application DDoS shield middleware enforces a configurable body size limit (default 256KB). Align your web server limit to match — if the web server limit is higher, it wastes resources receiving oversized payloads before the application check rejects them.

Server	Directive
Apache	`LimitRequestBody 262144`
Nginx	`client_max_body_size 256k`

MySQL Permissions

The tbldata_builder_api_rate table contains rate counters that must only be writable by the application DB user. Restricting access prevents unauthorized counter manipulation.

SQL — Restrict table access

-- Revoke from any monitoring/reporting users
REVOKE SELECT, INSERT, UPDATE, DELETE
  ON your_db.tbldata_builder_api_rate FROM 'readonly_user'@'%';

-- Grant only to the application user
GRANT SELECT, INSERT, UPDATE, DELETE
  ON your_db.tbldata_builder_api_rate TO 'app_user'@'localhost';

tbldata_builder_api_logs contains sensitive audit data — also restrict to app user and admin only.

Reverse Proxy / WAF

The application-level DDoS shield handles body size limits (413), IP-level fixed-window throttling, and malformed payload detection. For volumetric DDoS (layer 3/4) or large-scale layer 7 attacks, use external solutions:

Cloudflare

WAF + rate limiting + bot protection. Recommended for most setups.

AWS WAF + Shield

For AWS-hosted deployments with managed rules.

Nginx + fail2ban

Self-hosted: ban IPs exceeding rate limits.

HAProxy

Connection-level rate limiting before PHP.

Cloudflare Rate Limiting Rule (example)

Cloudflare — Rate Limiting

Match:    http.request.uri.path contains "/api/v1/"
Action:   Rate limiting — 500 requests per minute per IP
Response: 429 Too Many Requests

HTTPS Enforcement

All API tokens sent via Authorization: Bearer header must be transmitted over HTTPS only.

Apache

.htaccess

# Enforce HTTPS for API routes
RewriteCond %{HTTPS} off
RewriteCond %{REQUEST_URI} ^/api/v1/
RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

Nginx

nginx.conf — http block

if ($scheme != "https") {
    return 301 https://$host$request_uri;
}

Production Checklist

Ensure all items are configured before going live.

Web server slow HTTP protection configured (Apache / Nginx)

client_max_body_size matches application body limit (default 256KB)

MySQL grants on api_rate and api_logs tables restricted to app user

HTTPS enforced for /api/v1/ routes

WAF or reverse proxy in place for high-traffic deployments

api_allow_query_token left OFF (default) unless embed mode intentionally needed

Log retention cron job configured (default: purge logs older than 90 days)

Public Chart Reports

Public data views with embeddable chart reports. Click any report to open it in a new tab.

Activity Log

/embed/report/activity-log

Type URI	`https://databuilder.polyxgo.com/api_docs#error-query-string-too-long`
Description	The URL query string exceeds the maximum allowed length (default 4KB). This is a protection against query-based abuse.
Resolution	Reduce the number or length of query parameters. Use POST with a JSON body for complex queries.
Source	`DdosShieldMiddleware`

Type URI	`https://databuilder.polyxgo.com/api_docs#error-batching-not-supported`
Description	GraphQL operation batching (sending an array of operations in a single request) is not supported. This restriction prevents rate-limit bypass via operation packing.
Resolution	Send a single GraphQL operation object per request, not an array.
Source	`Db_graphql`

Type URI	`https://databuilder.polyxgo.com/api_docs#error-invalid-parameter`
Description	One or more query parameters have invalid values. For aggregation endpoints, the `aggregation` parameter must be one of: sum, avg, count, min, max.
Resolution	Check the error detail for which parameter is invalid and what values are accepted.
Source	`Db_views`

Type URI	`https://databuilder.polyxgo.com/api_docs#error-invalid-token`
Description	The provided token is not valid. It may have been revoked, expired, or was never issued. Tokens are validated by computing SHA-256 hash and comparing against stored hashes.
Resolution	Verify the token is correct and has not been revoked. Check if the token has an expiration date. Generate a new token from the admin panel if needed.
Source	`AuthGateMiddleware`

Type URI	`https://databuilder.polyxgo.com/api_docs#error-unauthorized`
Description	The token was not properly resolved before the scope verification stage. This typically indicates a middleware pipeline configuration error.
Resolution	This is a server-side configuration issue. Contact the system administrator.
Source	`ScopeVerifierMiddleware`

API Overview

Getting Started

Authentication

HMAC Verification

Testing with Postman

Step 1 — Create an API Token

Step 2 — Export the Postman Collection

Step 3 — Import into Postman

Step 4 — Configure Collection Variables

Step 5 — Send Your First Request

Step 6 — Production Security: HMAC Signatures

Available Query Parameters

Testing with OpenAPI

Step 1 — Download the OpenAPI Spec

Custom YAML Export

Step 2 — Import into Your Favorite Tool

Step 3 — Integrate with ChatGPT (OpenAI Actions)

Step 4 — Testing GraphQL with the OpenAPI Spec

What's Included in the Spec

Deployment Guide

Slow HTTP Protection

Apache

Nginx

Body Size Limit Alignment

MySQL Permissions

Reverse Proxy / WAF

Cloudflare Rate Limiting Rule (example)

HTTPS Enforcement

Apache

Nginx

Production Checklist

Public Chart Reports

Error Reference

Examples

Sandbox GET