General
The Call APIs feature allows users to generate new transactions from an external API endpoint on a scheduled basis. Users can configure automated imports that retrieve data from external systems and create transactions automatically.
Each API Call runs on an individual schedule and can be configured with its own authentication, request method, scripts, and processing logic. By using configurable identifiers and response processing scripts, only new transactions can be generated, reducing development time and increasing flexibility.
The feature is located under:
Settings → Imports → Call APIs
Call APIs overview
The overview displays all configured scheduled API calls.
Available information includes:
- Whether the API call is active
- Frequency interval
- HTTP method
- Endpoint URL
- Last execution time
- Current status
Users can create a new scheduled API call by clicking New API Call.
Users can also:
- Edit an existing API call
- Delete an existing API call
- Test the configured API endpoint
- Configure request body and response scripts
Creating a new API Call
To create a new scheduled API call:
- Navigate to Settings → Imports → Call APIs
- Click New API Call
- Configure the required settings
- Click Save
When the scheduled API call is active, it cannot be edited.
API Call settings
The following settings are available when configuring an API Call.
Active
Enables or disables the scheduled API call.
When enabled, the API call executes automatically according to the configured frequency.
Name
Specifies the name of the API Call.
The name is used to identify the scheduled import configuration.
Preparation
Specifies whether the created transaction is created in Preparation Mode.
Run as user
Specifies the Integrator user used to create the transaction.
The selected user must have sufficient permissions to create transactions and access the required resources.
Frequency(sec)
Defines the number of seconds between scheduled API executions.
Be careful when configuring the frequency. Very low intervals, such as 1 second, are not recommended and may cause unnecessary system load or excessive external API requests.
Client
Specifies the client used for authorization. The client must be configured in the Client settings, see Clients.
The selected client is used when authenticating the API request.
Method
Specifies the HTTP method used for the API request.
Supported methods:
- GET
- DELETE
- PATCH
- POST
- PUT
URL
Specifies the endpoint URL used for the API request.
The URL can be configured as:
- Plain text
- Javascript script
Only Javascript is supported for scripted URLs.
When using a script, the script must return a value using the return statement.
Example:
return "https://example.com/api/orders";
Headers
Defines additional HTTP headers required for the API request.
Headers can be added using the Add Header button.
Typical examples include:
- Authorization headers
- API keys
- Content-Type definitions
Test URL
The Test URL button executes the configured API request immediately and displays the response.
This allows users to validate:
- URL configuration
- Authentication
- Headers
- Returned response data
After the response is displayed, the response script can be executed manually by clicking Run response.
Body Script
The Body Script defines the request body sent with the API call.
Only Javascript is supported.
The script should return the request payload.
Example:
return JSON.stringify({
id: 1001,
status: "New"
});
Response Script
The Response Script is used to process the API response and return a transaction object.
The script is responsible for:
- Parsing the response
- Creating transaction data
- Determining whether a transaction should be created
If the transaction should not be created, the script must return the string:
return "Abort";
Returning "Abort" prevents the scheduled API call from being deactivated and safely exits the script execution.
If any other unhandled error occurs, the scheduled API call is automatically deactivated.
Scheduled execution behavior
When an API Call is active:
- The system executes the API request automatically according to the configured frequency
- The response is processed using the configured response script
- Transactions are created based on the returned transaction object
- Errors in the response script may deactivate the scheduled API call
To modify an API Call configuration, the API Call must first be deactivated.
Example workflow
A typical workflow for a scheduled API import is:
- Configure the API endpoint
- Configure authentication headers
- Configure request body if required
- Test the API request using Test URL
- Create a response script that converts the API response into a transaction object
- Activate the scheduled API call
- Transactions are automatically created on the configured interval
Example response data
Example API response:
[
{
"rfqId": 1,
"createdTime": "2023-10-18T06:20:10.705Z",
"userId": 1,
"modelId": 1,
"modelVersionId": 1,
"configurationId": 2,
"name": "Admin",
"email": "",
"comment": "Dette er en test",
"customFields": []
}
]
Notes
- Scheduled API calls cannot be edited while active
- Only Javascript is supported for scripts
- Always use
returnstatements in scripted fields - Use
"Abort"in response scripts when transactions should not be created - Excessively frequent API calls are not recommended
- The selected Integrator user must have sufficient permissions