Submitting a Job through the FME Flow REST API V4

Introduction

The FME Flow REST API allows third-party applications to run jobs on FME Flow. Connecting your systems and users over the web can exchange data and information in real time between otherwise unrelated systems. This article will walk through the steps to submitting a job using the V4 API, which was released as of FME 2025.1. Please see this article for guidance on using the FME Flow Rest API V3. The V3 API will be removed from FME 2026.1, and we encourage all users to update workflows using API calls as soon as possible.

All workspaces submitted by the REST API use the FME Flow REST Service. The REST Service allows you to run jobs on FME Flow, much like using the job submitter service. To use the transformation services, like data streaming or data download, use a webhook URL instead. For more control, consider Data Virtualization.

Multiple API calls are required to submit a job and check its result:

The first call (POST /jobs) submits the job to Flow. Flow queues the job and then returns the Job ID. 

The second call is a GET request, which retrieves information about a job. It differs depending on the workflow style: 

• For a synchronous workflow use /jobs/{Job ID}/result?longPoll=True, which waits until the job is complete before returning its results. The optional parameter longPollInterval is used to set the timeout of the request.
• For an asynchronous workflow, use /jobs/{Job ID}. This this will immediately information about a job, including its status (one of "queued", "running", "complete", "success", "failure", "cancelled"), and should be called repeatedly until the job is complete.

In this tutorial, you'll run a job on FME Flow synchronously and then asynchronously. Although requests will be sent using Postman, the same requests can be made from any HTTP client, like the HTTPCaller in FME Workbench. However, applications outside your network can only submit requests with the REST API if your FME Flow instance is publicly available. 

Requirements

• FME Flow 2025.1+
  • An FME Flow API Token with necessary permissions (see Authorizing Requests)
• Postman

REST API Overview

In this tutorial, you'll submit synchronous and asynchronous jobs through the FME Flow REST API V4. We’ll use the attached "10seconds.fmw" workspace for both requests. This workspace doesn't do anything but takes 10 seconds to complete, and contains Published Parameters that aren't used.

Documentation

Technical guidance on the V4 API is available in the documentation and is accessible via Help & Resources in the Flow UI. This page lists all available endpoints, parameters, possible response codes, and schemas for their request and response bodies. 

Authorizing Requests

Just like a user needs to log into FME Flow before running a workspace, an application needs to provide identification before running a job. This is done with tokens.

This tutorial assumes you already have a token. If you do not already have a token, create one by following our FME Flow REST API Authorization tutorial or from the FME Flow Token Management page.  

Step-by-Step Instructions

Publish the workspace to Flow.

Download the workspace in the Attachments section and publish it to Flow with the Job Submitter service selected. Once published, open the Run Workspace page and review its Published Parameters. It is generally best practice to review data or parameters before making API requests.

Published Parameters are set in the request body of job submission API calls. There are a couple of ways to find which parameters are available.

The first is via the Advanced section at the bottom of the Run Workspace page. Here, you'll find a table named Published Parameters, with a Parameter column containing each available parameter. The Options column contains a parameter's accepted inputs (blank means anything is accepted), and Type contains its data type. 

The second method is fetching published parameters via the endpoint GET /workspaces/{repository}/{workspace}/parameters. See the API documentation for more information on this endpoint.

Part 1: Getting Job Results Synchronously

1. Create a New Request in Postman

Use the plus button to create a new API request. Set the method to POST and the URL to <Flow URL>/fmeapiv4/jobs replacing "<Flow URL>" with your Flow hostname.

In the Authorization tab, add a new header with the key Authorization and value fmetoken token=<your token>:

In the Body tab, set the type to "raw" and the content to "{}". Click Send and ensure you get the following response:

This response is expected as we could authenticate correctly, but included an invalid request body - empty JSON in this case.

2. Construct a Request Body

In the REST API docs, expand the GET /jobs endpoint (found under the Jobs section) and click Schema in the Request Body section:

From this Schema, we see only repository and workspace are necessary in the general case. The location published parameter is also necessary in our case, though, since it's set to required in the workspace. From this, we can construct the following request body, with the optional year parameter also being specified:

{
    "repository": "Tutorials",
    "workspace": "10seconds.fmw",
    "publishedParameters": {
        "location": ["Burnaby", "Vancouver"],
        "year": 1985
    }
}

In Postman, replace "{}" in the Body with the JSON above and hit Send. You should see a response similar to the following with a different ID. Note this Job ID down.

3. View Workspace Status Synchronously

Create a new API request in Postman with the following configuration:

• URL: <Flow Hostname>/fmeapiv4/jobs/{Job ID from previous response}/result?longPoll=true*
• Method: GET
• Headers: [same Authorization header and value as before]
• Body: none

*When you enter this URL, Postman will populate the Query Params table automatically - this is expected.

Hit Send. You should see a response with the attribute "status" showing "success":

4. Observe Synchronous Behaviour.

With the two API requests open in different Postman tabs, submit another job (run the first request), copy the ID, paste it into the second request's URL, and fetch its information. You should see the request take a while to complete.

Part 2: Getting Job Results Asynchronously

1. Create an Asynchronous Request

Duplicate the second request by right-clicking on it and pressing Duplicate Tab.

In the URL of the duplicated request, remove /result?longPoll=True, keeping everything up to and including the job ID. Hit send and verify you get a similar 200 response with a longer body, but with the same "status": "success" attribute:

2. Observe Asynchronous Behavior

Submit another job with the POST request, copy the ID, and submit the asynchronous GET request just created. You should see a similar response as before, but with "status": "running" instead:

Keep making the same request until the status changes to "complete". This should happen 15 seconds after the job is submitted.

Troubleshooting 

401 (Unauthorized) Errors

If a token is invalid, you’ll receive a 401 error code. 

Tokens are likely to be rejected when they expire or if permission is not given to access the workspace or its dependencies. For authentication options and troubleshooting, please review the Authorization section of the FME Flow REST API documentation or the Authorization section of the FME Flow REST API documentation.

Other Error Codes 

The FME Flow REST API returns an error when something goes wrong with a request. The API response contains the code and a message, which can usually be used to troubleshoot. 

For an overview of general error codes and their corresponding messages, review the HTTP Response Codes and Errors section of the REST API V4 documentation in the Overview tab. Sometimes, error codes may be referenced and explained in an endpoint's documentation, so it's good to check there too if a problem arises.