Introduction

Enquiry API

Overview

Accepts enquiry POSTs from marketing sites, stores submissions in D1 (and attachments in R2), optionally sends team email, and can notify integrators via webhooks.

Team notification addresses are configured on the Worker — they are never taken from the form body.

Access

POST /v1/enquiries — public browser forms (origin check + Turnstile)
GET /v1/integration/organisations/{organisationId}/enquiries — CRM and automation (X-Enquiry-Api-Key + X-Enquiry-Integration-Secret; /v1/public/enquiries is deprecated)
GET /v1/enquiries — staff inbox (Authorization: Bearer JWT from Directory)
Webhooks — enquiry.created and enquiry.status_changed to {SITE}_ENQUIRY_WEBHOOK_URL when configured on the Worker

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

Errors use { error: { code, message, details?, request_id? } } with codes such as VALIDATION_ERROR, FORBIDDEN, RATE_LIMITED, UNAUTHORIZED, NOT_FOUND, and INTERNAL.

Integration guide: Enquiry service docs

OpenAPI v0.1.0 · source openapi/enquiry.json

OpenAPI 3.1.0 · v0.1.0 · 12 operations

Operations

System

Liveness and generated documentation.

get/health

Health check

Example request

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

Unauthenticated liveness probe. Does not send mail or check Turnstile.

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/enquiry/v1/health"

Unauthenticated liveness probe. Does not send mail or check Turnstile.

Operation ID: getHealthV1

Responses

200
Service is running
application/json

Audit

Enquiry activity log.

get/v1/audit

Enquiry audit trail

Example request

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

Operation ID: listEnquiryAudit

Responses

200
Audit events
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
422
Invalid JSON body or incomplete enquiry fields. `error.code`: VALIDATION_ERROR.
application/json
429
Rate limit exceeded for this IP and site. `error.code`: RATE_LIMITED.
application/json

Enquiries

Public marketing-site submissions and JWT staff inbox.

get/v1/enquiries

List stored enquiries

Example request

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

Authenticated inbox of marketing-site submissions persisted after a successful POST.

Operation ID: listEnquiries

Parameters

Name	In	Type	Description
status	query	string	Inbox status for a stored enquiry.
site	query	string	—
q	query	string	—
page	query	integer	—
page_size	query	integer	—

Responses

200
Stored enquiries
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
422
Invalid JSON body or incomplete enquiry fields. `error.code`: VALIDATION_ERROR.
application/json
429
Rate limit exceeded for this IP and site. `error.code`: RATE_LIMITED.
application/json

post/v1/enquiries

Submit an enquiry

Example request

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

Accepts a marketing-site form, validates it, stores the enquiry in D1, persists attachments in R2, and optionally sends team email when ENQUIRY_EMAIL_ENABLED=true.

Operation ID: createEnquiry

Request body(required)

application/jsonEnquiryRequest

Responses

202
Enquiry accepted (stored; email optional)
application/json
403
Origin is not allowed. `error.code`: FORBIDDEN.
application/json
422
Invalid JSON body or incomplete enquiry fields. `error.code`: VALIDATION_ERROR.
application/json
429
Rate limit exceeded for this IP and site. `error.code`: RATE_LIMITED.
application/json
502
The message could not be sent. `error.code`: INTERNAL.
application/json

get/v1/enquiries/{id}

Get a stored enquiry

Example request

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

Operation ID: getEnquiry

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Stored enquiry
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The enquiry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid JSON body or incomplete enquiry fields. `error.code`: VALIDATION_ERROR.
application/json
429
Rate limit exceeded for this IP and site. `error.code`: RATE_LIMITED.
application/json

patch/v1/enquiries/{id}

Update enquiry status

Example request

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

Marks an enquiry as new, read, or closed.

Operation ID: updateEnquiryStatus

Parameters

Name	In	Type	Description
id*	path	string	—

Request body(required)

application/jsonEnquiryStatusPatch

Responses

200
Updated enquiry
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The enquiry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid JSON body or incomplete enquiry fields. `error.code`: VALIDATION_ERROR.
application/json
429
Rate limit exceeded for this IP and site. `error.code`: RATE_LIMITED.
application/json

get/v1/enquiries/{id}/attachments/{attachmentId}

Download an enquiry attachment

Example request

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

Operation ID: downloadEnquiryAttachment

Parameters

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

Responses

200
Attachment file bytes
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The enquiry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid JSON body or incomplete enquiry fields. `error.code`: VALIDATION_ERROR.
application/json
429
Rate limit exceeded for this IP and site. `error.code`: RATE_LIMITED.
application/json

Integration

Per-site API key and integration secret; `organisationId` must match the site org. Optional signed webhooks on create and status change.

get/v1/integration/organisations/{organisationId}/enquiries

List enquiries for the authenticated organisation

Example request

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

Requires `X-Enquiry-Api-Key`, `X-Enquiry-Integration-Secret`, and `organisationId` matching the key's site org. Optional webhooks: `{SITE}_ENQUIRY_WEBHOOK_URL`.

Operation ID: listIntegrationEnquiries

Parameters

Name	In	Type	Description
organisationId*	path	string	Directory organisation id for the site tied to the API key.
status	query	string	Inbox status for a stored enquiry.
site	query	string	—
q	query	string	—
page	query	integer	—
page_size	query	integer	—

Responses

200
Enquiries for this organisation
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The enquiry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid JSON body or incomplete enquiry fields. `error.code`: VALIDATION_ERROR.
application/json
429
Rate limit exceeded for this IP and site. `error.code`: RATE_LIMITED.
application/json

get/v1/integration/organisations/{organisationId}/enquiries/{id}

Get one enquiry

Example request

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

Operation ID: getIntegrationEnquiry

Parameters

Name	In	Type	Description
organisationId*	path	string	Directory organisation id for the site tied to the API key.
id*	path	string	—

Responses

200
Enquiry
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The enquiry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid JSON body or incomplete enquiry fields. `error.code`: VALIDATION_ERROR.
application/json
429
Rate limit exceeded for this IP and site. `error.code`: RATE_LIMITED.
application/json

patch/v1/integration/organisations/{organisationId}/enquiries/{id}

Update enquiry status

Example request

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

Operation ID: updateIntegrationEnquiryStatus

Parameters

Name	In	Type	Description
organisationId*	path	string	Directory organisation id for the site tied to the API key.
id*	path	string	—

Request body(required)

application/jsonEnquiryStatusPatch

Responses

200
Updated enquiry
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The enquiry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid JSON body or incomplete enquiry fields. `error.code`: VALIDATION_ERROR.
application/json
429
Rate limit exceeded for this IP and site. `error.code`: RATE_LIMITED.
application/json

get/v1/integration/organisations/{organisationId}/enquiries/{id}/attachments/{attachmentId}

Download an enquiry attachment

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/enquiry/v1/integration/organisations/example-id/enquiries/example-id/attachments/example-id"

Operation ID: downloadIntegrationEnquiryAttachment

Parameters

Name	In	Type	Description
organisationId*	path	string	Directory organisation id for the site tied to the API key.
id*	path	string	—
attachmentId*	path	string	—

Responses

200
Attachment file bytes
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED.
application/json
404
The enquiry was not found. `error.code`: NOT_FOUND.
application/json
422
Invalid JSON body or incomplete enquiry fields. `error.code`: VALIDATION_ERROR.
application/json
429
Rate limit exceeded for this IP and site. `error.code`: RATE_LIMITED.
application/json