Skip to main content

​
Overview

API-powered dropdown fields retrieve their selection options from external APIs at runtime, rather than from a static list of values maintained within Elementum. This enables use cases where dropdown options need to reflect data from third-party systems such as ERPs, CRMs, or custom internal services. There are two approaches to API-powered dropdowns in Elementum:
ApproachDescriptionBest For
API PicklistA dropdown field configured to call an external HTTP endpoint directlySimple integrations where dropdown values come from a single API call
Dynamic Dropdown on API ElementsA dynamic dropdown linked to an API Element that fetches data through configured API RequestsComplex integrations where the external data source is modeled as an Element with multiple fields and relationships

​
Prerequisites

Before configuring API-powered dropdown fields, ensure the following:
  • Admin access to the app where you want to add the field
  • API endpoint details for the external system:
    • Endpoint URL
    • HTTP method (GET, POST, or PUT)
    • Authentication credentials (if required)
    • Response format (JSON)
  • Cloud credentials configured (for API Elements approach)

​
Approach 1: API Picklist Fields

An API Picklist field calls an external HTTP endpoint and maps the response data to dropdown options. Each time a user opens the dropdown, Elementum fetches the latest values from the API.

​
Step 1: Add a Dropdown Field to Your Layout

  1. In your app, open Configuration in the left navigation and select Record Details Layout icon Records Detail Layout
  2. Click Add Field, then choose Dropdown or Multi-Select
  3. In the field setup panel, set the picklist source/type to API
If the API type is not available in the field configuration, contact Elementum support to have the API Dropdown feature enabled for your organization.

​
Step 2: Configure the API Endpoint

Provide the details for the external API that will supply the dropdown values:
SettingDescription
URLThe full endpoint URL. Supports template parameters that reference field values on the current record
MethodHTTP method: GET, POST, or PUT
HeadersCustom HTTP headers to include in the request (e.g., Content-Type, Accept)
Query ParametersURL query parameters appended to the request
The API endpoint must return a JSON response. Non-JSON responses will cause the dropdown to fail to load.

​
Step 3: Configure Authentication

Select the authentication method that matches your external API:
Auth TypeConfiguration
NoneNo authentication headers are sent
BasicProvide a username and password. Elementum sends these as a Base64-encoded Authorization: Basic header
Bearer TokenProvide a static token. Sent as Authorization: Bearer <token>
OAuth 2.0Provide the token URL, client ID, and client secret. Elementum automatically handles the client credentials flow, token acquisition, and caching
For OAuth 2.0, Elementum caches tokens and refreshes them automatically before expiration.

​
Step 4: Configure the Request Body (POST/PUT Only)

If the API requires a POST or PUT request, configure the body:
Body TypeDescription
JSONA JSON payload. Supports template parameters that reference record field values
FormKey-value pairs sent as form-encoded data

​
Step 5: Map the Response

Define how Elementum should extract dropdown options from the API response:
SettingDescription
IDThe JSON path to the unique identifier for each option (used as the stored value)
LabelThe JSON path or template for the display text shown to users. Supports template parameters
ValueAn optional JSON path for the value to store (if different from the ID)
SchemaThe JSON schema describing the response structure, used for parsing nested responses
Example: If your API returns: 
{
  "results": [
    { "code": "US", "name": "United States" },
    { "code": "CA", "name": "Canada" }
  ]
}
You would configure:
  • ID: code
  • Label: name

​
Template Parameters

URL, label, headers, query parameters, and body fields support template parameters that dynamically insert values at runtime:
Parameter SourceDescription
Field ValueReferences a field on the current record. The field’s value is substituted into the template at request time
Text ValueA static text string
JSON PathA value extracted from a JSON structure
This allows the API request to be contextual. For example, a “City” dropdown could pass the selected “Country” field value as a query parameter to filter results.

​
Approach 2: Dynamic Dropdowns on API Elements

This approach models external API data as an Elements icon Element, then creates a dynamic dropdown that references that Element. This is suited for scenarios where you need the external data to participate in relationships, calculations, or reports.
  1. Navigate to Settings icon Organization Settings > CloudLinks
  2. Click Add CloudLink
  3. Select API as the provider type
  4. Configure the connection credentials (base URL, authentication)
  5. Save the CloudLink

​
Step 2: Create an API Element

  1. Create a new Elements icon Element connected to your API CloudLink
  2. Configure the API Requests on the Element. Each API Request defines how to fetch data from the external system
  3. Define the Element’s fields to match the structure of the API response
The Element’s data is populated by the API at runtime rather than being stored in Elementum’s database.

​
Step 3: Create a Dynamic Dropdown Field

  1. In your app’s Configuration > Record Details Layout icon Records Detail Layout, add a new Dropdown or Multi-Select field
  2. In the field configuration, set Dropdown Type to Dynamic
  3. In the related object selector on the right side of the page, choose the API Element you created
  4. Configure the API Request filter:
    • Select which API Request on the Element to use for fetching dropdown values
    • Map any required request variables to fields on the current record

​
Step 4: Configure Variable Mappings

If the API Request requires input parameters, map them to fields on the current record or static values:
Mapping TypeDescription
Record FieldA field value from the current record is passed as a variable to the API Request
Static ValueA fixed value is passed to the API Request
This allows the dropdown options to change based on other field values on the record.

​
Cloud Credentials for API Connections

API-powered features store authentication credentials securely through the CloudLink system. To manage API credentials:
  1. Navigate to Settings icon Organization Settings > CloudLinks
  2. Select or create an API CloudLink
  3. Configure credentials in the credential editor:
    • Basic Auth: Username and password
    • Bearer Token: API token
    • OAuth 2.0: Token URL, client ID, client secret, and optional scope
Credentials are encrypted at rest and are never exposed in the UI after initial configuration.

​
Considerations

  • API responses are subject to a configurable timeout. If the external API does not respond within the timeout period, the dropdown displays an error
  • Consider the latency of your external API. Dropdowns that take several seconds to load create a poor user experience
  • For high-traffic fields, ensure your external API can handle the request volume
  • If the API returns an error or is unreachable, the dropdown displays an empty state with an error indicator
  • Verify your API endpoint is accessible from Elementum’s servers (firewall rules, IP allowlisting may be required)
  • API Picklist fields fetch data on each dropdown open, ensuring values are always current
  • Dynamic dropdowns on API Elements fetch data according to the Element’s configured refresh behavior
  • Use OAuth 2.0 or Bearer Token authentication for production integrations. Avoid Basic Auth over non-HTTPS endpoints
  • API credentials are stored encrypted and are not retrievable after configuration
  • Elementum sends requests server-side; API endpoints are not exposed to end users’ browsers

​
Troubleshooting

IssueResolution
Dropdown shows no optionsVerify the API endpoint is reachable and returns a valid JSON response. Check the response mapping (ID and Label paths)
Authentication errorsConfirm credentials are correct. For OAuth, verify the token URL, client ID, and client secret. Check that the OAuth scope grants read access
Dropdown loads slowlyCheck the external API’s response time. Consider adding caching on the API side or reducing the response payload size
Options appear but display incorrectlyReview the Label template configuration. Ensure the JSON path points to the correct field in the response
Variable mappings not workingEnsure the mapped source fields on the current record have values. Empty source fields result in empty or null parameters in the API request