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?

Positions Upload (v3) brings several improvements over Position Upload (v2), making it more efficient and scalable.

Key Benefits:

Increased file size limit:

v2 had a strict 4.5 MB file size restriction.
v3 significantly increases the limit to 50 MB, allowing larger position files to be uploaded in a single request.

Unified endpoint for all file types

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

Simplified request structure:

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

Positions Upload

Request comparison

HTTP Method - POST (same as v2)

URL

version	URL
v2	https://{environment_name}-svc.fundapps.co/api/adapptr/v2/task/positions/expost
v3	https://{environment_name}-api.fundapps.co/v3/data/positions/upload

Please note - We have moved the upload endpoint from your service domain to the api domain

Query Parameters

No change

Body

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

	v2	v3
positions	✅	✅

Headers

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

Security

Basic Authentication - (same as in v2)

Response comparison

{
  "id": "0775103d-40be-40d1-a7be-cf72c3c6e297",
  "type": {
    "id": 1,
    "name": "Positions"
  },
  "status": {
    "id": 1,
    "name": "Accepted",
    "description": "Position file accepted. Please check the tracking endpoint to check for any errors in the file upload and to track the progress of the file enrichment."
  },
  "dateCreated": "2025-03-18T13:45:56.7060539Z",
  "dateUpdated": "2025-03-18T13:45:56.7060539Z",
  "trackingEndpoint": "/api/adapptr/v2/task/0775103d-40be-40d1-a7be-cf72c3c6e297/status"
}

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

Note: The status code response for the upload endpoint is now 202 Accepted.

Status

Request comparison

HTTP Method - GET (same as v2)

URL

version	URL
v2	https://{environment_name}-svc.fundapps.co/api/adapptr/v2/task/{taskId}/status
v3	https://{environment_name}-api.fundapps.co/v3/data/positions/{id}/status

Query Parameters

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

Note - id represents taskStatus; we're just moving away from task-related terminology.

Security

Basic Authentication - (same as in v2)

Response comparison

{
  "id": "0775103d-40be-40d1-a7be-cf72c3c6e297",
  "type": {
    "id": 1,
    "name": "Positions"
  },
  "status": {
    "id": 3,
    "name": "Transmitted"
  },
  "dateCreated": "2025-03-18T13:45:56.7060539Z",
  "dateUpdated": "2025-03-18T13:48:43.2783463Z",
  "trackingEndpoint": "/api/adapptr/v2/task/0775103d-40be-40d1-a7be-cf72c3c6e297/status"
}

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

Steps to Migrate

Update API URLs to use the new v3 paths and api domain.
Ensure the request format matches v3 expectations.
Validate authentication and authorization settings.
Please make any adjustments to your response reading to accommodate the v3 response format.

For further details, refer to the full API specification.