Using the New Importer via REST API Import Service

Starting with Perfion version 2025-R2, the REST API has been extended with endpoints that allow you to call the New Importer. More precisely, these endpoints let you create and submit an Import Job to the Application Server.

This guide explains the required endpoints, their purpose, and the step-by-step process for creating and managing an Import Job.

Prerequisites

In this guide, we use Postman as an example tool to demonstrate API calls and their responses. Postman is a development tool that allows you to manually call APIs using different protocols.

Installing Postman is optional – you don’t need it to understand or use this guide. If you want to install it, you can download it here. 

Workflow overview

Creating an Import Job using this API involves the following steps:  

1. Authorize client 

2. Upload import file 

3. Upload the asset file (optional) 

4. Invoke the import method submitting the job 

5. Check the status of the submitted job 

Each step is described in detail below. 

Step 1: Authorize client 

Authorization is performed in the same way as described in the Authentication chapter.

Step 2: Upload the import file 

After authorizing, upload the Excel file containing the data to be imported.

URLPOST /import/upload-import-file 

The response is a JSON document containing:

• A binaryId (GUID) identifying the uploaded file
• The original file name
• The file size

You will need the returned binaryId later when submitting the Import Job (Step 4).

Example

The screenshot below shows how the POST request appears in Postman. The request has already been sent to the API, and the response is displayed in the lower section of the screen.

Step 3: Upload Asset-file (optional) 

If your import data contains binary features referenced by name (rather than by a URL or UNC path), you must provide these binaries in a separate ZIP file. This ZIP file is uploaded in the same way as the import file itself, except that it uses a different endpoint URL and requires a different file type.

URL: POST /import/upload-asset-file 

The response is again a JSON-body containing the binaryId, file name, and file size of the uploaded ZIP file. This binaryId will also be used later in Step 4 when creating the Import Job.

Step 4: Creating the Import Job for the application server 

After uploading the import file (and optionally the asset file), you can now submit the Import Job to the application server.

This can be done using the following: 

URL: POST /import 

For “ImportFileGuid,” provide the binary ID of the Excel file uploaded in Step 2. Optionally, supply the binary ID of the ZIP file uploaded in Step 3 as “AssetFileGuid.”

{ 

    "ImportFileGuid": "26db0a11-5c60-4066-8ed6-cf8d92efe105", 

    "Settings" : { 

        "BaseFeatureName": "Product" 

    } 

} 

The response to this POST request is a JSON document containing the ID of the job submitted to the application server:

{ 

    "jobId": 13 

} 

Step 5: Check the status of the submitted job (optional) 

You can keep track of an import job by calling a status-request which returns its current status.  

 URL: GET /import/job-status/{jobId} 

The response is a JSON document that provides the current status of the job, as shown in Postman below: 

Possible statuses are:  

• Created: Job has just been created 

• Pending: Job is waiting to be picked up by the application server 

• Running: Job is being processed by the application server 

• Failed: Job failed to execute  

• Success: Job completed successfully (may still have warnings) 

 To view detailed warnings or error messages, check the Import Logs in either the Perfion Web Client or the Windows Client.