Client Forms

Client Forms are published forms created in the BlueSuite dashboard. Use the provided embed snippet or hosted form link for a ready-made interface. A custom renderer can use the public APIs below. No workspace API key belongs in these requests.

The form must be published and its workspace/features available. Use the workspace and form slugs from its public link. Load the current definition rather than hardcoding field IDs.

Read form configuration

GET /api/client-forms/config?workspace=:workspaceSlug&form=:formSlug

Returns 200 with success: true and data containing:

• form: name, description, instructions, and bookingEnabled.
• fields: field IDs, types, labels, helper text, required flags, options, and service IDs.
• services and theme: offered services and resolved branding.
• booking: slot interval settings, or null.
• upload: upload URL, public gateway key, limits, and accepted types, or null.
• submit: form submission/confirmation settings.

Missing slugs return 400. An unavailable or unpublished form returns 404.

Read appointment availability

GET /api/client-forms/slots?workspace=:workspaceSlug&form=:formSlug

Optionally pass services=1,2 for the selected offered service IDs; they affect appointment duration. Returns { "success": true, "data": { "days": [...] } }. Use the returned day/time values for booking. Availability is not cached and is rechecked at submission.

A form without booking enabled returns 404 here. Changing selected services requires fetching new availability.

Submit answers

POST /api/client-forms/submit

Send JSON:

Every answer is serialized as a string. Text/date/number fields use their text value. Checkboxes use true / false; a required checkbox must be checked. Service pickers use comma-separated service IDs. Address fields contain serialized address JSON. Signatures use serialized { "type": "typed", "value": "Jamie Rivera" } or a supported drawn PNG signature. File fields contain the uploaded storage path.

Field IDs, required answers, choices, and service selections are validated against the published form. Do not invent an answer for a missing required field.

{
  "workspace": "your-workspace",
  "form": "request-service",
  "values": [
    {"form_field_id": 12, "value": "Jamie Rivera"},
    {"form_field_id": 13, "value": "jamie@example.com"}
  ],
  "booking": null,
  "website": "",
  "source": "embed"
}

Replace these field IDs and answers with the form's current definition. The maximum individual answer is 751,000 characters, with a 2,000,000-character aggregate limit; field-specific validation can be stricter.

Success returns 201 with success: true and the submission result in data, including the confirmation message. Validation returns 400. A time that was booked by someone else returns 409 with code: "SLOT_TAKEN"; refresh availability and let the customer choose again. Do not silently pick another appointment.

Upload a file

Use the upload.url and rules supplied by config. Send multipart fields file, workspace, and form. When an anonKey is provided, send it in both Authorization: Bearer ... and apikey headers; this is the public gateway key, not a workspace secret.

Accepted files are JPEG, PNG, GIF, WebP, HEIC, and PDF, up to 5 MB. The upload returns { "path": "..." }. Store that returned path as the file field's answer, then submit the form. Do not use the authenticated REST upload endpoint for anonymous form visitors.

Rate limits and CORS

Public config and availability reads allow 120 requests per hour per workspace/IP for each read route. Submissions allow 20 per hour per workspace/IP. A limit returns 429. These APIs allow cross-origin form use; keep the honeypot empty and present server validation errors to the customer.