This guide explains the benefits of the new Positions Upload (v3) endpoint, compares it to the previous version, and highlights the key differences to ensure a smooth migration.

Why did we build v3?

Unified endpoint for all file types

v3 offers a unified endpoint for all file types (CSV, XML, etc).
All position files will be processed similarly, allowing all clients to take advantage of extra data packages.

Simplified request structure:

The new API offers a simpler design with fewer parameters, improving maintainability and reducing potential errors.

Steps to migrate

Update POST request URL to replace v1/expost/check with v3/data/positions/upload
Add a new Header to the request with key X-FundApps-File-Format and value of xml/positions
Add a parameter for snapshotDate if required
Update status requests to replace v1/expost/result/{id} with v3/data/positions/{id}/status
Update response handling to handle the new responses

Uploading a file

Request

HTTP Method - POST (same as v1)

URL

version	URL
v1	https://{environment_name}-api.fundapps.co/v1/expost/check
v3	https://{environment_name}-api.fundapps.co/v3/data/positions/upload

Query Parameters

version	Parameter (Key)	Type	Example (Value)
v1	-	-	-
v3	`snapshotDate`	Date	`2025-01-25`

Note: support for the ignoreUnknownProperties and ignoreMissingProperties v1 flags is currently in development

Body

multipart/form-data in the body of the request. (same as v1)

	v1	v3
positions	✅	✅

Headers

v3 requires the following header to be added

Header (Key)	Valid Values	v1	v3
`X-FundApps-File-Format`	`xml/positions`, `csv/positions`	-	✅

Security

Basic Authentication - (same as in v1)

Response

<links>
    <result>/v1/expost/result/8fca0912-063e-4699-b951-b30200ca28c5</result>
</links>

{
  "id": "0775103d-40be-40d1-a7be-cf72c3c6e297",
  "dateCreated": "2025-03-18T13:45:56.7060539Z",
  "status": "InProgress",
  "hasWarnings": false
}

For more details, view the full v3 Position Upload Endpoint specifications.

Status

Request

HTTP Method - GET

URL

version	URL
v1	https://{environment_name}-api.fundapps.co/v1/expost/result/{id}
v3	https://{environment_name}-api.fundapps.co/v3/data/positions/{id}/status

Query Parameters

version	Parameter (Key)	Type	Example (Value)
v1	`id`	Guid	`0775103d-40be-40d1-a7be-cf72c3c6e297`
v3	`id`	Guid	`0775103d-40be-40d1-a7be-cf72c3c6e297`

Security

Basic Authentication

Response

<?xml version="1.0" encoding="utf-8"?>
ResultsSnapshot ValidationState="Passed" RuleState="Passed" Status="Okay" PipelineStage="Finished" Duration="00:01:28.7030000">

{
  "id": "0775103d-40be-40d1-a7be-cf72c3c6e297",
  "dateCreated": "2025-03-18T13:45:56.7060539Z",
  "status": "Success",
  "hasWarnings": false
}

View the full v3 Status Endpoint specifications.

Troubleshooting

If a 403 response is returned, confirm your authentication is being set correctly, and that the header of X-FundApps-File-Format with a value of either xml/positions or csv/positions has been added.