### List Forms API Response Example

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

Example JSON response when requesting a list of forms. This includes form details and aggregated metadata.

```json
{
"Forms":[{
"Form":{
"id":"XXXX", "version_id":"XXXX", "name":"XXXXXXXX",
"category":"XXXX", "subcategory":"XXXX", "is_template":"XXXX",
"display_status":"XXXX", "moderation_status":"XXXX", "expired":"XXXX",
"use_ssl":"XXXX", "user_id":"XXXX",
"created":"XXXXXXXX", "modified":"XXXXXXXX",
"Aggregate_metadata":{
"id":"XXXX", "response_count":"XXXX", "submitted_count":"XXXX",
"saved_count":"XXXX", "unread_count":"XXXX", "dropout_rate":"XXXX",
"average_completion_time":"XXXX", "is_uptodate":"XXXX"
}
}
}]
}
```

--------------------------------

### PHP OAuth2 Integration

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Complete PHP implementation demonstrating the OAuth2 authorization flow and API access pattern. This example handles user redirection, token exchange, and API requests.

```PHP
<?php
$CLIENT_ID = "your_client_id";
$CLIENT_SECRET = "your_client_secret";
$RETURN_URL = "https://" . $_SERVER['SERVER_NAME'] . $_SERVER['REQUEST_URI'];
$AUTH_ENDPOINT = "https://app.formassembly.com/oauth/login";
$TOKEN_REQUEST_ENDPOINT = "https://app.formassembly.com/oauth/access_token";
$API_REQUEST = "https://app.formassembly.com/api_v1/forms/index.json";

// Step 1: Redirect user to authorization
if (empty($_GET) && empty($_POST)) {
    $AUTH_URI = "$AUTH_ENDPOINT?type=web&client_id=$CLIENT_ID&redirect_uri=$RETURN_URL&response_type=code";
    header("Location: $AUTH_URI", TRUE, 302);
    exit;
}

// Step 2: Exchange code for token and make API request
if (!empty($_GET['code'])) {
    $CODE = $_GET['code'];

    $TOKEN_REQUEST_DATA = array(
        "grant_type" => "authorization_code",
        "type" => "web_server",
        "client_id" => $CLIENT_ID,
        "client_secret" => $CLIENT_SECRET,
        "redirect_uri" => $RETURN_URL,
        "code" => $CODE
    );

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $TOKEN_REQUEST_ENDPOINT);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $TOKEN_REQUEST_DATA);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    $output = curl_exec($ch);
    curl_close($ch);

    $TOKEN_RESPONSE = json_decode($output);
    $TOKEN = urlencode($TOKEN_RESPONSE->access_token);

    // Make API request
    $FULL_API_REQUEST = "$API_REQUEST?access_token=$TOKEN";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $FULL_API_REQUEST);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    $API_RESPONSE = curl_exec($ch);
    curl_close($ch);

    print_r(json_decode($API_RESPONSE));
}
?>

```

--------------------------------

### Access Token Response Example

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

The JSON response received after successfully requesting an access token. Store the 'access_token' for subsequent API calls.

```json
{
  "access_token":"XXXXXXXXXXXXXX",
  "expires_in":XXXXX,
  "scope":XXXX,
  "refresh_token":"XXXXXXXXXXXX"
}
```

--------------------------------

### GET /api_v1/themes/index

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

Retrieves a list of themes associated with the user account.

```APIDOC
## GET /api_v1/themes/index

### Description
Returns a list of the themes associated with the user account.

### Method
GET

### Endpoint
https://app.formassembly.com/api_v1/themes/index.json
```

--------------------------------

### GET /api_v1/forms/view/#FORMID#

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

Retrieves the definition of a specific form.

```APIDOC
## GET /api_v1/forms/view/#FORMID#

### Description
Returns an encoded copy of the form's definition in XML or JSON.

### Method
GET

### Endpoint
https://app.formassembly.com/api_v1/forms/view/#FORMID#.{format}

### Parameters
#### Path Parameters
- **FORMID** (string) - Required - The ID of the form to retrieve

#### Query Parameters
- **raw** (boolean) - Optional - Bypass form XML element whitelisting
```

--------------------------------

### GET /api_v1/forms/index

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

Retrieves a list of forms associated with the user account.

```APIDOC
## GET /api_v1/forms/index

### Description
Returns a list of the forms in the user's account, along with associated metadata.

### Method
GET

### Endpoint
https://app.formassembly.com/api_v1/forms/index.{format}

### Parameters
#### Query Parameters
- **access_token** (string) - Required - The token received during authentication

### Response
#### Success Response (200)
- **Forms** (array) - A list of form objects

#### Response Example
{
  "Forms": [{
    "Form": {
      "id": "XXXX",
      "name": "XXXXXXXX",
      "created": "XXXXXXXX"
    }
  }]
}
```

--------------------------------

### List Forms API Request

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

A GET request to retrieve a list of forms in the user's account. Replace ACCESS_TOKEN with your obtained token.

```http
https://app.formassembly.com/api_v1/forms/index.json?access_token=ACCESS_TOKEN
```

--------------------------------

### POST /admin/api_v1/themes/create

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

Creates a new theme with the provided CSS data.

```APIDOC
## POST /admin/api_v1/themes/create

### Description
Create a new theme.

### Method
POST

### Endpoint
https://app.formassembly.com/admin/api_v1/themes/create.json

### Parameters
#### Request Body
- **name** (string) - Required - Name of the theme
- **css_data** (string) - Required - CSS payload for the theme
```

--------------------------------

### Create New Form

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Create a new form by providing the required XML data and configuration parameters.

```bash
curl -X POST "https://app.formassembly.com/api_v1/forms/create.json?access_token=YOUR_ACCESS_TOKEN" \
  -d "xml_data=<form>...</form>" \
  -d "builder_version=4.2.0" \
  -d "language=en-US" \
  -d "name=My New Form"

# Supported builder versions: "3.4.2", "4.0.0", "4.0.1", "4.1.0", "4.2.0"
```

--------------------------------

### Create Connector

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Initializes a new connector for a form, requiring an event type parameter.

```bash
curl -X POST "https://app.formassembly.com/admin/api_v1/connectors/create/12345/MyConnector.json?access_token=YOUR_ACCESS_TOKEN" \
  -d "event=background"

# Event types:
# - "beforerender": Before form is displayed to user
# - "before_save": When form is saved by user
# - "interactive": After form is completed
# - "background": After user sees the thank-you page
```

--------------------------------

### List Themes

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieves a list of all themes available to the authenticated user.

```bash
curl -X GET "https://app.formassembly.com/api_v1/themes/index.json?access_token=YOUR_ACCESS_TOKEN"
```

--------------------------------

### View Connector Definition

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieves the configuration and mapping settings for a specific connector.

```bash
curl -X GET "https://app.formassembly.com/admin/api_v1/connectors/view/67890.json?access_token=YOUR_ACCESS_TOKEN"

curl -X GET "https://app.formassembly.com/admin/api_v1/connectors/view/67890.xml?access_token=YOUR_ACCESS_TOKEN"
```

--------------------------------

### Create Theme

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Creates a new theme with custom CSS styling for form appearance.

```APIDOC
## Create Theme

### Description
Creates a new theme with custom CSS styling for form appearance.

### Method
POST

### Endpoint
`/admin/api_v1/themes/create.json`

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your FormAssembly API access token.

#### Request Body
- **name** (string) - Required - The name of the new theme.
- **css_data** (string) - Required - The CSS styling for the theme.

### Request Example
```json
{
  "name": "My Custom Theme",
  "css_data": ".wForm { background-color: #f5f5f5; } .wFormContainer { padding: 20px; }"
}
```

### Response Example
```json
{
  "id": 12345,
  "name": "My Custom Theme",
  "css_data": ".wForm { background-color: #f5f5f5; } .wFormContainer { padding: 20px; }"
}
```
```

--------------------------------

### Create Theme via cURL

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Creates a new theme with custom CSS styling for form appearance.

```bash
curl -X POST "https://app.formassembly.com/admin/api_v1/themes/create.json?access_token=YOUR_ACCESS_TOKEN" \
  -d "name=My Custom Theme" \
  -d "css_data=.wForm { background-color: #f5f5f5; } .wFormContainer { padding: 20px; }"
```

--------------------------------

### Admin List All Forms

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieve all forms across an entire instance. This requires an admin-level access token on Enterprise plans.

```bash
# Get all forms in the instance (admin only)
curl -X GET "https://app.formassembly.com/admin/api_v1/forms/index.json?access_token=ADMIN_ACCESS_TOKEN"

curl -X GET "https://app.formassembly.com/admin/api_v1/forms/index.xml?access_token=ADMIN_ACCESS_TOKEN"
```

--------------------------------

### View Form Definition

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieve the definition of a specific form. Use the raw parameter to bypass whitelisting and return internal fields.

```bash
# Get form definition in JSON
curl -X GET "https://app.formassembly.com/api_v1/forms/view/12345.json?access_token=YOUR_ACCESS_TOKEN"

# Get form definition in XML
curl -X GET "https://app.formassembly.com/api_v1/forms/view/12345.xml?access_token=YOUR_ACCESS_TOKEN"

# Get raw form definition (includes internal fields)
curl -X GET "https://app.formassembly.com/api_v1/forms/view/12345.json?access_token=YOUR_ACCESS_TOKEN&raw=1"
```

--------------------------------

### POST /admin/api_v1/form_elements/create

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

Creates a new form element.

```APIDOC
## POST /admin/api_v1/form_elements/create

### Description
Create a new form element.

### Method
POST

### Endpoint
https://app.formassembly.com/admin/api_v1/form_elements/create.json

### Parameters
#### Request Body
- **xml_data** (string) - Required - XML payload for FormAssembly FormBuilder
- **name** (string) - Required - Name for element
- **comments** (string) - Optional - TBD
- **category** (string) - Optional - System level category
- **subcategory** (string) - Optional - User defined category
- **batch** (int) - Optional - TBD
```

--------------------------------

### View Theme via cURL

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieves a theme's definition in raw CSS format. Note that CSS may contain local URLs requiring environment-specific adjustments.

```bash
curl -X GET "https://app.formassembly.com/admin/api_v1/themes/view/11111.json?access_token=YOUR_ACCESS_TOKEN"
```

--------------------------------

### Request Access Token

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

Execute a POST request from your server to obtain an access token. Ensure all parameters are correctly populated.

```http
POST https://YOUR_FORMASSEMBLY_INSTANCE_URL/oauth/access_token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&type=web_server&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=RETURN_URL&code=CODE
```

--------------------------------

### List Form Connectors

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieves a list of connectors associated with a specific form in JSON or XML format.

```bash
# Get connectors for a form in JSON
curl -X GET "https://app.formassembly.com/api_v1/connectors/index/12345.json?access_token=YOUR_ACCESS_TOKEN"

# Get connectors for a form in XML
curl -X GET "https://app.formassembly.com/api_v1/connectors/index/12345.xml?access_token=YOUR_ACCESS_TOKEN"
```

--------------------------------

### List User Forms

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieve a list of forms associated with the authenticated user account in JSON or XML format.

```bash
# Get all forms in JSON format
curl -X GET "https://app.formassembly.com/api_v1/forms/index.json?access_token=YOUR_ACCESS_TOKEN"

# Get all forms in XML format
curl -X GET "https://app.formassembly.com/api_v1/forms/index.xml?access_token=YOUR_ACCESS_TOKEN"

# Response (JSON):
# {
#   "Forms": [{
#     "Form": {
#       "id": "12345",
#       "version_id": "1",
#       "name": "Contact Form",
#       "category": "Contact Forms",
#       "subcategory": "Sales",
#       "is_template": "0",
#       "display_status": "2",
#       "moderation_status": "0",
#       "expired": null,
#       "use_ssl": "1",
#       "user_id": "100",
#       "created": "2023-01-15 10:30:00",
#       "modified": "2023-06-20 14:45:00",
#       "Aggregate_metadata": {
#         "id": "12345",
#         "response_count": "150",
#         "submitted_count": "142",
#         "saved_count": "8",
#         "unread_count": "5",
#         "dropout_rate": "0.15",
#         "average_completion_time": "180",
#         "is_uptodate": "1"
#       }
#     }
#   }]
# }
```

--------------------------------

### Create Form

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Creates a new form in the user's account. Requires form XML data, builder version, language code, and display name.

```APIDOC
## Create Form

Creates a new form in the user's account. Requires form XML data formatted per FormAssembly's schema, builder version, language code, and display name sent as POST parameters.

### Method
POST

### Endpoint
`/api_v1/forms/create.json`

### Query Parameters
- **access_token** (string) - Required - The OAuth2 access token.

### Request Body Parameters
- **xml_data** (string) - Required - The XML definition of the form.
- **builder_version** (string) - Required - The builder version to use (e.g., "4.2.0"). Supported versions: "3.4.2", "4.0.0", "4.0.1", "4.1.0", "4.2.0".
- **language** (string) - Required - The language code for the form (e.g., "en-US").
- **name** (string) - Required - The display name of the form.

### Request Example
```bash
curl -X POST "https://app.formassembly.com/api_v1/forms/create.json?access_token=YOUR_ACCESS_TOKEN" \
  -d "xml_data=<form>...</form>" \
  -d "builder_version=4.2.0" \
  -d "language=en-US" \
  -d "name=My New Form"
```
```

--------------------------------

### View Theme

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieves a theme's definition in raw CSS format. Note that the CSS may contain links to local URLs that require adjustment for different environments.

```APIDOC
## View Theme

### Description
Retrieves a theme's definition in raw CSS format. Note that the CSS may contain links to local URLs that require adjustment for different environments.

### Method
GET

### Endpoint
`/admin/api_v1/themes/view/{id}.json`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the theme to retrieve.

#### Query Parameters
- **access_token** (string) - Required - Your FormAssembly API access token.

### Response Example
```css
/* CSS content of the theme */
.wForm { background-color: #f5f5f5; }
.wFormContainer { padding: 20px; }
```
```

--------------------------------

### FormAssembly API Base URLs by Edition

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Defines the base URLs for the FormAssembly API across different deployment types. Use the appropriate URL based on whether you are using the Developer Sandbox, FormAssembly.com (cloud), or an Enterprise/Teams/Government self-hosted instance.

```bash
# Developer Sandbox (testing only)
BASE_URL="https://developer.formassembly.com/api_v1/"

# FormAssembly.com (cloud)
BASE_URL="https://app.formassembly.com/api_v1/"

# Enterprise/Teams/Government (self-hosted)
BASE_URL="https://your_instance.tfaforms.net/api_v1/"
```

```bash
# Example requests for each edition
curl -X GET "https://developer.formassembly.com/api_v1/forms/index.json?access_token=TOKEN"
curl -X GET "https://app.formassembly.com/api_v1/forms/index.json?access_token=TOKEN"
curl -X GET "https://mycompany.tfaforms.net/api_v1/forms/index.json?access_token=TOKEN"
```

--------------------------------

### List Connectors

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Returns a list of all connectors associated with a specific form.

```APIDOC
## List Connectors

### Description
Returns a list of all connectors associated with a specific form. Connectors enable automated data processing and integrations with external services.

### Method
GET

### Endpoint
https://app.formassembly.com/api_v1/connectors/index/{form_id}.{format}

### Parameters
#### Path Parameters
- **form_id** (integer) - Required - The ID of the form.
- **format** (string) - Required - The desired output format (e.g., "json", "xml").

#### Query Parameters
- **access_token** (string) - Required - Your FormAssembly API access token.

### Request Example
```bash
# Get connectors for a form in JSON
curl -X GET "https://app.formassembly.com/api_v1/connectors/index/12345.json?access_token=YOUR_ACCESS_TOKEN"

# Get connectors for a form in XML
curl -X GET "https://app.formassembly.com/api_v1/connectors/index/12345.xml?access_token=YOUR_ACCESS_TOKEN"
```
```

--------------------------------

### Access Form File Uploads

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

Use the export zip API call to retrieve a file path, which can then be appended to the instance URL to download the file.

```text
https://app.formassembly.com/api_v1/responses/export/5040999.zip
```

```text
https://app.formassembly.com/uploads/get_zip/a2124d28e77f7b2da80ed12301cfcb17-form_5040999.zip
```

--------------------------------

### Create Connector

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Creates a new connector for a form. The event parameter specifies when the connector runs.

```APIDOC
## Create Connector

### Description
Creates a new connector for a form. The event parameter specifies when the connector runs in the form submission lifecycle.

### Method
POST

### Endpoint
https://app.formassembly.com/admin/api_v1/connectors/create/{form_id}/{connector_name}.{format}

### Parameters
#### Path Parameters
- **form_id** (integer) - Required - The ID of the form.
- **connector_name** (string) - Required - The name of the connector.
- **format** (string) - Required - The desired output format (e.g., "json").

#### Query Parameters
- **access_token** (string) - Required - Your FormAssembly API access token.

#### Request Body
- **event** (string) - Required - The event that triggers the connector (e.g., "background", "before_save", "interactive", "beforerender").

### Request Example
```bash
curl -X POST "https://app.formassembly.com/admin/api_v1/connectors/create/12345/MyConnector.json?access_token=YOUR_ACCESS_TOKEN" \
  -d "event=background"

# Event types:
# - "beforerender": Before form is displayed to user
# - "before_save": When form is saved by user
# - "interactive": After form is completed
# - "background": After user sees the thank-you page
```
```

--------------------------------

### List Form Elements via cURL

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Returns a list of form elements available to the user. This endpoint is subject to change without warning.

```bash
curl -X GET "https://app.formassembly.com/api_v1/form_elements/index.xml?access_token=YOUR_ACCESS_TOKEN"
```

--------------------------------

### Admin List All Forms (Enterprise Only)

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Returns a list of all forms across the entire FormAssembly instance. This endpoint is only accessible with an admin-level user on Enterprise plans.

```APIDOC
## Admin List All Forms (Enterprise Only)

Returns a list of all forms across the entire FormAssembly instance, not just the authenticated user's forms. This endpoint is only accessible with an access token from an admin-level user on Enterprise plans.

### Method
GET

### Endpoint
`/admin/api_v1/forms/index.json`
`/admin/api_v1/forms/index.xml`

### Query Parameters
- **access_token** (string) - Required - The admin OAuth2 access token.
```

--------------------------------

### List Form Elements

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Returns a list of form elements available to the user for building forms. This endpoint is in flux and may change without warning.

```APIDOC
## List Form Elements

### Description
Returns a list of form elements available to the user for building forms. This endpoint is in flux and may change without warning.

### Method
GET

### Endpoint
`/api_v1/form_elements/index.xml`

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your FormAssembly API access token.

### Response Example
```xml
<form_elements>
  <element>
    <id>1</id>
    <name>Text Field</name>
    <type>text</type>
  </element>
  <element>
    <id>2</id>
    <name>Dropdown</name>
    <type>select</type>
  </element>
</form_elements>
```
```

--------------------------------

### Edit Connector

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Updates the mapping, credentials, and configuration of an existing connector.

```bash
curl -X POST "https://app.formassembly.com/admin/api_v1/connectors/edit/67890.json?access_token=YOUR_ACCESS_TOKEN" \
  -d "mapping={...}" \
  -d "login=service_username" \
  -d "password=service_password"
```

--------------------------------

### Edit Theme

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Updates an existing theme's name and CSS styling.

```APIDOC
## Edit Theme

### Description
Updates an existing theme's name and CSS styling.

### Method
POST

### Endpoint
`/admin/api_v1/themes/edit/{id}.json`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the theme to edit.

#### Query Parameters
- **access_token** (string) - Required - Your FormAssembly API access token.

#### Request Body
- **name** (string) - Optional - The updated name for the theme.
- **css_data** (string) - Optional - The updated CSS styling for the theme.

### Request Example
```json
{
  "name": "Updated Theme Name",
  "css_data": ".wForm { background-color: #ffffff; }"
}
```

### Response Example
```json
{
  "id": 11111,
  "name": "Updated Theme Name",
  "css_data": ".wForm { background-color: #ffffff; }"
}
```
```

--------------------------------

### View Form Element via cURL

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieves an XML copy of a form element's definition.

```bash
curl -X GET "https://app.formassembly.com/admin/api_v1/form_elements/view/22222.xml?access_token=YOUR_ACCESS_TOKEN"
```

--------------------------------

### List Forms

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieves a list of all forms in the authenticated user's account. Supports JSON and XML formats.

```APIDOC
## List Forms

Retrieves a list of all forms in the authenticated user's account along with associated metadata including response counts, dropout rates, and completion times. Returns form details such as ID, name, category, creation date, and aggregate statistics.

### Method
GET

### Endpoint
`/api_v1/forms/index.json`
`/api_v1/forms/index.xml`

### Query Parameters
- **access_token** (string) - Required - The OAuth2 access token.

### Response Example (JSON)
{
  "Forms": [{
    "Form": {
      "id": "12345",
      "version_id": "1",
      "name": "Contact Form",
      "category": "Contact Forms",
      "subcategory": "Sales",
      "is_template": "0",
      "display_status": "2",
      "moderation_status": "0",
      "expired": null,
      "use_ssl": "1",
      "user_id": "100",
      "created": "2023-01-15 10:30:00",
      "modified": "2023-06-20 14:45:00",
      "Aggregate_metadata": {
        "id": "12345",
        "response_count": "150",
        "submitted_count": "142",
        "saved_count": "8",
        "unread_count": "5",
        "dropout_rate": "0.15",
        "average_completion_time": "180",
        "is_uptodate": "1"
      }
    }
  }]
}
```

--------------------------------

### Authorize via OAuth2

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Perform the OAuth2 flow by directing the user to the login URL and exchanging the authorization code for an access token.

```bash
# Step 1: Direct user to authorization URL
AUTH_URL="https://app.formassembly.com/oauth/login?type=web&client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&response_type=code"

# Step 2: Exchange authorization code for access token
curl -X POST https://app.formassembly.com/oauth/access_token \
  -d "grant_type=authorization_code" \
  -d "type=web_server" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "code=AUTHORIZATION_CODE"

# Response:
# {
#   "access_token": "XXXXXXXXXXXXXX",
#   "expires_in": 315360000,
#   "scope": null,
#   "refresh_token": "XXXXXXXXXXXX"
# }
```

--------------------------------

### Export Form Responses

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieves form response data with support for various formats, filtering, pagination, and enterprise data unlocking.

```bash
# Export all completed responses as CSV
curl -X GET "https://app.formassembly.com/api_v1/responses/export/12345.csv?access_token=YOUR_ACCESS_TOKEN"

# Export responses in JSON format
curl -X GET "https://app.formassembly.com/api_v1/responses/export/12345.json?access_token=YOUR_ACCESS_TOKEN"

# Export responses in XML format
curl -X GET "https://app.formassembly.com/api_v1/responses/export/12345.xml?access_token=YOUR_ACCESS_TOKEN"

# Export with date range filter (includes incomplete responses)
curl -X GET "https://app.formassembly.com/api_v1/responses/export/12345.csv?access_token=YOUR_ACCESS_TOKEN&date_from=01/01/2023&date_to=12/31/2023&filter=all"

# Export specific response IDs only
curl -X GET "https://app.formassembly.com/api_v1/responses/export/12345.xml?access_token=YOUR_ACCESS_TOKEN&response_ids=10,11,12"

# Export with pagination (page 7, 300 responses per page)
curl -X GET "https://app.formassembly.com/api_v1/responses/export/12345.csv?access_token=YOUR_ACCESS_TOKEN&page=7&page_size=300"

# Export starred responses only
curl -X GET "https://app.formassembly.com/api_v1/responses/export/12345.csv?access_token=YOUR_ACCESS_TOKEN&flag=1"

# Enterprise: Unlock sensitive data fields
curl -X GET "https://app.formassembly.com/api_v1/responses/export/12345.csv?access_token=YOUR_ACCESS_TOKEN&unlock=1"

# Export file uploads as ZIP
curl -X GET "https://app.formassembly.com/api_v1/responses/export/12345.zip?access_token=YOUR_ACCESS_TOKEN"
# Response returns path like: uploads/get_zip/a2124d28e77f7b2da80ed12301cfcb17-form_12345.zip
# Download file: https://app.formassembly.com/uploads/get_zip/a2124d28e77f7b2da80ed12301cfcb17-form_12345.zip
```

--------------------------------

### Edit Theme via cURL

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Updates an existing theme's name and CSS styling.

```bash
curl -X POST "https://app.formassembly.com/admin/api_v1/themes/edit/11111.json?access_token=YOUR_ACCESS_TOKEN" \
  -d "id=11111" \
  -d "name=Updated Theme Name" \
  -d "css_data=.wForm { background-color: #ffffff; }"
```

--------------------------------

### Create Form Element via cURL

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Creates a new reusable form element for the FormBuilder.

```bash
curl -X POST "https://app.formassembly.com/admin/api_v1/form_elements/create.json?access_token=YOUR_ACCESS_TOKEN" \
  -d "xml_data=<element>...</element>" \
  -d "name=Custom Text Field" \
  -d "comments=A custom styled text input" \
  -d "category=" \
  -d "subcategory=Custom Fields" \
  -d "batch="
```

--------------------------------

### PHP OAuth2 Integration

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Complete implementation for the OAuth2 authorization flow, including user redirection, token exchange, and API requests.

```php
<?php
$CLIENT_ID = "your_client_id";
$CLIENT_SECRET = "your_client_secret";
$RETURN_URL = "https://" . $_SERVER['SERVER_NAME'] . $_SERVER['REQUEST_URI'];
$AUTH_ENDPOINT = "https://app.formassembly.com/oauth/login";
$TOKEN_REQUEST_ENDPOINT = "https://app.formassembly.com/oauth/access_token";
$API_REQUEST = "https://app.formassembly.com/api_v1/forms/index.json";

// Step 1: Redirect user to authorization
if (empty($_GET) && empty($_POST)) {
    $AUTH_URI = "$AUTH_ENDPOINT?type=web&client_id=$CLIENT_ID&redirect_uri=$RETURN_URL&response_type=code";
    header("Location: $AUTH_URI", TRUE, 302);
    exit;
}

// Step 2: Exchange code for token and make API request
if (!empty($_GET['code'])) {
    $CODE = $_GET['code'];

    $TOKEN_REQUEST_DATA = array(
        "grant_type" => "authorization_code",
        "type" => "web_server",
        "client_id" => $CLIENT_ID,
        "client_secret" => $CLIENT_SECRET,
        "redirect_uri" => $RETURN_URL,
        "code" => $CODE
    );

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $TOKEN_REQUEST_ENDPOINT);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $TOKEN_REQUEST_DATA);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    $output = curl_exec($ch);
    curl_close($ch);

    $TOKEN_RESPONSE = json_decode($output);
    $TOKEN = urlencode($TOKEN_RESPONSE->access_token);

    // Make API request
    $FULL_API_REQUEST = "$API_REQUEST?access_token=$TOKEN";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $FULL_API_REQUEST);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    $API_RESPONSE = curl_exec($ch);
    curl_close($ch);

    print_r(json_decode($API_RESPONSE));
}
?>
```

--------------------------------

### View Form Definition

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieves an encoded copy of a specific form's definition in XML or JSON format. The `raw` parameter can be used to bypass whitelisting.

```APIDOC
## View Form Definition

Retrieves an encoded copy of a specific form's definition in XML or JSON format. The optional `raw` parameter bypasses form XML element whitelisting to return the exact content stored by FormAssembly.

### Method
GET

### Endpoint
`/api_v1/forms/view/{form_id}.json`
`/api_v1/forms/view/{form_id}.xml`

### Path Parameters
- **form_id** (integer) - Required - The ID of the form to view.

### Query Parameters
- **access_token** (string) - Required - The OAuth2 access token.
- **raw** (integer) - Optional - If set to `1`, returns the raw form definition bypassing whitelisting.
```

--------------------------------

### OAuth2 Authorization

Source: https://context7.com/formassembly/formassembly-api/llms.txt

The FormAssembly API uses OAuth2 for authorization. This section details the steps to obtain an access token.

```APIDOC
## OAuth2 Authorization

The FormAssembly API uses OAuth2 for authorization, requiring applications to obtain user consent before accessing their account data. The authorization flow involves redirecting users to FormAssembly's login page, receiving an authorization code, and exchanging it for an access token that grants API access.

### Step 1: Direct user to authorization URL
`AUTH_URL="https://app.formassembly.com/oauth/login?type=web&client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&response_type=code"`

### Step 2: Exchange authorization code for access token
```bash
curl -X POST https://app.formassembly.com/oauth/access_token \
  -d "grant_type=authorization_code" \
  -d "type=web_server" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "code=AUTHORIZATION_CODE"
```

### Response Example (Access Token)
{
  "access_token": "XXXXXXXXXXXXXX",
  "expires_in": 315360000,
  "scope": null,
  "refresh_token": "XXXXXXXXXXXX"
}
```

--------------------------------

### View Connector

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieves an encoded copy of a specific connector's definition.

```APIDOC
## View Connector

### Description
Retrieves an encoded copy of a specific connector's definition including its configuration and mapping settings.

### Method
GET

### Endpoint
https://app.formassembly.com/admin/api_v1/connectors/view/{connector_id}.{format}

### Parameters
#### Path Parameters
- **connector_id** (integer) - Required - The ID of the connector.
- **format** (string) - Required - The desired output format (e.g., "json", "xml").

#### Query Parameters
- **access_token** (string) - Required - Your FormAssembly API access token.

### Request Example
```bash
curl -X GET "https://app.formassembly.com/admin/api_v1/connectors/view/67890.json?access_token=YOUR_ACCESS_TOKEN"

curl -X GET "https://app.formassembly.com/admin/api_v1/connectors/view/67890.xml?access_token=YOUR_ACCESS_TOKEN"
```
```

--------------------------------

### View Form Element

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Retrieves an XML copy of a form element's definition.

```APIDOC
## View Form Element

### Description
Retrieves an XML copy of a form element's definition.

### Method
GET

### Endpoint
`/admin/api_v1/form_elements/view/{id}.xml`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the form element to retrieve.

#### Query Parameters
- **access_token** (string) - Required - Your FormAssembly API access token.

### Response Example
```xml
<element>
  <id>22222</id>
  <name>Custom Text Field</name>
  <xml_data>...</xml_data>
  <comments>A custom styled text input</comments>
  <category></category>
  <subcategory>Custom Fields</subcategory>
  <batch></batch>
</element>
```
```

--------------------------------

### Create Form Element

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Creates a new reusable form element for the FormBuilder.

```APIDOC
## Create Form Element

### Description
Creates a new reusable form element for the FormBuilder.

### Method
POST

### Endpoint
`/admin/api_v1/form_elements/create.json`

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your FormAssembly API access token.

#### Request Body
- **xml_data** (string) - Required - The XML definition of the form element.
- **name** (string) - Required - The name of the form element.
- **comments** (string) - Optional - Comments about the form element.
- **category** (string) - Optional - The category of the form element.
- **subcategory** (string) - Optional - The subcategory of the form element.
- **batch** (string) - Optional - The batch identifier for the form element.

### Request Example
```json
{
  "xml_data": "<element>...</element>",
  "name": "Custom Text Field",
  "comments": "A custom styled text input",
  "category": "",
  "subcategory": "Custom Fields",
  "batch": ""
}
```

### Response Example
```json
{
  "id": 33333,
  "name": "Custom Text Field",
  "xml_data": "<element>...</element>",
  "comments": "A custom styled text input",
  "category": "",
  "subcategory": "Custom Fields",
  "batch": ""
}
```
```

--------------------------------

### Edit Connector

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Updates an existing connector's mapping, login credentials, and configuration settings.

```APIDOC
## Edit Connector

### Description
Updates an existing connector's mapping, login credentials, and configuration settings.

### Method
POST

### Endpoint
https://app.formassembly.com/admin/api_v1/connectors/edit/{connector_id}.{format}

### Parameters
#### Path Parameters
- **connector_id** (integer) - Required - The ID of the connector to edit.
- **format** (string) - Required - The desired output format (e.g., "json").

#### Query Parameters
- **access_token** (string) - Required - Your FormAssembly API access token.

#### Request Body
- **mapping** (object) - Optional - The updated mapping configuration.
- **login** (string) - Optional - The updated service username for the connector.
- **password** (string) - Optional - The updated service password for the connector.

### Request Example
```bash
curl -X POST "https://app.formassembly.com/admin/api_v1/connectors/edit/67890.json?access_token=YOUR_ACCESS_TOKEN" \
  -d "mapping={...}" \
  -d "login=service_username" \
  -d "password=service_password"
```
```

--------------------------------

### POST /oauth/access_token

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

Exchanges an authorization code for an access token to authenticate API requests.

```APIDOC
## POST /oauth/access_token

### Description
Requests an access token from the server using an authorization code.

### Method
POST

### Endpoint
https://YOUR_FORMASSEMBLY_INSTANCE_URL/oauth/access_token

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be 'authorization_code'
- **type** (string) - Required - Must be 'web_server'
- **client_id** (string) - Required - Unique client application ID
- **client_secret** (string) - Required - Unique client application secret
- **redirect_uri** (string) - Required - The return URL used in the authorization step
- **code** (string) - Required - The authorization code obtained from the user

### Response
#### Success Response (200)
- **access_token** (string) - The token used for API requests
- **expires_in** (integer) - Token expiration time
- **scope** (string) - Token scope
- **refresh_token** (string) - Token used to obtain a renewed access token

#### Response Example
{
  "access_token": "XXXXXXXXXXXXXX",
  "expires_in": 3600,
  "scope": "read",
  "refresh_token": "XXXXXXXXXXXX"
}
```

--------------------------------

### Form Management API

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

Endpoints for creating, editing, and deleting forms in FormAssembly.

```APIDOC
## POST /api/v1/forms/create

### Description
Create a new form.

### Method
POST

### Endpoint
https://app.formassembly.com/api_v1/forms/create.json
https://app.formassembly.com/api_v1/forms/create.xml

### Parameters
#### Request Body
- **xml_data** (string) - Required - XML data formatted per FormAssembly's schema.
- **builder_version** (string) - Optional - String identifier for the builder version (e.g., "3.4.2").
- **language** (string) - Optional - ISO language code (e.g., "en-US").
- **name** (string) - Optional - Internal display name for the form.

### Response
#### Success Response (200)
- **id** (integer) - The ID of the newly created form.

## POST /api/v1/forms/edit/#FORMID#

### Description
Send an update to an existing form.

### Method
POST

### Endpoint
https://app.formassembly.com/api_v1/forms/edit/#FORMID#.json
https://app.formassembly.com/api_v1/forms/edit/#FORMID#.xml

### Parameters
#### Path Parameters
- **FORMID** (integer) - Required - The ID of the form to edit.

#### Request Body
- **id** (integer) - Required - The ID of the existing form.
- **xml_data** (string) - Required - XML data formatted per FormAssembly's schema.
- **builder_version** (string) - Optional - String identifier for the builder version (e.g., "3.4.2").
- **language** (string) - Optional - ISO language code (e.g., "en-US").
- **name** (string) - Optional - Internal display name for the form.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the update was successful.

## POST /api/v1/forms/delete/#FORMID#

### Description
Delete a form.

### Method
POST

### Endpoint
https://app.formassembly.com/api_v1/forms/delete/#FORMID#.json
https://app.formassembly.com/api_v1/forms/delete/#FORMID#.xml

### Parameters
#### Path Parameters
- **FORMID** (integer) - Required - The ID of the form to delete.

#### Request Body
- **id** (integer) - Required - The ID of the existing form to delete.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the deletion was successful.
```

--------------------------------

### Delete Theme via cURL

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Removes a theme from the user's account.

```bash
curl -X POST "https://app.formassembly.com/admin/api_v1/themes/delete/11111.json?access_token=YOUR_ACCESS_TOKEN"
```

--------------------------------

### Edit Form Definition

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Updates an existing form's definition using POST parameters for XML data and metadata.

```bash
curl -X POST "https://app.formassembly.com/api_v1/forms/edit/12345.json?access_token=YOUR_ACCESS_TOKEN" \
  -d "id=12345" \
  -d "xml_data=<form>...</form>" \
  -d "builder_version=4.2.0" \
  -d "language=en-US" \
  -d "name=Updated Form Name"
```

--------------------------------

### Delete Theme

Source: https://context7.com/formassembly/formassembly-api/llms.txt

Removes a theme from the user's account.

```APIDOC
## Delete Theme

### Description
Removes a theme from the user's account.

### Method
POST

### Endpoint
`/admin/api_v1/themes/delete/{id}.json`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the theme to delete.

#### Query Parameters
- **access_token** (string) - Required - Your FormAssembly API access token.

### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Connectors API

Source: https://github.com/formassembly/formassembly-api/blob/main/README.md

Endpoints for managing connectors associated with forms.

```APIDOC
## GET /api/v1/connectors/index/#FORMID#

### Description
Returns a list of connectors associated with a specific form.

### Method
GET

### Endpoint
https://app.formassembly.com/api_v1/connectors/index/#FORMID#.json
https://app.formassembly.com/api_v1/connectors/index/#FORMID#.xml

### Parameters
#### Path Parameters
- **FORMID** (integer) - Required - The ID of the form.

### Response
#### Success Response (200)
- A list of connectors associated with the form.

## GET /admin/api_v1/connectors/view/#CONNECTORID#

### Description
Returns an encoded copy of a connector's definition.

### Method
GET

### Endpoint
https://app.formassembly.com/admin/api_v1/connectors/view/#CONNECTORID#.json
https://app.formassembly.com/admin/api_v1/connectors/view/#CONNECTORID#.xml

### Parameters
#### Path Parameters
- **CONNECTORID** (integer) - Required - The ID of the connector.

### Response
#### Success Response (200)
- An XML or JSON representation of the connector's definition.

## POST /admin/api_v1/connectors/create/#FORMID#/#CONNECTORNAME#

### Description
Create a new connector for a form.

### Method
POST

### Endpoint
https://app.formassembly.com/admin/api_v1/connectors/create/#FORMID#/#CONNECTORNAME#.json
https://app.formassembly.com/admin/api_v1/connectors/create/#FORMID#/#CONNECTORNAME#.xml

### Parameters
#### Path Parameters
- **FORMID** (integer) - Required - The ID of the form.
- **CONNECTORNAME** (string) - Required - The name of the connector.

#### Request Body
- **event** (string) - Required - The stage at which the connector runs (e.g., "beforerender", "before_save", "interactive", "background").

### Response
#### Success Response (200)
- **id** (integer) - The ID of the newly created connector.

## POST /admin/api_v1/connectors/edit/#CONNECTORID#

### Description
Edit an existing connector.

### Method
POST

### Endpoint
https://app.formassembly.com/admin/api_v1/connectors/edit/#CONNECTORID#.json
https://app.formassembly.com/admin/api_v1/connectors/edit/#CONNECTORID#.xml

### Parameters
#### Path Parameters
- **CONNECTORID** (integer) - Required - The ID of the connector to edit.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the edit was successful.
```