What is the Friendly Upload Service and how does it work?

Software Version: 02.26.2026 or later

Introduction

This feature adds a new “Friendly Upload” service endpoint to NorthScope that allows third‑party systems to upload file attachments using friendly IDs (TransactionType, TransactionID, CompanyID) instead of internal SK values.

It is designed specifically for cases where:

• The parent transaction may not exist yet (it is still in the inbound integration queue), and/or

• The third‑party system does not know the SK value of the transaction.

Files submitted through this endpoint are saved to the file attachment directory and then attached to the appropriate transaction via the integration queue, so that from the user’s perspective they behave exactly like attachments added via the NorthScope UI.

1. What is the Friendly Upload service?

The Friendly Upload service is a new NorthScope API POST service endpoint that allows third‑party applications to upload file attachments for transactions using friendly IDs instead of internal SK values.

It mimics the existing Upload service’s behavior (file handling, attachment creation) but is:

• Integration‑friendly (no SK required), and

• Queue‑driven (asynchronous and retry‑able via the integration queue).

2. Why was this feature created?

This feature addresses two main integration challenges:

1. Timing: For some third party integrations, the file attachment may be sent before the Fish Ticket transaction is fully created in NorthScope (it might still be in the inbound integration queue).

2. Identification: Third‑party systems typically know business IDs (e.g., TransactionID, CompanyID) but not internal SK values, which the existing Upload service requires.

The Friendly Upload service solves these by:

• Accepting TransactionType, TransactionID, CompanyID instead of SKs, and

• Saving the file immediately while deferring attachment to the integration queue, which runs after or alongside transaction integration.

3. What does the new endpoint look like?

Base URL:

Example:

4. How does authentication work?

The Friendly Upload service uses the same authentication pattern as other NorthScope API services, such as ActionCommand:

• Headers required:

  • NSLogin: Your NorthScope user (email address/username).

  • NSAPISession: A valid API session token or Static API Key.

Typical setup for Static API Key:

1. In NorthScope, go to System → My Profile.

2. Set API Authentication Mode to Static Token.

3. Click Save.

4. If API Key is blank, click Generate API Key.

5. Use this API Key as the value for NSAPISession in your requests.

5. What query string parameters are required?

The service expects three query string parameters:

1. TransactionType

   • Initially supports APDeliveryTicket.

2. TransactionID

   • The external/business ID of the target transaction.

   • Must correspond to a real transaction in NorthScope (or one that will be created via integration).

3. CompanyID

   • The ID of the company where the transaction exists (or will exist).

Example:

6. What does the request body look like?

• The request body should contain the binary contents of a single file.

• All integrations should send data element in the form-data mode.

In Postman:

1. Select Body.

2. Choose form-data.

3. Add a key (name is not strictly important; the upload service handles a single file).

4. Change type to File and choose a file.

In curl (example):

The service supports one file per request, consistent with the underlying Upload service.

7. How are files processed after upload?

Once the Friendly Upload endpoint receives a request:

1. File is deposited into the configured attachments directory on the filesystem.

   • Same behavior as the existing Upload service.

2. The service creates an entry in the inbound integration queue containing:

   • The generated unique filename.

   • TransactionType.

   • TransactionID.

   • CompanyID (and related metadata).

3. Processing the inbound integration queue:

   • Locates the target transaction using TransactionType/TransactionID/CompanyID.

   • Inserts a record into ERPx_MFUploadHistory (the NorthScope “Attachments” repository).

   • Links the attachment to the transaction so it appears in the UI like a user‑uploaded attachment.

This design ensures the attachment can be created even if the transaction doesn’t exist yet at the moment the file is uploaded.

8. Is the attachment processing synchronous or asynchronous?

Processing is asynchronous:

• The HTTP call itself:

  • Saves the file to disk.

  • Creates the integration queue record.

• The actual association of the file to the transaction (updating Notes/Attachments, ERPx_MFUploadHistory) happens when the integration queue is processed.

This approach makes the process retry‑able:

• If the attachment record is processed before the transaction exists—or any other error occurs—the integration queue record can be reprocessed after the underlying issue is resolved.

9. What happens if the transaction does not yet exist?

That scenario is explicitly supported:

• The service does not require the transaction to exist at upload time.

• The attachment’s queue record will be processed later, once:

  • The transaction is created via integration, and

  • The integration queue processor runs.

• If ordering issues occur (attachment record processed before transaction exists), the queue record can be re‑processed.

This behavior is critical for integrations where the transaction integration and attachment upload occur in rapid succession or without guaranteed sequence.

10. How is this different from the existing Upload service?

Key differences from the existing Upload service:

1. Identification:

   • Existing Upload: requires specific SK values for the transaction and attachment target.

   • Friendly Upload: uses TransactionType, TransactionID, CompanyID; no SK needed.

2. Timing & Processing:

   • Existing Upload: always assumes the transaction is already present because it requires a NorthScope SK value which only exists after a transaction is created.

   • Friendly Upload: saves the file immediately and then uses the Inbound integration queue to associate it with the transaction later.

     • Note: Integrating the same attachment multiple times will result in multiple copies attached to the transaction. There is not a process to verify any duplicate attachments or update/delete through the friendly API. It's add-attachment only.

3. Use case focus:

   • Existing Upload: always UI‑driven, user‑initiated attachments.

   • Friendly Upload: primarily third‑party integration scenarios.

11. What configuration is required for file storage?

In NorthScope:

• Go to System → Setup → Preferences.

• Ensure the File Attachments directory is correctly configured and accessible.

If this path is incorrect or inaccessible:

• Attachments will fail for both:

  • UI‑based uploads, and

  • Uploads via the new Friendly Upload API.