Position Green API: Uploading files

Modified on Tue, 21 Jul at 9:23 AM

Inserting data into Position Green

To import files into Position Green you can send HTTP POST requests to the Import endpoints. Synchronous uploads process immediately, while Queue endpoints enable asynchronous background processing for large datasets.

https://api.positiongreen.com/v1/imports

You must supply valid credentials in the form of an access token or client ID/secret header.

Get available import configurations

Retrieves a list of available import configuration keys for the authenticated tenant.

GET https://api.positiongreen.com/v1/imports

Example Response (200 OK)

[
  "ERP_FINANCIAL_IMPORT",
  "FACILITY_ENERGY_IMPORT",
  "TRAVEL_DATA_IMPORT"
]

Note about fileType and yearId values

fileType / importConfiguration is a string value that needs to match an existing import-configuration key in Position Green. Available configuration keys can be queried via GET /imports or provided by Position Green upon request.

Optional yearId parameter: All import endpoints accept an optional yearId parameter (UUID). If omitted, data will be imported into the organization's currently active year.

Synchronous Import Endpoints

1. Upload binary file (Multipart Form)

The request must have a multipart/form-data content type with the file sent as file, alongside fileType (string) and optional yearId (UUID).

POST https://api.positiongreen.com/v1/imports

2. Import JSON Payload

For imports configured by Position Green to handle JSON data.

POST https://api.positiongreen.com/v1/imports/json

Request Body Example:

{
  "options": {
    "importConfiguration": "ERP_FINANCIAL_IMPORT"
  },
  "payload": "{\"records\": [{\"account\": \"1001\", \"amount\": 520.50}]}",
  "yearId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

3. Import Base64 Encoded File

Uploads a file encoded in Base64 string format.

POST https://api.positiongreen.com/v1/imports/base64

Request Body Example:

{
  "name": "data-export.xml",
  "content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4...",
  "fileType": "ERP_FINANCIAL_IMPORT",
  "yearId": null
}

Background / Queued Import Endpoints

For large datasets, use the /queue endpoints. These endpoints return immediately with an HTTP 202 Accepted status and an importId. You can poll the status endpoint to track progress.

Endpoint	Format	Description
`POST /imports/queue`	multipart/form-data	Queues a binary file upload for background execution.
`POST /imports/queue/json`	application/json	Queues a JSON payload for background execution.
`POST /imports/queue/base64`	application/json	Queues a Base64 encoded file for background execution.

Queued Response Example (202 Accepted)

{
  "importId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

Checking Queued Import Status

Poll this endpoint using the importId returned from a /queue endpoint to check processing status.

GET https://api.positiongreen.com/v1/imports/status/{importId}

Path Parameters

Name	Type	Description
importId*	string (uuid)	Required. The identifier returned when the import was queued.

Status Response Example (200 OK)

{
  "importId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status": "Done",
  "startedAt": "2026-02-01T10:00:00Z",
  "finishedAt": "2026-02-01T10:02:15Z",
  "details": {
    "validations": [
      {
        "severity": "Info",
        "message": "Successfully imported 150 records."
      }
    ]
  }
}

Possible status values: Queued, InProgress, Done, Failed.

Example 1 - Import a file to Position Green API using HttpClient

namespace TestClient;
public class Program
{
    private static string apiUrl = "https://api.positiongreen.com/v1/imports";
    private static string loginUrl = "https://login.positiongreen.com/connect/token"; 
    
    public static async Task Main()
    {
        var token = await RequestToken("clientid", "clientsecret");
        var fileType = "ERP_FINANCIAL_IMPORT";
        await UploadFile(token, "data.xml", fileType);
    }

    private static async Task<string> RequestToken(string clientId, string clientSecret)
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Accept", "application/json");
        client.BaseAddress = new Uri(loginUrl);
        var data = new Dictionary<string, string>
        {
            { "client_id", clientId },
            { "client_secret", clientSecret },
            { "grant_type", "client_credentials" },
        };
        var response = await client.PostAsync("/connect/token", new FormUrlEncodedContent(data));
        var token = await response.Content.ReadFromJsonAsync<Token>();
        return token.access_token;
    }

    static async Task UploadFile(string token, string file, string fileType)
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
        
        var form = new MultipartFormDataContent();
        var fileData = await File.ReadAllBytesAsync(file);
        var byteArrayContent = new ByteArrayContent(fileData);
        byteArrayContent.Headers.ContentType = MediaTypeHeaderValue.Parse("text/xml");
        
        form.Add(byteArrayContent, "file", file);
        form.Add(new StringContent(fileType), "fileType");
        
        var response = await client.PostAsync(apiUrl, form);
        if (!response.IsSuccessStatusCode)
        {
            throw new Exception(await response.Content.ReadAsStringAsync());
        }
    }
}

public class Token
{
    public string access_token { get; set; }
}

Explore the full Import section on our Swagger page.