Forms Builder Guide

This guide covers how to work with forms in GxP, including retrieving form definitions and managing form responses.

Overview

GxP's form builder enables you to:

• Create custom registration and survey forms
• Collect responses from attendees
• Configure conditional logic
• Export and analyze form data

Form Structure

A form consists of:

• Sections: Logical groupings of fields
• Fields: Individual input elements
• Conditional Logic: Rules for showing/hiding fields

Form Types

Type	Description
registration	Attendee registration forms
survey	Post-event surveys
feedback	Session feedback forms
custom	General-purpose forms

Listing Forms

Get all forms for a project:

curl -X GET "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/forms" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "id": 1,
      "name": "Registration Form",
      "slug": "registration-form",
      "type": "registration",
      "is_active": true,
      "created_at": "2024-01-10T09:00:00Z"
    }
  ]
}

Getting Form Details

Retrieve a form with its fields:

curl -X GET "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/forms/{formId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response with Fields

{
  "data": {
    "id": 1,
    "name": "Registration Form",
    "slug": "registration-form",
    "sections": [
      {
        "id": 1,
        "name": "Personal Information",
        "order": 1,
        "fields": [
          {
            "id": 1,
            "label": "First Name",
            "slug": "first_name",
            "type": "text",
            "required": true,
            "order": 1
          },
          {
            "id": 2,
            "label": "Email",
            "slug": "email",
            "type": "email",
            "required": true,
            "order": 2
          }
        ]
      }
    ]
  }
}

Field Types

Type	Description	Example
text	Single-line text	Name, title
textarea	Multi-line text	Comments
email	Email input	Contact email
select	Dropdown selection	Country
radio	Radio buttons	Yes/No
checkbox	Checkboxes	Multi-select
date	Date picker	Birth date
datetime	Date and time	Arrival time
file	File upload	Resume, photo
number	Numeric input	Age, quantity

Form Responses

List Responses

Get all responses for a form:

curl -X GET "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/forms/{formId}/responses" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "id": 1,
      "form_id": 1,
      "attendee_id": 12345,
      "values": {
        "first_name": "Jane",
        "email": "jane@example.com",
        "dietary_requirements": ["vegetarian"]
      },
      "submitted_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Submit Response

Create a new form response:

curl -X POST "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/forms/{formId}/responses" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "attendee_id": 12345,
    "values": {
      "first_name": "Jane",
      "email": "jane@example.com",
      "dietary_requirements": ["vegetarian"]
    }
  }'

Update Response

Modify an existing response:

curl -X PUT "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/forms/{formId}/responses/{responseId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "dietary_requirements": ["vegetarian", "gluten-free"]
    }
  }'

Delete Response

Remove a response:

curl -X DELETE "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/forms/{formId}/responses/{responseId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Searching Responses

Search responses with filters:

curl -X POST "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/forms/{formId}/responses/search" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {
        "field": "values.dietary_requirements",
        "operator": "contains",
        "value": "vegetarian"
      }
    ],
    "sort": [
      {"field": "submitted_at", "direction": "desc"}
    ]
  }'

User-Scoped Responses

For authenticated attendees to manage their own responses:

List My Responses

curl -X GET "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/my-responses/{formSlug}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Update My Response

curl -X PUT "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/my-responses/{formSlug}/{responseId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "session_preference": "workshop-a"
    }
  }'

Exporting Responses

Export all responses for a form:

curl -X POST "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/my-responses/{formSlug}/export" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv"
  }'

Form Fields API

List Form Fields

curl -X GET "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/forms/{formId}/fields" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Field Properties

Property	Type	Description
label	string	Display label
slug	string	Unique identifier
type	string	Field type
required	boolean	Is field required
options	array	Options for select/radio/checkbox
default_value	mixed	Pre-filled value
validation_rules	object	Custom validation
condition_params	object	Conditional display rules

Conditional Logic

Fields can be conditionally shown based on other field values:

{
  "condition_params": {
    "rules": [
      {
        "field": "has_dietary_requirements",
        "operator": "equals",
        "value": "yes"
      }
    ],
    "action": "show"
  }
}

Condition Operators

Operator	Description
equals	Field value equals target
not_equals	Field value does not equal target
contains	Field value contains target
is_empty	Field has no value
is_not_empty	Field has a value

Best Practices

1. Use meaningful slugs: Field slugs should be descriptive and consistent
2. Validate client-side: Implement client validation to improve UX
3. Handle file uploads: Use appropriate file size and type restrictions
4. Test conditional logic: Verify all conditional rules work as expected
5. Export regularly: Back up form responses periodically