API reference

Create campaign

Creates a campaign under the approved organization using validated details and creator ownership; draft creation is not publication.

POSThttps://api.sparkglim.net/api/white-label/v1/campaigns

Access model

Access model: Server-side Organization HMAC
Required scope: campaigns:write
Documented availability: Implemented in source

Availability is verified from source, not a live production guarantee.

Private signing stays on your server. API Version 1 uses signature format v2; it is not API v2.

Headers

Name	Type	Validation
`x-white-label-domain`Required Verified website hostname used to resolve the approved organization account and bind this request.	`string`	Validation: verified HTTPS hostname.
`x-white-label-key-id`Required Identifier extracted from the single issued Private Key value; never send its secret in this header.	`string`	Validation: issued private key internal identifier.
`x-white-label-signature-version`Required Selects the domain-bound signing format; API routes remain Version 1.	`string`	Validation: 2.
`x-white-label-timestamp`Required Request signing time in milliseconds, checked against the server clock to reject stale requests.	`string`	Validation: 13 digit milliseconds; within five minutes.
`x-white-label-nonce`Required Fresh random signing value recorded by the server to reject replay of a signed request.	`string`	Validation: fresh 16–128 [A-Za-z0-9_-].
`x-white-label-signature`Required HMAC-SHA256 of the canonical domain, idempotency key, campaign credential, timestamp, nonce, method, path, sorted query and exact body hash.	`string`	Validation: lowercase hexadecimal HMAC-SHA256.
`x-white-label-campaign-key`Optional Optional complete Campaign Key that narrows a private request to the same authorized campaign.	`string`	Validation: complete optional scoped keyId:secret.

Request

Name	Type	Validation
`title`Required Public-facing campaign title supplied by the authorized organizer.	`string`	Validation: 3–255.
`description`Required Organizer-provided description explaining this campaign or ticket type.	`string`	Validation: 10–5000.
`campaign_type`Required Selects ticketing, awards voting or donation campaign services; does not grant access to an unrelated module.	`enum`	Validation: ticketing \| voting \| donation.
`start_date`Required Campaign opening timestamp in ISO datetime format.	`string`	Validation: ISO datetime.
`end_date`Required Campaign closing timestamp in ISO datetime format.	`string`	Validation: ISO datetime.
`country_code`Optional Configured selling country code; the server checks account and market eligibility.	`string`	Validation: ISO2.
`currency_code`Optional Existing permitted campaign currency; choosing a country never authorizes a new currency.	`string`	Validation: ISO3.
`slug`Optional URL-friendly identifier for the existing campaign or published article.	`string`	Validation: configured slug schema.
`status`Optional Requested supported lifecycle state; account and campaign approval rules still control publication and access.	`enum`	Validation: draft \| pending_approval \| approved \| rejected \| archived.
`vote_price`Optional Campaign configuration value for the selected product, stored in the campaign’s own currency or capacity unit.	`number`	Validation: >=0.
`donation_goal`Optional Campaign configuration value for the selected product, stored in the campaign’s own currency or capacity unit.	`number`	Validation: >=0.
`ticket_price`Optional Campaign configuration value for the selected product, stored in the campaign’s own currency or capacity unit.	`number`	Validation: >=0.
`ticket_capacity`Optional Campaign configuration value for the selected product, stored in the campaign’s own currency or capacity unit.	`integer`	Validation: >0.
`image_url`Optional URL of the resource’s supplied image; use authorized public media.	`string\|null`	Validation: URL.
`banner_url`Optional Campaign cover artwork URL supplied by the organizer.	`string\|null`	Validation: URL.
`category`Optional Configured campaign category or approved settings category, depending on the resource.	`string\|null`	Validation: <=120.
`location`Optional Public campaign location or discovery location filter; separate from the financial selling country.	`string\|null`	Validation: <=255.
`event_date`Optional Scheduled event date/time, distinct from the campaign selling period.	`string\|null`	Validation: ISO datetime.
`verification_required`Optional Controls the supported verification requirement for the resource; it does not bypass server eligibility checks.	`boolean`	Validation: default true.
`metadata`Optional Additional JSON metadata accepted by the documented schema; it never overrides authorization, prices or account ownership.	`object`	Validation: JSON object.

Request

Examples describe the contract and are not executed. Use authorized test records; never paste a real secret into these pages.

POST /api/white-label/v1/campaigns

http

POST /api/white-label/v1/campaigns HTTP/1.1
Host: api.sparkglim.net
x-white-label-domain: events.example.com
x-white-label-key-id: <ISSUED_KEY_ID>
x-white-label-signature-version: 2
x-white-label-timestamp: <FRESH_MILLISECONDS>
x-white-label-nonce: <FRESH_SIGNING_NONCE>
x-white-label-signature: <SERVER_GENERATED_SIGNATURE>
Content-Type: application/json

{
  "title": "Example campaign",
  "description": "An illustrative campaign description.",
  "campaign_type": "ticketing",
  "start_date": "2030-06-01T09:00:00.000Z",
  "end_date": "2030-06-02T18:00:00.000Z"
}

Response

Success response · HTTP 201

json

{
  "success": true,
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "draft"
  },
  "requestId": "wlapi_example"
}

Error response · HTTP 400

json

{
  "success": false,
  "error": "<ERROR_MESSAGE>",
  "requestId": "wlapi_example"
}

Validation, permissions, unavailable records and temporary service failures use the handler’s HTTP status and error payload.

Limits & retries

Organization limiter: 120 requests per key and 300 per IP per window; honor Retry-After and X-RateLimit headers.

Source compatibility

Authorized operations require account-specific testing.

server/src/api/router.ts
server/src/api/routes/white-label.ts
server/src/white-label/auth.ts
server/src/white-label/schemas.ts
server/src/white-label/organization-service.ts
server/src/white-label/service.ts

Access model

Headers

Request

Request

Response

Limits & retries

Source compatibility

Continue building