Forms API

Overview

The Forms API allows you to programmatically manage your GoBlue forms, including creation, configuration, and data retrieval. Forms are the core of GoBlue’s automation system, defining how webhook data is processed and messages are generated.

Base URL

https://api.goblue.app/v1/forms

Authentication

All Forms API endpoints require authentication via API key. See Authentication for details.

Form Object

Properties

string

required

Unique identifier for the form (UUID format)

name

string

required

Display name for the form

description

string

Optional description of the form’s purpose

webhookUrl

string

required

The webhook URL for this form (read-only)

messageTemplate

string

required

Message template with variable placeholders

isActive

boolean

required

Whether the form is currently active

fields

array

required

Array of form field definitions

Show Field Object

name

string

required

Field name (used as variable in templates)

type

string

required

Field type: text, email, phone, number, url, date

required

boolean

required

Whether this field is required

label

string

Display label for the field

placeholder

string

Placeholder text for the field

validation

object

Validation rules for the field

settings

object

Additional form configuration

Show Settings Object

autoSend

boolean

Whether to automatically send messages via iOS Shortcuts

delayMinutes

number

Delay in minutes before sending message (default: 0)

timezone

string

Timezone for scheduling (default: UTC)

rateLimitPerDay

number

Maximum messages per day for this form

createdAt

string

required

ISO timestamp when form was created

updatedAt

string

required

ISO timestamp when form was last updated

Example Form Object

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "Website Contact Form",
  "description": "Lead capture from company website",
  "webhookUrl": "https://api.goblue.app/v1/forms/f47ac10b-58cc-4372-a567-0e02b2c3d479/webhook",
  "messageTemplate": "Hi {{firstName}}, thanks for your interest in {{serviceType}}! I'll review your project details and get back to you within 24 hours.",
  "isActive": true,
  "fields": [
    {
      "name": "firstName",
      "type": "text",
      "required": true,
      "label": "First Name",
      "placeholder": "Enter your first name"
    },
    {
      "name": "lastName", 
      "type": "text",
      "required": false,
      "label": "Last Name",
      "placeholder": "Enter your last name"
    },
    {
      "name": "phoneNumber",
      "type": "phone",
      "required": true,
      "label": "Phone Number",
      "validation": {
        "format": "international"
      }
    },
    {
      "name": "serviceType",
      "type": "text",
      "required": true,
      "label": "Service Interest"
    }
  ],
  "settings": {
    "autoSend": true,
    "delayMinutes": 0,
    "timezone": "America/New_York",
    "rateLimitPerDay": 100
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:22:00Z"
}

Endpoints

List All Forms

Retrieve all forms in your account.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.goblue.app/v1/forms

Response:

{
  "status": "success",
  "data": {
    "forms": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Website Contact Form",
        "description": "Lead capture from company website",
        "isActive": true,
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T14:22:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50
  }
}

Query Parameters:

page

number

default:"1"

Page number for pagination

limit

number

default:"50"

Number of forms per page (max: 100)

active

boolean

Filter by active status (true/false)

string

Search forms by name or description

Get Form by ID

Retrieve a specific form by its ID.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.goblue.app/v1/forms/f47ac10b-58cc-4372-a567-0e02b2c3d479

Response:

{
  "status": "success",
  "data": {
    "form": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Website Contact Form",
      "description": "Lead capture from company website",
      "webhookUrl": "https://api.goblue.app/v1/forms/f47ac10b-58cc-4372-a567-0e02b2c3d479/webhook",
      "messageTemplate": "Hi {{firstName}}, thanks for your interest in {{serviceType}}!",
      "isActive": true,
      "fields": [...],
      "settings": {...},
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T14:22:00Z"
    }
  }
}

Create Form

Create a new form with the specified configuration.

curl -X POST https://api.goblue.app/v1/forms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Lead Form",
    "description": "Capture leads from landing page",
    "messageTemplate": "Hi {{firstName}}, thanks for your interest!",
    "fields": [
      {
        "name": "firstName",
        "type": "text",
        "required": true,
        "label": "First Name"
      },
      {
        "name": "phoneNumber",
        "type": "phone", 
        "required": true,
        "label": "Phone Number"
      }
    ]
  }'

Request Body:

name

string

required

Display name for the form

description

string

Optional description of the form’s purpose

messageTemplate

string

required

Message template with placeholders

fields

array

required

Array of field definitions (at least one required)

settings

object

Optional form settings (autoSend, delayMinutes, etc.)

Response:

{
  "status": "success",
  "data": {
    "form": {
      "id": "new-form-id-here",
      "name": "New Lead Form",
      "webhookUrl": "https://api.goblue.app/v1/forms/new-form-id-here/webhook",
      "isActive": true,
      "createdAt": "2024-01-15T15:30:00Z",
      "updatedAt": "2024-01-15T15:30:00Z"
    }
  }
}

Update Form

Update an existing form’s configuration.

curl -X PUT https://api.goblue.app/v1/forms/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Contact Form",
    "messageTemplate": "Hi {{firstName}}, thanks for reaching out about {{serviceType}}!",
    "isActive": true
  }'

Response:

{
  "status": "success",
  "data": {
    "form": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Updated Contact Form",
      "messageTemplate": "Hi {{firstName}}, thanks for reaching out about {{serviceType}}!",
      "updatedAt": "2024-01-15T16:45:00Z"
    }
  }
}

Delete Form

Delete a form and all associated data.

This action is irreversible. All messages, contacts, and data associated with this form will be permanently deleted.

curl -X DELETE https://api.goblue.app/v1/forms/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "status": "success",
  "message": "Form deleted successfully",
  "data": {
    "deletedId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

Get Form Statistics

Retrieve usage statistics for a specific form.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.goblue.app/v1/forms/f47ac10b-58cc-4372-a567-0e02b2c3d479/stats

Query Parameters:

period

string

default:"30d"

Time period: 1d, 7d, 30d, 90d, 1y

timezone

string

default:"UTC"

Timezone for date calculations

Response:

{
  "status": "success",
  "data": {
    "stats": {
      "totalSubmissions": 1247,
      "totalMessages": 1195,
      "totalContacts": 892,
      "deliveryRate": 95.8,
      "averageResponseTime": 142,
      "periodStats": {
        "period": "30d",
        "submissions": 87,
        "messages": 84,
        "newContacts": 61
      },
      "dailyBreakdown": [
        {
          "date": "2024-01-15",
          "submissions": 5,
          "messages": 5,
          "contacts": 3
        }
      ]
    }
  }
}

Field Types and Validation

Supported Field Types

text

Standard text input fieldValidation Options:

minLength: Minimum character count
maxLength: Maximum character count
pattern: Regular expression pattern

Email address validationValidation Options:

domains: Array of allowed domains
required: Boolean for required field

phone

Phone number validation and formattingValidation Options:

format: “national” or “international”
regions: Array of allowed country codes

number

Numeric input with validationValidation Options:

min: Minimum value
max: Maximum value
integer: Boolean for integer-only

url

URL validationValidation Options:

protocols: Array of allowed protocols (http, https)
domains: Array of allowed domains

date

Date input and validationValidation Options:

format: Date format string
min: Minimum date
max: Maximum date

Field Validation Example

{
  "name": "email",
  "type": "email",
  "required": true,
  "label": "Email Address",
  "validation": {
    "domains": ["company.com", "partner.com"],
    "message": "Please use your company email address"
  }
}

Error Handling

Common Error Responses

400 Bad Request

Cause: Invalid request data or missing required fields

{
  "status": "error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "messageTemplate",
      "message": "Message template is required"
    },
    {
      "field": "fields",
      "message": "At least one field is required"
    }
  ]
}

404 Not Found

Cause: Form with specified ID doesn’t exist

{
  "status": "error",
  "message": "Form not found",
  "code": "FORM_NOT_FOUND"
}

409 Conflict

Cause: Form name already exists

{
  "status": "error",
  "message": "Form name already exists",
  "code": "DUPLICATE_FORM_NAME"
}

Rate Limiting

Forms API endpoints are subject to rate limiting:

Standard Plan: 1,000 requests per hour
Pro Plan: 5,000 requests per hour
Enterprise Plan: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Best Practices

Form Design

Keep Fields Minimal

Only include essential fields to reduce friction

Use Clear Labels

Provide descriptive labels and placeholders

Validate Input

Implement client-side validation before webhook submission

Test Templates

Always test message templates with sample data

Performance

Pagination

Use pagination when retrieving large numbers of forms:

const allForms = [];
let page = 1;
let hasMore = true;

while (hasMore) {
  const response = await fetch(`https://api.goblue.app/v1/forms?page=${page}&limit=50`);
  const data = await response.json();
  
  allForms.push(...data.data.forms);
  hasMore = data.data.forms.length === 50;
  page++;
}

Caching

Cache form configurations to reduce API calls:

class FormCache {
  constructor() {
    this.cache = new Map();
    this.ttl = 5 * 60 * 1000; // 5 minutes
  }
  
  async getForm(formId) {
    const cached = this.cache.get(formId);
    if (cached && Date.now() - cached.timestamp < this.ttl) {
      return cached.data;
    }
    
    const form = await this.fetchForm(formId);
    this.cache.set(formId, {
      data: form,
      timestamp: Date.now()
    });
    
    return form;
  }
}

Next Steps

Webhooks API

Learn how to send data to your forms via webhooks

Messages API

Manage and retrieve generated messages

Form Setup Guide

Step-by-step guide to creating your first form

Message Templating

Advanced techniques for dynamic message templates

Get Started

Core Concepts

Guides

Advanced

API Reference

Overview

Base URL

Authentication

Form Object

Properties

Example Form Object

Endpoints

List All Forms

Get Form by ID

Create Form

Update Form

Delete Form

Get Form Statistics

Field Types and Validation

Supported Field Types

Field Validation Example

Error Handling

Common Error Responses

Rate Limiting

Best Practices

Form Design

Keep Fields Minimal

Use Clear Labels

Validate Input

Test Templates

Performance

Next Steps

Webhooks API

Messages API

Form Setup Guide

Message Templating

Get Started

Core Concepts

Guides

Advanced

API Reference

​Overview

​Base URL

​Authentication

​Form Object

​Properties

​Example Form Object

​Endpoints

​List All Forms

​Get Form by ID

​Create Form

​Update Form

​Delete Form

​Get Form Statistics

​Field Types and Validation

​Supported Field Types

​Field Validation Example

​Error Handling

​Common Error Responses

​Rate Limiting

​Best Practices

​Form Design

Keep Fields Minimal

Use Clear Labels

Validate Input

Test Templates

​Performance

​Next Steps

Webhooks API

Messages API

Form Setup Guide

Message Templating

Overview

Base URL

Authentication

Form Object

Properties

Example Form Object

Endpoints

List All Forms

Get Form by ID

Create Form

Update Form

Delete Form

Get Form Statistics

Field Types and Validation

Supported Field Types

Field Validation Example

Error Handling

Common Error Responses

Rate Limiting

Best Practices

Form Design

Performance

Next Steps