Search

Authenticating and Extracting Information from API calls with the HTTPCaller

Desiree Marsden
Desiree Marsden
  • Updated

Files

Introduction 

FME can interact with APIs through various readers, writers, and transformers without the need to code. For web service providers not natively supported by FME, the HTTPCaller transformer can access a sea of APIs. This tutorial will walk you through how to “wrap up” an API into a custom transformer. By creating a custom transformer, you can take a sequence of transformers needed to access the information in an API into a single object on the canvas, helping to tidy up your workspace as well as make your transformation sequence shareable by publishing to the FME Hub. 
 

Requirements

 

Precisely’s APIs

In this tutorial, we will access one of Precisely’s APIs as an example of how to create a custom transformer that outputs data that is more digestible, which you could use to enrich your data.
Precisely provides services to access 100+ APIs that work to enrich your data and power your applications. Learn more about Precisely’s APIs here.

Note: We are not using Precisely’s cloud APIs

For this tutorial, we will create a custom transformer using Precisely’s Address Verification API. The Address Verification API works to eliminate errors in address data, improving customer experience, keeping it up-to-date, and maintaining its accuracy and consistency.

Step-by-step Instructions

Part 1: Generate a Bearer Token 

1. Create Text File

After signing up for Precisely’s free trial plan, explore the documentation, particularly the Getting Started and the Address Verification API (login required) pages. API documentation will likely mention what is required to authorize and make your first API call. Vendors often update and change how to connect to and use their API services, but currently Precisely’s APIs require generating an OAuth token by encoding your API Key and Secret. Let’s set this OAuth token up in FME:

Start by creating a text file containing the API Key and Secret provided by Precisely as outlined by their documentation. Using Notepad++ or a similar text editor, create this text file; it should look something like this:

Save the file as text_outline.txt

 

2. Convert Text File to BASE64

Open FME Workbench and create a blank workspace. 

Add a Text File reader and browse to the text_outline.txt file created in step 1. 

Connect the text_line reader feature type to a BinaryEncoder transformer to convert the text file to BASE64, as outlined by Precisely’s documentation. In the BinaryEncoder parameters, set the Output Encoding Type to Base64, then set the Input Attribute to text_line_data and the Output Attribute to Key_Secret_encoded. 

 

Finally, expose the encoded text attribute, so you can pass that value into the HTTPCaller. Add an AttributeExposer and set the Attribute to Key_Secret_encoded. 

3. Configure the HTTPCaller According to the API’s Documentation

In this example, the HTTP Method is set to POST, and the Header and Body have been configured to carry the Authorization Key. The output of HTTPCaller will be stored in the _response_body

  • Request URL: https://api.precisley.com/oauth/token
  • HTTP Method: POST
  • Headers:
    • Name: Authorization
    • Value: Basic @Value(Key_Secret_encoded)
  • Body:
    • Upload Data: Specific Body Upload
    • Upload Body: grant_type=client_credentials
    • Content Type: URL Encoded (application/x-www-form-urlencoded)

 

 

4. Test Run Workspace
Upon running the HTTPCaller we get a _response_body with the access (bearer) token embedded in the JSON body. 

 

5. Add Test Data 

Next, add some data to test the first API Call. This tutorial will use mock census data from a CSV file. Add a CSV (Comma Separated Value) reader to the canvas and browse to Sample_addresses.csv for the Dataset.  

 

6. Add Token to Data

Use a FeatureMerger to add the _response_body to each row in the census data, by setting the Join On Supplier and Requestor values to the same constant (i.e, the value “1”) and leaving the Comparison Mode as Automatic. 

 

7. Flatten JSON

Connect the Merged output of the FeatureMerger to a JSONFlattener. The JSONFlattener will extract the object keys and values into FME feature attributes. If you need a refresher on working with JSON in FME, refer to this tutorial. In the JSONFlattener parameters, set the JSON Document to _response_body, then for Attributes to Expose, click the ellipsis, then type access_token. 

 

8. Limit Calls

With the Precisely free trial, there is a limit to the number of calls that can be made. To avoid any 429 responses, add a Sampler between the FeatureMerger and JSONFlattener and configure it to sample the first 10 rows of the merged data. 



In the output, we see that all features now have an access_token attribute. We are now ready to use these features in our first API Call.
 

Part 2: POST HTTP Method: Configure the HTTPCaller to make your first API Call

Put down another HTTPCaller on the Workspace. Refer back to the documentation for the API for the request parameters of the API. 

{
    "options": {
        "OutputCasing": "M"
    },
    "Input": {
        "Row": [
            {
                "AddressLine1": "@Value(address)",
                "AddressLine2": "",
                "City": "@Value(city)",
                "Country": "USA",
                "StateProvince": "@Value(state)",
                "PostalCode": "@Value(zip)",
                "FirmName": "@Value(company_name)"
            }
        ]
    }
}

 

The Response URL has .json at the end, as we want our results returned in JSON. Please refer to the Address Verification Precisley API documentation for more detailed instructions about this API, the link requires a Precisely account to view.

Confirm your configurations and run your HTTPCaller.


Inspect your _response_body. This holds all the valuable information we need. All that is left to do is to parse this and make the results digestible.
 

Part 3: Parsing the response body

These transformers come in handy when parsing JSON

Let's create a sequence of these transformers that will correctly extract information from the response body of our API every time. You can visualize your response body in any JSON Parser of your choice to understand the schema of your API call.

 

​​​​​​​1. Fragment JSON

First, add a JSONFragmenter to fragment a section of your response body that you want to flatten. Select _response_body to be the JSON Attribute. For JSON Query, input:

json["Output"][*]

 

2. Flatten JSON
Connect another JSONFlattener to expose the attributes. There are a few ways you can go about doing this. 

  • Manual Selection
  • Import Schema 

To manually select attributes to flatten, enter the values into the “Attributes to Expose”. 

 

To Import Schema from a source, select Import to bring in a source document that follows the same schema. You could achieve this by simply saving a .json file of the _response_body locally. 


​​​​​​​Run the JSONFlattener, and your selected attributes will be exposed in your table.
 

Part 4: Create a Custom Transformer

Now that you’ve completed the sequence of transformers needed to extract information from the API, it's time to package them into a custom transformer. 

 

Why Create a Custom Transformer?

Custom Transformers not only tidy up a workspace but also help create reusable, modular components that can be shared, maintained, and standardized across multiple workspaces. 

 

Choosing a Design Approach

Deciding which transformers to include in a custom transformer depends on its specific needs and use case. 

Design approaches to this example may be:

  1. Authorization-focused custom transformer that standardizes the authentication process while allowing flexibility in the subsequent API calls. An authorization custom transformer may include the BinaryEncoder, AttributeExposer, and first HTTPCaller (GeneratingToken_OAuth). 

  1. A complete API workflow custom transformer that provides a comprehensive and standardized way to connect to the API. Such a transformer may be a series of transformers from the BinaryEncoder to the final HTTPCaller (PreciselyAddressVerifyer). 

Several approaches are valid, but the best choice is always one that best suits a general use case.

 

Other Design Considerations

  • Removing the Sampler
     If users upgrade from a trial plan to a paid plan, the Sampler transformer, which was used to limit data during testing, may be a limiting factor in production.

  • API Cost Management
     Frequent API calls can become costly. Consider:
    • Adding rate limiting
    • Documenting expected usage
    • Implementing safeguards for high-volume processing

Additional considerations are important when publishing a transformer to the FME Hub. Refer to the article and documentation to learn more:

 

Creating the Custom Transformer

  1. Select the sequence of transformers on the canvas that satisfies the use case
  2. Right-click or (Ctrl + T) to create your custom transformer.
  3. In the dialog, set:
    • Transformer Name
    • Attribute References
    • (Optionally) Category and Description
  4. Add Input and Output ports to match your design.

Refer to the Custom Transformer documentation for more information on custom transformers and best practices.

Was this article helpful?

We're sorry to hear that.

Please tell us why.

As of January 14th, 2026, comments on knowledge base articles have been closed. To make sure questions don’t get missed and to enable more community support, we’ve moved discussions to the FME Community. If you have a question or a comment about this article, please create a new post or create a support ticket.