Gravity Connect API Alchemist

Terminology

Before we get started, let’s clarify a few important words we’ll use throughout this documentation.

• GCAPI: An acronym for this plugin, GC API Alchemist.
• GPPA: An acronym for GP Populate Anything.

Lastly, API Alchemist inevitably uses a lot of API terminology. If you’re not familiar with APIs, our API Alchemist-focused API starter guide will be out soon!

How do I enable this functionality?

API Feed Setup

	Navigate to your desired form and click the “API Alchemist” item under the “Settings” menu.
	Click the “Add New” button and give your API Alchemist feed a name.
	Configure the Webhook Settings. You can choose to connect to a direct URL or work with an API Connection.
	Configure the Request Configuration. Different HTTP methods have their own configuration.
	(Optional) Add Custom Headers unique to this feed.
	If you are capturing responses, configure the Response Handling.

Add New API Connection

	On the left side WordPress menu under Forms, select API Connections.
	Click the “Add New API Connection” button and give your API connection a name.
	Configure the Connection Profile Settings. This is the profile for the entire API, meant to hold the base URL, authentication, HTTP headers, and detected endpoints (if a schema is added).

To enable dynamic choice and value population, go to the GP Populate Anything integration.

---

Feature Details

Gravity Forms API Data Interaction

API Alchemist interacts with REST APIs by sending webhook requests via feeds with Gravity Forms data. Requests can be made using common HTTP methods (GET, POST, PUT, PATCH, DELETE) and may also capture data from the API on submission.

Data Capture with Response Handling

When capturing API responses, API Alchemist can either process them immediately after submission or use a pre-generated callback URL that updates the corresponding entry once the API responds.

All feeds are processed asynchronously, except when the Require response to complete submission option is enabled (available for Simple Response Mode).

One-time API Profile Setups

API Connection profiles store core configurations—such as base URL, authentication, headers, and schema—for reuse across multiple API Alchemist feeds. When paired with GP Populate Anything, these profiles can also dynamically populate form fields with API data.

For quick one-off connections, API Alchemist feeds support direct URLs.

Adaptive No-Code Configuration

API Alchemist provides interfaces for API authentication and headers, plus interactive drag-and-drop trees for mapping JSON properties to form fields and GP Populate Anything objects. The UI interprets imported API schemas, showing available endpoints matched to their HTTP methods alongside their available properties and parameters, improving input accuracy and streamlining configuration.

Live Choice and Value Population

API Alchemist can dynamically populate field choices and values with live API data when paired with GP Populate Anything. Real-time sourcing keeps data current, improves accuracy, eliminates redundancy, and reduces database load. Read more.

Feed Settings

API Alchemist feeds configure a webhook that trigger an event on form submission. When configuring API Alchemist feeds, you will be presented with the following settings.

After giving your feed a name, it’s time for the fun stuff.

Webhook Settings

Use the Webhook Settings to configure this feed’s webhook and define:

• Which API endpoint your webhook will be sent to.
• What HTTP method (aka verb) the webhook will use.

These settings change depending on the type of Connection Profile you choose.

Connection Profile

Choose between None (Direct URL) or one of your pre-setup API Connections.

API Connections that had their schema added to API Alchemist have access to the schema-based setup, allowing you to see available endpoints for that API directly in the feed. Direct URLs and API Connections without an added schema go through the manual setup.

Schema-Based Setup

Use the Endpoint Path search bar to find available endpoints. Select which one you want to use for this webhook.

Manual Setup

When a schema isn’t necessary or available, manual setups allow you to enter an endpoint path and select the fitting HTTP method manually.

HTTP Method: Choose the HTTP method (aka verb) for this webhook.

Request Configuration

Configure the HTTP request itself. There are two types of request configurations:

• GET and DELETE: Query parameter configuration.
• POST, PUT, and PATCH: Payload configuration.

GET / DELETE Request Configuration

Define query parameters and values to be appended to the GET or DELETE endpoint URL.

Example: http://api.marketstock.com/v1/eod?symbols=AAPL&sort=desc

Query Parameters (Schema Enabled)

API Alchemist automatically detects all available query parameters for the selected endpoint. For values, you can add Gravity Forms merge tags and/or static values. Parameters with empty values will be ignored.

If the endpoint doesn’t require any parameters, it will show this message instead:

Query Parameters (Manual)

Add custom query parameters to be appended to the endpoint URL. For values, you can add Gravity Forms merge tags and/or static values.

POST / PUT / PATCH Request Configuration

Configure the webhook payload (aka request body) for POST, PUT, or PATCH requests.

Payload Configuration (Schema Enabled)

API Alchemist automatically detects all available query parameters for the selected endpoint and signals if they are required or not. To add values to those parameters, you can use Gravity Forms merge tags and/or static values. Parameters with empty values will be ignored.

If no parameters are detected, it will show this message instead:

Toggle Advanced Mode to write or edit the JSON template directly in code. You can freely toggle between them.

Payload Configuration (Manual)

Request Body Format: Choose how the form data should be formatted in the webhook request body. Available formats are JSON, Form Data, and Raw.

Request Body Content: Choose whether to send all form data automatically pre-formatted or customize the request body.

The JSON and Form Data formats let you map custom query parameters and add Gravity Forms merge tags and/or static values in a field mapping interface.

The Raw format allows for manual input of other data formats such as XML or SOAP.

The Advanced Mode toggle allows you to write and edit the template directly in code.

Custom Headers

Add custom headers specific to this feed and add values to those headers using Gravity Forms merge tags and/or static values. These will be sent in addition to any inherited headers from the Connection Profile.

Response Handling

Response handling lets API Alchemist process API responses and capture JSON data in an entry. The two available modes are processed asynchronously, so form submissions aren’t blocked by default while the request is being handled.

Simple Response Mode

Handle responses immediately after form submission. Perfect for quick REST APIs where it makes sense for your server to wait for the API response.

Require response to complete submission: When enabled, the feed is processed synchronously and form submissions will wait for a response before completing. This ensures the response data is processed before the user sees the confirmation message, enabling API data to be used in it. Invalid API responses will trigger a validation error.

Example Use Cases:

• An order form sends selected products to the Shopify API. Variant SKUs are added to the entry after submission.
• A shipping request form calculates rates via the ShipStation API. The returned shipping cost is included in the confirmation message.

Advanced Response Mode

Handle delayed responses via callback URL. Ideal for complex workflows and long-running processes where your server shouldn’t wait for the API response.

External systems will receive instructions to POST their response to the callback URL. Those instructions will also contain a token for them to include in their callback response, which expires in 24 hours for security.

Example Use Case:

• n8n workflows with AI-powered steps and additional external services.

Response Field Mapping

Map API response data to any form field or entry meta. Use the interactive tree for advanced testing and drag-and-drop mapping. To refresh requests, click the 🔃 icon next to the status code.

API Connection Profiles

An API Connection Profile is where you set up the base URL, required HTTP headers, schema, and authentication details for a specific API. Once created, the profile becomes the root of all requests for an API and can be used to configure multiple feeds that connect to it.

This is also where you can create custom endpoints for GP Populate Anything, allowing Gravity Forms fields to be dynamically populated with API data.

Connection Profile Settings

When configuring API Connection Profiles, you will be presented with the following settings.

Base URL: Enter the base URL for the API. Endpoints and parameters are added through API Alchemist feeds.

Description (Optional): Describe this API Connection profile.

Authentication

API Connection Profiles handle API authentication for those that require it. Use the Authentication Type drop down to select the authentication method for the API, which will display the relevant fields to that method.

API Key Setup Example:

OAuth2 Setup Example:

Headers

API Connection Profiles can have default HTTP headers that are feed-agnostic and will be sent with every request using this connection profile.

Schema Configuration

API Connection Profiles support OpenAPI, Swagger, and WordPress REST API schema imports. This enables endpoint discovery and parameter validation within API Alchemist feeds and Populate Anything custom endpoints.

API Alchemist will automatically detect a schema from common endpoints like /openapi.json or /swagger.json. If it can’t detect a schema, you can manually import it from a URL or paste the JSON directly.

Once a schema is successfully imported, API Alchemist displays a readout.

JSONPath

API Alchemist uses JSONPath for navigating and extracting data from JSON objects in Response Handling and Populate Anything Endpoints.

This query language provides a concise, standardized syntax that lets you drill into nested structures, filter arrays, and retrieve specific values without manually parsing the entire JSON. Whether you need a single property, a slice of an array, or every matching field across different levels, JSONPath helps narrow it down.

JSONPath Examples: Common Operators

• $.customer.id – Simple property access (grabs the id inside customer)
• $.data[0].status – Array element access (first item in data, then its status)
• $.results[*].name – All array items (gets every name from all objects in results)
• $.items[?(@.active)].id – Conditional filtering (only id values from items where active is true)
• $.store.book[1].author – Nested array element (the author of the second book in store)
• $..price – Recursive descent (finds all price fields at any level in the JSON)
• $.orders[*].products[*].name – Deep wildcard (all name fields from every product in every order)
• $.users[?(@.age > 30)].name – Filter with comparison (the name of users where age is greater than 30)
• $.records[-1:] – Slice notation (gets the last element in the records array)
• $.data[0:2] – Array slice (first two elements in data)

JSONPath Examples: Advanced Operators

• $.store.book[0,2].title – Union (selects the title from the first and third book in store)
• $.store.book[0:3:2].title – Slice with step (every second book in the first three)
• $..* – Wildcard with recursive descent (selects all elements at all levels)
• $.users[?(@.role =~ /admin|editor/)].id – Regex filter (gets id of users whose role matches admin or editor)
• $.metrics[?(@.score >= 90 && @.passed == true)] – Multiple conditions (all metrics where score is 90+ and passed is true)
• $.items[?(@.tags[?(@ == "featured")])] – Nested filter (items that have "featured" inside their tags array)
• $['store','warehouse'].location – Multiple keys (selects location from both store and warehouse)

---

Integrations

Populate Anything

GP Populate Anything is deeply integrated with API Alchemist, allowing Gravity Forms to populate fields with data from any API.

The integration starts inside API Connection Profiles. When both API Alchemist and GP Populate Anything are activated, the configuration for Populate Anything Endpoints is unlocked.

Creating a Populate Anything Endpoint

1. Configuration: Name the Populate Anything endpoint and select or enter the API endpoint you’d like to connect to.

   

2. Data & Property Mapping: Test a request and map response properties to create Populate Anything objects. You can navigate through the API sample data via an interactive tree or directly in code. To refresh requests, click the 🔃 icon next to the status code.

   

   API Alchemist will auto-detect and map all properties from sample data. If you want to create only certain GPPA objects, you can use data roots to filter it or drag-and-drop properties via custom property mapping.

   

3. Query Parameters (Filters): Configure which query parameters from the API endpoint should be available as filters in Populate Anything.

   

   These will allow users to dynamically filter the data when populating form fields.

   

4. Cache Settings: This setting controls longer-term persistent caching between page loads. You can choose to enable cache API responses (up to a week) to improve performance and reduce API calls.

   Cache Behavior:

   • Responses are always cached temporarily during form rendering for performance.
   • You can further customize cache behavior using hooks like gcapi_gppa_cache_key and gcapi_gppa_should_cache

Added endpoints are displayed in the Populate Anything Endpoints section, where they can be edited or deleted.

Once you’re done configuring Populate Anything Endpoints, make sure to Update the API Connection Profile.

Submit to Access

GP Submit to Access gates posts, blocks, and shortcodes behind Gravity Forms submissions. When tying API Alchemist into Submit to Access, you can require successful API responses, otherwise the form fails validation.

Developer’s Notes

If you’d like to disable the Populate Anything Endpoints feature highlight, you can do so via the API Connection Screen Options. To use Populate Anything Endpoints later, simply enable it again.

Troubleshooting Issues

Coming soon from our legendary support team.

FAQ

You tell us! What do you want to know?

Translations

You can use the free Loco Translate plugin to create translations for any of our Perks. If you’ve never used Loco translate before, here’s a tutorial written for beginners.

Hooks

• gcapi_callback_token_current_time
  Filter the current time for token generation and validation. This filter allows tests to mock the current time for testing token expiration scenarios.
• gcapi_form_field_choices
  Filter the choices available in the form field dropdown.
• gcapi_gppa_cache_duration
  Filter the cache duration for GPPA endpoint responses.
• gcapi_gppa_cache_key
  Filter the cache key for GPPA endpoint responses.
• gcapi_gppa_should_cache
  Filter whether to use cached GPPA endpoint responses.
• gcapi_http_request
  Filter HTTP request data before sending Allows modification of request URL, method, and options before the HTTP request is sent. This is a low-level filter that applies to all HTTP requests made through the plugin.
• gcapi_http_response
  Filter HTTP response data after receiving Allows modification of response data after the HTTP response is received. This is a low-level filter that applies to all HTTP responses received through the plugin.

---

Related Resources

No related resources found.