Fields API Reference

This reference covers field management and configuration in the FG API platform.

Field Types

Data Types

Fields support the following data types:

String

Description: Text data
Use cases: Names, emails, messages, descriptions
Example values: "John Doe", "user@example.com", "Hello world"

Number

Description: Numeric data
Use cases: Ages, prices, quantities, ratings
Example values: 25, 99.99, 1000

Boolean

Description: True/false values
Use cases: Yes/no questions, checkboxes, flags
Example values: true, false

Array

Description: Lists of items
Use cases: Multiple selections, tags, categories
Example values: ["tag1", "tag2"], [1, 2, 3]

Object

Description: Complex data structures
Use cases: Nested information, structured data
Example values: {"name": "John", "age": 25}

Field Types

Fields support the following presentation types:

Text

Description: Single-line text input
Data types: string, number
Use cases: Names, emails, single values

Single Select

Description: Dropdown with one selection
Data types: string
Use cases: Categories, ratings, single choices
Configuration: Requires options list

Multi Select

Description: Dropdown with multiple selections
Data types: array
Use cases: Tags, multiple interests, checkboxes
Configuration: Requires options list

Date

Description: Date picker
Data types: string
Use cases: Birthdays, event dates, deadlines
Format: ISO 8601 date format (YYYY-MM-DD)

Date & time (`date_time`)

Description: Single instant as a string (for direct JSON / integrations that send full timestamps).
Data types: string
Use cases: Exact submission time, scheduled slot with time
Format: ISO 8601 instant with time and UTC offset or Z, e.g. 2026-05-12T14:30:00.000Z or 2026-05-12T14:30:00+00:00. Plain YYYY-MM-DD alone is not valid for this type (use Date above).

Object

Description: Complex nested data
Data types: object
Use cases: Addresses, complex forms, structured data

Field Configuration

Field Properties

Each field has the following configurable properties:

Field Name

Type: string
Required: Yes
Description: The parameter name used in API requests
Format: lowercase with underscores
Examples: first_name, email_address, phone_number

Data Type

Type: enum
Required: Yes
Options: string, number, boolean, array, object
Description: The type of data this field accepts

Field Type

Type: enum
Required: Yes
Options: text, single_select, multi_select, date, object
Description: How the field is presented and validated

Required

Type: boolean
Required: No
Default: false
Description: Whether this field must be provided in API requests

Active

Type: boolean
Required: No
Default: true
Description: Whether this field is enabled and accepts data

Field Management API

Get Fields

Get all fields for a specific endpoint.

Endpoint: GET /api/fields?endpointId={endpointId}

Query Parameters:

endpointId (string, required): The endpoint ID

Headers:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Response:

json

{
  "data": [
    {
      "id": "field123",
      "endpoint": "cmf1234567890",
      "field_name": "name",
      "data_type": "string",
      "field_type": "text",
      "required": true,
      "active": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Create Field

Add a new field to an endpoint.

Endpoint: POST /api/fields

Headers:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Request Body:

json

{
  "endpoint": "cmf1234567890",
  "field_name": "email",
  "data_type": "string",
  "field_type": "text",
  "required": true
}

Response:

json

{
  "data": {
    "id": "field456",
    "endpoint": "cmf1234567890",
    "field_name": "email",
    "data_type": "string",
    "field_type": "text",
    "required": true,
    "active": true,
    "created_at": "2024-01-15T11:00:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}

Update Field

Update an existing field configuration.

Endpoint: PUT /api/fields/{fieldId}

Parameters:

fieldId (string, required): The field ID

Headers:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Request Body:

json

{
  "field_name": "user_email",
  "data_type": "string",
  "field_type": "text",
  "required": false,
  "active": true
}

Response:

json

{
  "data": {
    "id": "field456",
    "endpoint": "cmf1234567890",
    "field_name": "user_email",
    "data_type": "string",
    "field_type": "text",
    "required": false,
    "active": true,
    "created_at": "2024-01-15T11:00:00Z",
    "updated_at": "2024-01-15T11:30:00Z"
  }
}

Field Examples

Text Fields

Name Field

json

{
  "field_name": "name",
  "data_type": "string",
  "field_type": "text",
  "required": true,
  "active": true
}

API Usage:

json

{
  "name": "John Doe"
}

Age Field

json

{
  "field_name": "age",
  "data_type": "number",
  "field_type": "text",
  "required": true,
  "active": true
}

API Usage:

json

{
  "age": 25
}

Select Fields

Category Field (Single Select)

json

{
  "field_name": "category",
  "data_type": "string",
  "field_type": "single_select",
  "required": true,
  "active": true
}

API Usage:

json

{
  "category": "Support"
}

Interests Field (Multi Select)

json

{
  "field_name": "interests",
  "data_type": "array",
  "field_type": "multi_select",
  "required": false,
  "active": true
}

API Usage:

json

{
  "interests": ["Technology", "Design", "Marketing"]
}

Date Fields

Event Date Field

json

{
  "field_name": "event_date",
  "data_type": "string",
  "field_type": "date",
  "required": true,
  "active": true
}

API Usage:

json

{
  "event_date": "2024-12-25"
}

Boolean Fields

json

{
  "field_name": "newsletter_signup",
  "data_type": "boolean",
  "field_type": "text",
  "required": false,
  "active": true
}

API Usage:

json

{
  "newsletter_signup": true
}

Field Validation

Built-in Validation

Required Fields

Fields marked as required: true must be provided in API requests
Missing required fields return a 400 Bad Request error

Data Type Validation

String fields accept text data
Number fields accept numeric data
Boolean fields accept true/false values
Array fields accept lists of items
Object fields accept structured data

Field Type Validation

Text fields accept single values
Select fields validate against predefined options
Date fields validate ISO 8601 date format

Validation Errors

Missing Required Field

json

{
  "error": "validation failed",
  "details": "Field 'name' is required"
}

Invalid Data Type

json

{
  "error": "validation failed",
  "details": "Field 'age' must be a number"
}

Invalid Field Type

json

{
  "error": "validation failed",
  "details": "Field 'category' must be one of: General, Support, Sales"
}

Best Practices

Field Naming

Good Examples

✅ first_name
✅ email_address
✅ phone_number
✅ user_message
✅ event_date

Bad Examples

❌ firstName (use underscores)
❌ email (too generic)
❌ phone# (special characters)
❌ msg (abbreviations)
❌ date (too generic)

Data Type Selection

Choose Appropriate Types

✅ Use "string" for names, emails, messages
✅ Use "number" for ages, prices, quantities
✅ Use "boolean" for yes/no questions
✅ Use "array" for multiple selections
✅ Use "object" for complex data

Avoid Common Mistakes

❌ Don't use "string" for phone numbers that need formatting
❌ Don't use "number" for IDs that start with zeros
❌ Don't use "boolean" for multi-state values

Field Configuration

Required Fields

✅ Only mark essential fields as required
✅ Consider user experience when setting requirements
✅ Provide clear error messages for missing fields

Field Organization

✅ Group related fields together
✅ Use logical field ordering
✅ Keep field names consistent across endpoints

Common Field Configurations

Contact Form Fields

json

[
  {
    "field_name": "name",
    "data_type": "string",
    "field_type": "text",
    "required": true,
    "active": true
  },
  {
    "field_name": "email",
    "data_type": "string",
    "field_type": "text",
    "required": true,
    "active": true
  },
  {
    "field_name": "subject",
    "data_type": "string",
    "field_type": "single_select",
    "required": true,
    "active": true
  },
  {
    "field_name": "message",
    "data_type": "string",
    "field_type": "text",
    "required": true,
    "active": true
  }
]

User Registration Fields

json

[
  {
    "field_name": "first_name",
    "data_type": "string",
    "field_type": "text",
    "required": true,
    "active": true
  },
  {
    "field_name": "last_name",
    "data_type": "string",
    "field_type": "text",
    "required": true,
    "active": true
  },
  {
    "field_name": "email",
    "data_type": "string",
    "field_type": "text",
    "required": true,
    "active": true
  },
  {
    "field_name": "phone",
    "data_type": "string",
    "field_type": "text",
    "required": false,
    "active": true
  },
  {
    "field_name": "newsletter_signup",
    "data_type": "boolean",
    "field_type": "text",
    "required": false,
    "active": true
  }
]

Product Feedback Fields

json

[
  {
    "field_name": "product_id",
    "data_type": "string",
    "field_type": "text",
    "required": true,
    "active": true
  },
  {
    "field_name": "rating",
    "data_type": "string",
    "field_type": "single_select",
    "required": true,
    "active": true
  },
  {
    "field_name": "review",
    "data_type": "string",
    "field_type": "text",
    "required": false,
    "active": true
  },
  {
    "field_name": "recommend",
    "data_type": "boolean",
    "field_type": "text",
    "required": true,
    "active": true
  }
]

Troubleshooting

Common Issues

Field Not Accepting Data

Check if field is marked as "Active"
Verify field name matches API request
Ensure data type matches field configuration

Validation Errors

Check required field settings
Verify data format matches field type
Review field configuration for errors

Field Not Appearing

Check if field is marked as "Active"
Verify field is associated with correct endpoint
Check field configuration for errors

Error Messages

Field Not Found

json

{
  "error": "Field not found"
}

Invalid Field Configuration

json

{
  "error": "Invalid field configuration",
  "details": "Field type 'text' not compatible with data type 'array'"
}

Field Already Exists

json

{
  "error": "Field already exists",
  "details": "A field with name 'email' already exists for this endpoint"
}

Fields API Reference ​

Field Types ​

Data Types ​

String ​

Number ​

Boolean ​

Array ​

Object ​

Field Types ​

Text ​

Single Select ​

Multi Select ​

Date ​

Date & time (date_time) ​

Object ​

Field Configuration ​

Field Properties ​

Field Name ​

Data Type ​

Field Type ​

Required ​

Active ​

Field Management API ​

Get Fields ​

Create Field ​

Update Field ​

Field Examples ​

Text Fields ​

Name Field ​

Age Field ​

Select Fields ​

Category Field (Single Select) ​

Interests Field (Multi Select) ​

Date Fields ​

Event Date Field ​

Boolean Fields ​

Newsletter Signup Field ​

Field Validation ​

Built-in Validation ​

Required Fields ​

Data Type Validation ​

Field Type Validation ​

Validation Errors ​

Missing Required Field ​

Invalid Data Type ​

Invalid Field Type ​

Best Practices ​

Field Naming ​

Good Examples ​

Bad Examples ​

Data Type Selection ​

Choose Appropriate Types ​

Avoid Common Mistakes ​

Field Configuration ​

Required Fields ​

Field Organization ​

Common Field Configurations ​

Contact Form Fields ​

User Registration Fields ​

Product Feedback Fields ​

Troubleshooting ​

Common Issues ​

Field Not Accepting Data ​

Validation Errors ​

Field Not Appearing ​

Error Messages ​

Field Not Found ​

Invalid Field Configuration ​

Field Already Exists ​

Fields API Reference

Field Types

Data Types

String

Number

Boolean

Array

Object

Field Types

Text

Single Select

Multi Select

Date

Date & time (`date_time`)

Object

Field Configuration

Field Properties

Field Name

Data Type

Field Type

Required

Active

Field Management API

Get Fields

Create Field

Update Field

Field Examples

Text Fields

Name Field

Age Field

Select Fields

Category Field (Single Select)

Interests Field (Multi Select)

Date Fields

Event Date Field

Boolean Fields

Newsletter Signup Field

Field Validation

Built-in Validation

Required Fields

Data Type Validation

Field Type Validation

Validation Errors

Missing Required Field

Invalid Data Type

Invalid Field Type

Best Practices

Field Naming

Good Examples

Bad Examples

Data Type Selection

Choose Appropriate Types

Avoid Common Mistakes

Field Configuration

Required Fields

Field Organization

Common Field Configurations

Contact Form Fields

User Registration Fields

Product Feedback Fields

Troubleshooting

Common Issues

Field Not Accepting Data

Validation Errors

Field Not Appearing

Error Messages

Field Not Found

Invalid Field Configuration

Field Already Exists