Introduction

Raffle API

Overview

Staff create a raffle campaign with an active and inactive time. Each campaign has its own public entry URL.

One receipt upload is one entry. The same receipt uploaded again creates another entry.

Access

POST /v1/campaigns — staff (Authorization: Bearer JWT from Directory)
GET /v1/public/campaigns/{slug} — public campaign window
POST /v1/public/campaigns/{slug}/entries — public entry (full name, email, phone, one receipt image)

All routes are under /v1. Gateway base: https://api.mayawealth.co.uk/raffle.

Errors use { error: { code, message, details?, request_id? } }.

Integration guide: Raffle service docs

OpenAPI v0.1.0 · source openapi/raffle.json

OpenAPI 3.1.0 · v0.1.0 · 11 operations

Operations

System

Liveness.

get/health

Health check

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/raffle/health"

Operation ID: getHealth

Responses

200
Service is running
application/json

get/v1/health

Health check (versioned)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/raffle/v1/health"

Operation ID: getHealthV1

Responses

200
Service is running
application/json

Campaigns

Staff campaign management.

get/v1/campaigns

List campaigns

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/raffle/v1/campaigns"

Operation ID: listCampaigns

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—

Responses

200
Campaigns for this organisation
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
422
Invalid body, or the campaign is closed. `error.code`: VALIDATION_ERROR or CAMPAIGN_CLOSED.
application/json
429
Rate limit exceeded for this IP and campaign. `error.code`: RATE_LIMITED.
application/json

post/v1/campaigns

Create a raffle campaign

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/raffle/v1/campaigns"

Creates a campaign that accepts entries from startsAt until endsAt. The response includes the public entry path.

Operation ID: createCampaign

Request body(required)

application/jsonCampaignCreate

Responses

201
Campaign created
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The campaign or entry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid body, or the campaign is closed. `error.code`: VALIDATION_ERROR or CAMPAIGN_CLOSED.
application/json
429
Rate limit exceeded for this IP and campaign. `error.code`: RATE_LIMITED.
application/json

get/v1/campaigns/{id}

Get a campaign

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/raffle/v1/campaigns/example-id"

Operation ID: getCampaign

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Campaign
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The campaign or entry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid body, or the campaign is closed. `error.code`: VALIDATION_ERROR or CAMPAIGN_CLOSED.
application/json
429
Rate limit exceeded for this IP and campaign. `error.code`: RATE_LIMITED.
application/json

patch/v1/campaigns/{id}

Update a campaign window

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/raffle/v1/campaigns/example-id"

Changes the name or the active window. Set endsAt to now to close the campaign early.

Operation ID: updateCampaign

Parameters

Name	In	Type	Description
id*	path	string	—

Request body(required)

application/jsonCampaignPatch

Responses

200
Updated campaign
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The campaign or entry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid body, or the campaign is closed. `error.code`: VALIDATION_ERROR or CAMPAIGN_CLOSED.
application/json
429
Rate limit exceeded for this IP and campaign. `error.code`: RATE_LIMITED.
application/json

Entries

Staff entry inbox and receipt download.

get/v1/campaigns/{id}/entries

List entries

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/raffle/v1/campaigns/example-id/entries"

Each row is one receipt. The same receipt image can appear more than once.

Operation ID: listEntries

Parameters

Name	In	Type	Description
id*	path	string	—
page	query	integer	—
page_size	query	integer	—

Responses

200
Entries for this campaign
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The campaign or entry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid body, or the campaign is closed. `error.code`: VALIDATION_ERROR or CAMPAIGN_CLOSED.
application/json
429
Rate limit exceeded for this IP and campaign. `error.code`: RATE_LIMITED.
application/json

get/v1/campaigns/{id}/entries/{entryId}

Get one entry

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/raffle/v1/campaigns/example-id/entries/example-id"

Operation ID: getEntry

Parameters

Name	In	Type	Description
id*	path	string	—
entryId*	path	string	—

Responses

200
Entry
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The campaign or entry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid body, or the campaign is closed. `error.code`: VALIDATION_ERROR or CAMPAIGN_CLOSED.
application/json
429
Rate limit exceeded for this IP and campaign. `error.code`: RATE_LIMITED.
application/json

get/v1/campaigns/{id}/entries/{entryId}/receipt

Download a receipt image

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/raffle/v1/campaigns/example-id/entries/example-id/receipt"

Operation ID: downloadEntryReceipt

Parameters

Name	In	Type	Description
id*	path	string	—
entryId*	path	string	—

Responses

200
Receipt image bytes
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The campaign or entry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid body, or the campaign is closed. `error.code`: VALIDATION_ERROR or CAMPAIGN_CLOSED.
application/json
429
Rate limit exceeded for this IP and campaign. `error.code`: RATE_LIMITED.
application/json

Public

Public campaign window and receipt entry.

get/v1/public/campaigns/{slug}

Public campaign window

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/raffle/v1/public/campaigns/example-id"

Returns the campaign name and whether it is accepting entries. Does not return entrant data.

Operation ID: getPublicCampaign

Parameters

Name	In	Type	Description
slug*	path	string	—

Responses

200
Public campaign
application/json
403
The organisation cannot use this service. `error.code`: FORBIDDEN or SERVICE_DISABLED.
application/json
404
The campaign or entry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid body, or the campaign is closed. `error.code`: VALIDATION_ERROR or CAMPAIGN_CLOSED.
application/json
429
Rate limit exceeded for this IP and campaign. `error.code`: RATE_LIMITED.
application/json
502
The raffle service could not complete this request. `error.code`: INTERNAL.
application/json

post/v1/public/campaigns/{slug}/entries

Submit one receipt as one entry

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/raffle/v1/public/campaigns/example-id/entries"

One request stores one entry. Qualifying items on the receipt are not counted separately. Uploading the same receipt again creates another entry.

Operation ID: createEntry

Parameters

Name	In	Type	Description
slug*	path	string	—

Request body(required)

application/jsonEntryCreate

Responses

201
Entry stored
application/json
403
The organisation cannot use this service. `error.code`: FORBIDDEN or SERVICE_DISABLED.
application/json
404
The campaign or entry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid body, or the campaign is closed. `error.code`: VALIDATION_ERROR or CAMPAIGN_CLOSED.
application/json
429
Rate limit exceeded for this IP and campaign. `error.code`: RATE_LIMITED.
application/json
502
The raffle service could not complete this request. `error.code`: INTERNAL.
application/json