FG API

Appearance

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)

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 ​

Newsletter Signup Field ​

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"
}