Embedded Forms

The Embedded Forms API allows you to add customer request forms directly to your website. When visitors submit the form, requests are created automatically in your BlueSuite workspace.

Overview

Embedded forms are ideal for:

Contact forms on your website
Service request forms
Quote request widgets
Lead capture pages

Quick Start

1. Create an API Key

Go to Settings > Integrations in BlueSuite
Click Create Embed Form Key
Copy your API key (format: wk_abc12345.secret...)

2. Submit Form Data

const response = await fetch('https://app.bluesuite.com/api/forms/embed-request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    apiKey: 'wk_abc12345.your_secret_key',
    formData: {
      firstName: 'John',
      lastName: 'Smith',
      email: 'john@example.com',
      phone: '+15551234567',
      description: 'I need a quote for window cleaning',
    },
  }),
});

const result = await response.json();

API Reference

Submit Form

POST /api/forms/embed-request

Required Scope: forms:write

Request Body

Field	Type	Required	Description
`apiKey`	string	Yes	Your embed form API key
`workspaceId`	number	No	Required only for legacy API keys
`formData`	object	Yes	Form field values

Form Data Fields

Field	Type	Required	Description
`firstName`	string	Yes	Customer's first name (max 50 chars)
`lastName`	string	Yes	Customer's last name (max 50 chars)
`email`	string	Yes	Valid email address
`phone`	string	Yes	Phone number (E.164 format recommended)
`description`	string	Yes	Service description (5-1000 chars)
`company`	string	No	Company name (max 100 chars)
`property`	object	No	Property address (see below)
`customFields`	object	No	Custom field values
`website`	string	No	Honeypot field (leave empty)

Property Fields (Optional)

{
  "property": {
    "street": "123 Main St",
    "street_2": "Suite 100",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  }
}

Success Response

{
  "success": true,
  "data": {
    "requestId": 456,
    "requestNumber": "REQ-2024-0042",
    "contactId": 123,
    "propertyId": 789
  }
}

Error Responses

Validation Error (400):

{
  "success": false,
  "error": "Invalid request data",
  "details": [
    {
      "path": ["formData", "email"],
      "message": "Valid email is required"
    }
  ]
}

Rate Limited (429):

{
  "success": false,
  "error": "Rate limit exceeded"
}

Complete Example

Here's a complete HTML form implementation:

<form id="request-form">
  <input type="text" name="firstName" placeholder="First Name" required />
  <input type="text" name="lastName" placeholder="Last Name" required />
  <input type="email" name="email" placeholder="Email" required />
  <input type="tel" name="phone" placeholder="Phone" required />
  <textarea name="description" placeholder="How can we help?" required></textarea>

  <!-- Honeypot (hidden) -->
  <input type="text" name="website" style="display: none" />

  <button type="submit">Submit Request</button>
</form>

<script>
  const API_KEY = 'wk_abc12345.your_secret_key';

  document.getElementById('request-form').addEventListener('submit', async (e) => {
    e.preventDefault();

    const form = e.target;
    const formData = {
      firstName: form.firstName.value,
      lastName: form.lastName.value,
      email: form.email.value,
      phone: form.phone.value,
      description: form.description.value,
      website: form.website.value, // Honeypot
    };

    try {
      const response = await fetch('https://app.bluesuite.com/api/forms/embed-request', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ apiKey: API_KEY, formData }),
      });

      const result = await response.json();

      if (result.success) {
        alert('Request submitted successfully!');
        form.reset();
      } else {
        alert('Error: ' + result.error);
      }
    } catch (error) {
      alert('Failed to submit. Please try again.');
    }
  });
</script>

Rate Limiting

Embedded forms are rate-limited to prevent abuse:

100 requests per hour per workspace
Rate limits reset every hour

If you exceed the limit, you'll receive a 429 status code.

CORS Support

The embed form endpoint supports cross-origin requests (CORS):

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

This allows forms to be submitted from any domain.

Spam Prevention

Honeypot Field

Include a hidden website field in your form. If this field has a value when submitted, the request is rejected as spam:

<!-- Hidden from users, filled by bots -->
<input type="text" name="website" style="display: none" tabindex="-1" autocomplete="off" />

Server-side Validation

BlueSuite validates:

Email format
Phone number format
Required field lengths
Custom field types

Custom Fields

If your workspace has custom fields configured, you can include them:

{
  "formData": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "john@example.com",
    "phone": "+15551234567",
    "description": "Window cleaning quote",
    "customFields": {
      "property_type": "residential",
      "preferred_date": "2024-02-15",
      "number_of_windows": 12
    }
  }
}

Contact your BlueSuite administrator to learn which custom fields are available.

Security Best Practices

Use HTTPS on your website
Keep API keys secure - Embed form keys are designed to be used client-side, but avoid exposing other key types
Implement honeypot fields to reduce spam
Validate client-side before submitting to improve UX
Handle errors gracefully in your form UI

On this page