Veristiq - Independent Fairness Verification

Authentication

The API uses Bearer Token authentication. You must send your API key in the Authorization header of every request.

Authorization: Bearer caas_live_8923n98...

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Competitions

POST

Create Competition

POST/api/v1/operator/competitions

Creates a new competition instance. Returns the created competition object with a UUID.

Parameter	Type	Description
external_id *	string	Your unique identifier for this competition.
name *	string	Public name/title of the competition.
max_tickets *	integer	Total available tickets.
draw_at *	timestamp	Scheduled draw time (ISO 8601 format).
prizes *	array	Array of prizes for this competition (minimum 1 prize required).
prizes[].external_id *	string	Your unique identifier for this prize within the competition.
prizes[].name *	string	Name/title of the prize.

Example Request

{
    "id": "956774e8-9835-4c54-9eb2-ce099db4e5f0",
    "external_id": "APPLE_PRODUCTS",
    "name": "Apple Mega Giveaway",
    "max_tickets": 1000,
    "draw_at": "2025-12-25T12:00:00Z",
    "prizes": [
        {
        "external_id": "MACBOOK",
        "title": "Macbook Pro"
        },
        {
        "external_id": "IPAD", 
        "title": "iPad Air"
        },
        {
        "external_id": "IPHONE17PRO",
        "title": "iPhone 17 Pro"
        }
    ]
}

GET

Get Competition

GET/api/v1/operator/competitions/{external_id}

Retrieves details and current status of a competition by your external ID. Includes all prizes with their draw status.

{
    "id": "956774e8-9835-4c54-9eb2-ce099db4e5f0",
    "name": "Apple Products",
    // ... competition details
}

PUT

Update Competition

PUT/api/v1/operator/competitions/{external_id}

Updates an existing competition's details. Prize modifications are only allowed when status is 'pending' or 'active', and prizes that have been drawn cannot be deleted.

Parameter	Type	Description
external_id *	string	Your unique identifier for this competition.
name *	string	Public name/title of the competition.
max_tickets *	integer	Total available tickets.
draw_at *	timestamp	Scheduled draw time (ISO 8601 format).
prizes *	array	Array of prizes for this competition (minimum 1 prize required).
prizes[].external_id *	string	Your unique identifier for this prize within the competition.
prizes[].name *	string	Name/title of the prize.

Example Request

{
        "external_id": "SAMSUNG_PRODUCTS",
        "name": "Samsung Products",
        "max_tickets": 20000,
        "draw_at": "2026-01-01 11:00:00",
        "prizes": [
            {
                "external_id": "GALAXY_TAB_11",
                "title": "Galaxy Tab 11"
            }
        ]
    }

POST

Close Competition

POST/api/v1/operator/competitions/{external_id}/close

Closes the competition to new entries, preparing it for the draw.

{
        "id": "956774e8-9835-4c54-9eb2-ce099db4e5f0",
        "status": "awaiting_draw",
        // ...
    }

GET

Get Competition Stats

GET/api/v1/operator/competitions/{external_id}/stats

Retrieves statistics including total entries, revenue estimates, and remaining tickets.

{
        "competition_id": "956774e8-9835-4c54-9eb2-ce099db4e5f0",
        "total_entries": 1250,
        "revenue_estimated": 12500.00,
        "tickets_sold": 1250,
        "tickets_remaining": 750,
        "percentage_sold": 62.5
    }

Entries

POST

Submit Paid Entry

POST/api/v1/operator/competitions/{competition_external_id}/entries

Registers a paid entry for a user. Returns the assigned ticket number(s).

Parameter	Type	Description
external_id *	string	Your unique transaction/entry ID.
user_reference	string	User identifier (hashed/masked recommended for privacy).
eligible *	boolean	Whether this entry should be entered into the final draw. Only entries with true are eligible for the draw.

POST

Submit Free Entry

POST/api/v1/operator/competitions/{competition_external_id}/free-entries

Registers a postal or promotional entry. These are tracked separately for compliance reporting.

Parameter	Type	Description
external_id *	string	Your unique transaction/entry ID.
user_reference *	string	Identifier for the user submitting the free entry.
reason	string	Reason for free entry (e.g., 'postal', 'promotional', 'compensation').
eligible *	boolean	Whether this entry should be entered into the final draw. Only entries with true are eligible for the draw.

DELETE

Void Entry

DELETE/api/v1/operator/competitions/{competition_external_id}/entries/{entry_external_id}

Voids a previously submitted entry. This action is recorded in the audit log.

Parameter	Type	Description
reason	string	Reason for cancellation. Must be one of: refund, cancellation, duplicate, fraud, other
notes	string	Additional information.

Draws

POST

Trigger Draw

POST/api/v1/operator/competitions/{competition_external_id}/draws/run

Initiates the CSPRNG draw process. You can draw a specific prize or all undrawn prizes at once. When drawing all prizes, previous winners are automatically excluded from subsequent prize draws.

{
            "success": true,
            "competition_id": "956774e8-9835-4c54-9eb2-ce099db4e5f0",
            "total_prizes_drawn": 2,
            "draws": [
                {
                    "id": "...",
                    "drawn_at": "2025-11-20T11:25:24.000000Z",
                    "signature_hash": "71b4d0f1d3e8f145b60d37f1bf2b7d7c5985bc59d408143ff4a49a969a5b5511",
                    "prize": { "title": "Galaxy Tab 11" },
                    "winner": { "entry": { "number": 1 } }
                }
            ],
            "audit_url": "https://veristiq.io/audit/956774e8..."
        }

GET

Get Audit Logs

GET/api/v1/operator/competitions/{competition_external_id}/audits

Retrieves the full cryptographic audit chain and event history for a competition. Each prize draw creates its own audit record linked to the global audit chain.

{
    "competition_id": "CHRISTMAS2025",
    "total_draws": 3,
    "audits": [
        {
        "draw_id": "draw_abc123...",
        "prize_id": "GRAND_PRIZE",
        "rng_seed_hash": "a3f8d9e2...",
        "signature_hash": "a3f8d9e2...",
        "previous_signature_hash": "f2a8c9d4...",
        "pool_hash": "d4f2a8c9..."
        }
    ]
    }

Compliance

GET

Get Compliance Summary

GET/api/v1/operator/compliance

Retrieves your current compliance score and any outstanding requirements.

{
    "overall_score": 98,
    "status": "compliant",
    "requirements": [
        {
            "id": "req_audit_logs",
            "status": "pass",
            "description": "All draws have verifiable audit logs"
        },
        {
            "id": "req_complaints",
            "status": "pass",
            "description": "Complaint resolution under 72h"
        }
    ]
}

POST

Log Complaint

POST/api/v1/operator/complaints

Log a user complaint for regulatory tracking and resolution.

Parameter	Type	Description
competition_id *	string	External ID of the related competition.
user_reference *	string	User raising the complaint.
description *	text	Details of the complaint.

Webhooks

POST

Create Subscription

POST/api/v1/operator/webhooks

Subscribe to platform events such as 'draw.completed' or 'audit.generated'.

Parameter	Type	Description
url *	url	HTTPS endpoint to receive payloads.
events *	array	List of event types to subscribe to (e.g., ['draw.completed']).

GET

List Webhooks

GET/api/v1/operator/webhooks

List all active webhook subscriptions.

{
    "data": [
        {
            "id": "wh_123",
            "url": "https://yourapp.com/webhooks",
            "events": ["draw.completed"],
            "created_at": "2025-11-20T10:00:00Z"
        }
    ]
}

Parameter

Type

Description

external_id *

string

Your unique identifier for this competition.

name *

string

Public name/title of the competition.

max_tickets *

integer

Total available tickets.

draw_at *

timestamp

Scheduled draw time (ISO 8601 format).

prizes *

array

Array of prizes for this competition (minimum 1 prize required).

prizes[].external_id *

string

Your unique identifier for this prize within the competition.

prizes[].name *

string

Name/title of the prize.

{ "id": "956774e8-9835-4c54-9eb2-ce099db4e5f0", "external_id": "APPLE_PRODUCTS", "name": "Apple Mega Giveaway", "max_tickets": 1000, "draw_at": "2025-12-25T12:00:00Z", "prizes": [ { "external_id": "MACBOOK", "title": "Macbook Pro" }, { "external_id": "IPAD", "title": "iPad Air" }, { "external_id": "IPHONE17PRO", "title": "iPhone 17 Pro" } ] }

Parameter

Type

Description

external_id *

string

Your unique identifier for this competition.

name *

string

Public name/title of the competition.

max_tickets *

integer

Total available tickets.

draw_at *

timestamp

Scheduled draw time (ISO 8601 format).

prizes *

array

Array of prizes for this competition (minimum 1 prize required).

prizes[].external_id *

string

Your unique identifier for this prize within the competition.

prizes[].name *

string

Name/title of the prize.

{ "external_id": "SAMSUNG_PRODUCTS", "name": "Samsung Products", "max_tickets": 20000, "draw_at": "2026-01-01 11:00:00", "prizes": [ { "external_id": "GALAXY_TAB_11", "title": "Galaxy Tab 11" } ] }

{ "competition_id": "956774e8-9835-4c54-9eb2-ce099db4e5f0", "total_entries": 1250, "revenue_estimated": 12500.00, "tickets_sold": 1250, "tickets_remaining": 750, "percentage_sold": 62.5 }

Parameter

Type

Description

external_id *

string

Your unique transaction/entry ID.

user_reference

string

User identifier (hashed/masked recommended for privacy).

eligible *

boolean

Whether this entry should be entered into the final draw. Only entries with true are eligible for the draw.

Parameter

Type

Description

external_id *

string

Your unique transaction/entry ID.

user_reference *

string

Identifier for the user submitting the free entry.

reason

string

Reason for free entry (e.g., 'postal', 'promotional', 'compensation').

eligible *

boolean

Whether this entry should be entered into the final draw. Only entries with true are eligible for the draw.

Parameter

Type

Description

reason

string

Reason for cancellation. Must be one of: refund, cancellation, duplicate, fraud, other

notes

string

Additional information.

{ "success": true, "competition_id": "956774e8-9835-4c54-9eb2-ce099db4e5f0", "total_prizes_drawn": 2, "draws": [ { "id": "...", "drawn_at": "2025-11-20T11:25:24.000000Z", "signature_hash": "71b4d0f1d3e8f145b60d37f1bf2b7d7c5985bc59d408143ff4a49a969a5b5511", "prize": { "title": "Galaxy Tab 11" }, "winner": { "entry": { "number": 1 } } } ], "audit_url": "https://veristiq.io/audit/956774e8..." }

{ "competition_id": "CHRISTMAS2025", "total_draws": 3, "audits": [ { "draw_id": "draw_abc123...", "prize_id": "GRAND_PRIZE", "rng_seed_hash": "a3f8d9e2...", "signature_hash": "a3f8d9e2...", "previous_signature_hash": "f2a8c9d4...", "pool_hash": "d4f2a8c9..." } ] }

{ "overall_score": 98, "status": "compliant", "requirements": [ { "id": "req_audit_logs", "status": "pass", "description": "All draws have verifiable audit logs" }, { "id": "req_complaints", "status": "pass", "description": "Complaint resolution under 72h" } ] }

Parameter

Type

Description

competition_id *

string

External ID of the related competition.

user_reference *

string

User raising the complaint.

description *

text

Details of the complaint.

Parameter

Type

Description

url *

url

HTTPS endpoint to receive payloads.

events *

array

List of event types to subscribe to (e.g., ['draw.completed']).

{ "data": [ { "id": "wh_123", "url": "https://yourapp.com/webhooks", "events": ["draw.completed"], "created_at": "2025-11-20T10:00:00Z" } ] }

API Reference

Authentication

Competitions

Create Competition

Get Competition

Update Competition

Close Competition

Get Competition Stats

Entries

Submit Paid Entry

Submit Free Entry

Void Entry

Draws

Trigger Draw

Get Audit Logs

Compliance

Get Compliance Summary

Log Complaint

Webhooks

Create Subscription

List Webhooks

API Reference

Authentication

Competitions

Create Competition

Get Competition

Update Competition

Close Competition

Get Competition Stats

Entries

Submit Paid Entry

Submit Free Entry

Void Entry

Draws

Trigger Draw

Get Audit Logs

Compliance

Get Compliance Summary

Log Complaint

Webhooks

Create Subscription

List Webhooks