Form details

Shows details of a form

Forms belong to a site and can be associated with:

• Landing pages
• Offers
• Email sequences
• Events
• Newsletters

Form Attributes

• title (string) - A required field that represents the name or heading of the form. This is used to identify and display the form in the user interface. Forms must have a unique title within a site and can be searched and sorted by this attribute.
• default (boolean) - A boolean flag indicating whether this is the default form for the site. Each site can have one default form, which is typically used when no specific form is specified. The default form can be accessed using the special ID “default” in API calls. When true, this form is considered the site’s primary contact form.
• webhook_url (string) - An optional URL where form submission data will be sent via webhook. This allows integration with external systems. The URL:
  • Must be a valid URL format
  • Cannot be a redirecting URL
  • Is automatically transformed and validated
  • Can be used to send form submission data to external services
• created_at (string) - Timestamp indicating when the form was created. This is automatically set when the form is first created.
• updated_at (string) - Timestamp indicating when the form was last modified. This is automatically updated whenever the form is changed.

Include Related Resources

Use the include parameter to load related resources:

Include fields, offer, contact_tags

• GET /v1/forms/123?include=fields,offer,contact_tags

Response will include the requested related resources

{
  "data": {
    "id": "123",
    "type": "forms",
    "attributes": {
      "title": "Contact Form",
      "default": false,
      "webhook_url": null,
      "created_at": "2025-02-27T01:03:09.179Z",
      "updated_at": "2025-02-27T01:03:25.365Z"
    },
    "relationships": {
      "fields": {
        "data": [
          { "id": "456", "type": "fields" },
          { "id": "789", "type": "fields" }
        ]
      },
      "offer": {
        "data": { "id": "123", "type": "offers" }
      },
      "contact_tags": {
        "data": [
          { "id": "456", "type": "contact_tags" },
          { "id": "789", "type": "contact_tags" }
        ]
      }
    }
  },
  "included": [
    {
      "id": "456",
      "type": "fields", "attributes": { "name": "Name" }
    },
    {
      "id": "789",
      "type": "fields", "attributes": { "name": "Email" }
    },
    {
      "id": "123",
      "type": "offers", "attributes": { "name": "Offer A" }
    },
    {
      "id": "456",
      "type": "contact_tags", "attributes": { "name": "Tag A" }
    },
    {
      "id": "789",
      "type": "contact_tags", "attributes": { "name": "Tag B" }
    }
  ]
}

Field Attributes

Fields are used in:

• Contact forms
• Offer forms
• Custom field sets
• Form submissions

The system maintains default fields like name, email, etc. that cannot be removed

• title (string) - The display name or label of the field. This is a required attribute that represents how the field will be shown to users in forms and interfaces. Aside from default fields, custom fields can have user-defined titles.
• type (string) - The type of field, which must be one of these predefined types:
  • TextField - Standard text input
  • PhoneField - Phone number input
  • EmailField - Email address input
  • TextAreaField - Multi-line text input
  • CheckboxField - Boolean checkbox
  • SelectBoxField - Dropdown select
  • RadioButtonsField - Radio button group
  • CountryField - Country selector
  • MobilePhoneField - Mobile phone input
• required (boolean) - A boolean indicating whether the field must be filled out. For default fields, this is set in the configuration, while custom fields can be marked as required or optional.
• handle (string) - A unique identifier for the field within a site.
  • A custom handle in the format custom_N where N is a number from 1 to 150
  • The handle is used to reference the field in code and templates.
• select_options (string) - For fields that have choices (SelectBoxField, RadioButtonsField), this contains the available options. The options are stored as newline-separated values and must be unique within the field.
• editable (boolean) - A boolean indicating whether the field can be modified. Default fields typically have this set to false, while custom fields can be editable.
• created_at (string) - Timestamp when the field was created.
• updated_at (string) - Timestamp when the field was last updated.

Sparse Fields

Use the fields[forms] parameter to request only specific attributes:

Only return title and webhook_url attributes

• GET /v1/forms/123?fields[forms]=title,webhook_url

Response will only include requested fields

{
  "data": [{
    "id": "123",
    "type": "forms",
    "attributes": {
      "title": "Contact Form A",
      "webhook_url": "https://example.com/webhook"
    }
  }]
}

Using Multiple Parameters Together

You can combine include and sparse fields in a single request:

Include fields (only name attribute) and only return title and webhook_url attributes

• GET /v1/forms/123?include=fields&fields[forms]=title,webhook_url&&fields[fields]=title

Response will include related fields with sparse fields

{
  "data": {
    "id": "123",
    "type": "forms",
    "attributes": {
      "title": "Contact Form A",
      "webhook_url": "https://example.com/webhook"
    },
    "relationships": {}
  },
  "included": [
    {
      "id": "456",
      "type": "fields",
      "attributes": {
        "title": "Name"
      }
    },
    {
      "id": "789",
      "type": "fields",
      "attributes": {
        "title": "Email"
      }
    }
  ]
}