Legacy embedded forms
Maintain existing v1 embed snippets and migrate new work to Client Forms
This API is retained for existing v1 embed snippets. Use Client Forms for new website forms and booking flows, or Leads for authenticated server-to-server inquiry capture.
Submit an existing embed form
POST /api/forms/embed-requestSend JSON to https://my.bluesuite.app/api/forms/embed-request. This endpoint reads the API key from apiKey in the body or api_key in the query, not from the Bearer header. Use a dedicated embed key with forms:write. Old-format keys also require workspaceId.
| Field | Required | Meaning |
|---|---|---|
apiKey | Unless in query | Embed API key |
workspaceId | For legacy key format | Positive workspace ID |
formData | Yes | Object described below |
| formData field | Required | Meaning |
|---|---|---|
firstName, lastName | Yes | 1 to 50 characters each |
email | Yes | Valid email |
phone | Yes | Digits, optional leading +, first digit 1 to 9 |
description | Yes | 5 to 1,000 characters |
company | No | Up to 100 characters |
property | No | Object with required street (1 to 100 characters); optional street2, city, state, zip |
customFields | No | Values keyed by configured custom-field keys |
website | No | Honeypot; leave empty |
{
"apiKey": "wk_example.your_embed_key",
"formData": {
"firstName": "Jamie",
"lastName": "Rivera",
"email": "jamie@example.com",
"phone": "+15551234567",
"description": "Please contact me about annual maintenance.",
"website": ""
}
}The flow resolves/creates the contact, optionally creates a property, and creates a request. The requests module must be enabled. This legacy flow does not create a Client Form submission record.
Success is 201 with { "success": true, "data": { "requestId": 42, "requestNumber": 10, "contactId": 12, "propertyId": null } }.
Malformed input returns 400, bad credentials 401, a filled honeypot 422, and exceeding 100 submissions per hour per workspace returns 429. Other failures include unavailable workspaces or disabled requests. The endpoint supports browser CORS; use only a dedicated embed key in client-side code.
Country configuration
GET /api/forms/embed-configSupply api_key in the query with forms:read; old keys also need workspace_id. Returns { "country": "US" } using the workspace country (US fallback). The response may be cached for one hour.