Form Customization

Customize your form's appearance, labels, and colors using the Agent API.

Getting Form Details

Endpoint: GET /api/agent/form

Headers:

Authorization: Bearer sr_live_your_api_key

Response:

{
  "form": {
    "id": "uuid",
    "title": "Get Support",
    "description": "Fill in the following details...",
    "background_color": "f9f9fb",
    "button_color": "3f3ea2",
    "text_color": "000000",
    "logo_url": "https://...",
    "button_text": "SEND",
    "field_name_label": "Name",
    "field_email_label": "Email",
    "field_message_label": "Message",
    "field_name_placeholder": "Your name",
    "field_email_placeholder": "your@email.com",
    "field_message_placeholder": "Write something nice"
  },
  "embed": {
    "direct_url": "https://supportretriever.com/form/uuid",
    "iframe": "<iframe src=\"...\"></iframe>",
    "html_link": {
      "default": "<a href=\"...\">Contact Support</a>",
      "with_styles": "<a href=\"...\" style=\"...\">Contact Support</a>"
    }
  }
}

Updating Form

Endpoint: PUT /api/agent/form

Headers:

Authorization: Bearer sr_live_your_api_key
Content-Type: application/json

Request Body (all fields optional):

{
  "title": "Contact Us",
  "description": "We'd love to hear from you!",
  "background_color": "ffffff",
  "button_color": "007bff",
  "text_color": "333333",
  "logo_url": "https://example.com/logo.png",
  "button_text": "Send Message",
  "field_name_label": "Your Name",
  "field_email_label": "Your Email",
  "field_message_label": "Your Message",
  "field_name_placeholder": "John Doe",
  "field_email_placeholder": "john@example.com",
  "field_message_placeholder": "How can we help?"
}

Response:

{
  "success": true,
  "form": {
    // Updated form object
  }
}

Customizable Fields

Visual Settings

Field	Type	Description	Example
`title`	string	Form heading (max 100 chars)	"Contact Us"
`description`	string	Form description text	"We'd love to hear from you!"
`background_color`	string	Hex color (6 chars, no #)	"ffffff"
`button_color`	string	Hex color for submit button	"007bff"
`text_color`	string	Hex color for text	"333333"
`logo_url`	string	URL of logo image	"https://example.com/logo.png"
`button_text`	string	Submit button text	"Send Message"

Field Labels

Field	Description	Example
`field_name_label`	Label for name field	"Your Name"
`field_email_label`	Label for email field	"Your Email"
`field_message_label`	Label for message field	"Your Message"

Field Placeholders

Field	Description	Example
`field_name_placeholder`	Placeholder for name input	"John Doe"
`field_email_placeholder`	Placeholder for email input	"john@example.com"
`field_message_placeholder`	Placeholder for message textarea	"How can we help?"

Protected Fields

These fields cannot be changed via the Agent API (silently ignored):

recipient_email - Email where submissions are sent
custom_email_domain - Custom email domain settings
custom_email_username - Custom email username
userID - Form owner
id - Form identifier
created_at - Creation timestamp

Why Protected?

recipient_email prevents hijacking customer messages
Other fields are system-managed

Color Format

Colors use hex format without the # symbol:

✅ Correct: "ffffff", "3f3ea2", "000000"
❌ Wrong: "#ffffff", "rgb(255,255,255)", "white"

Partial Updates

You can update only the fields you want to change:

{
  "title": "New Title",
  "button_color": "ff0000"
}

Only title and button_color will be updated; other fields remain unchanged.

Best Practices

Color Contrast

Use light backgrounds (ffffff, f9f9fb) with dark text (000000, 333333)
Ensure button color contrasts well with background
Test readability on different devices

Title Length

Keep titles short (under 50 characters)
Use action-oriented language ("Contact Us", "Get Support")

Descriptions

Keep descriptions concise (1-2 sentences)
Explain what happens after submission

Button Text

Use clear action words ("Send", "Submit", "Contact Us")
Keep it short (1-3 words)

Examples

Minimal Update (Just Colors)

{
  "background_color": "ffffff",
  "button_color": "007bff",
  "text_color": "333333"
}

Full Branding Update

{
  "title": "Contact Our Team",
  "description": "Have a question? We're here to help!",
  "background_color": "f8f9fa",
  "button_color": "28a745",
  "text_color": "212529",
  "logo_url": "https://example.com/logo.png",
  "button_text": "Send Message",
  "field_name_label": "Full Name",
  "field_email_label": "Email Address",
  "field_message_label": "Your Message",
  "field_name_placeholder": "Enter your name",
  "field_email_placeholder": "you@example.com",
  "field_message_placeholder": "Tell us how we can help..."
}