← Back to Support

API Documentation

Spring Systems PortalApp Web API — endpoint reference for integrating external applications with Spring transactional data.

View full interactive docs on readme.io
API Reference

Introduction

Our Web API endpoints give external applications access to Spring Systems transactional data. Usage of web APIs is much preferred over file-based integration.

Spring PortalApp API integrations support three interaction patterns:

GET

Pull data from PortalApp into your system.

POST

Create or update records in PortalApp.

WEBHOOK

Spring pushes data outbound to your system in real time.

Best Practice: While transactions are supported in both directions, we find it most efficient for the transaction originator to initiate the call. For example, since Spring Systems originates Ship Request (940) transactions, it is faster for our system to push them out to your WMS rather than your WMS polling for them.

Webhook / "Reverse API": The same functionality and data structures described in this guide apply when Spring Systems is pushing data to your system. Contact your project team or email support to enable outbound push.

Alternate Formats: Spring also supports many popular ERP and WMS formats as well as custom mapping. Email support to discuss.

Authentication

All API calls must include your api_user and api_key credentials. Two authentication methods are supported:

Method 1 — Credentials in URL prefix:

https://api_user@api_key:<insert endpoint here>

Example: https://api_user@api_key:portalapp.springsystems.com/api/po-outgoing/export

Method 2 — Credentials as path segments:

https://<insert endpoint here>/api_user/usernamegoeshere/api_key/keygoeshere

Example: https://portalapp.springsystems.com/api/po-outgoing/export/api_user/usernamegoeshere/api_key/keygoeshere

Identifying Objects

Throughout our data you will see ID and KEY fields (e.g. xxx_ID and xxx_KEY). These are internally assigned identification values given by our system to a particular object (e.g. a vendor, a location, a purchase order).

  • xxx_id — numeric, auto-incremented integer
  • xxx_key — auto-generated alphanumeric string

You can use these to precisely identify an object when communicating with our system. If you don't know the ID or KEY, you can identify an object using a combination of other fields.

Get Requests

When requesting resources, you must include filter parameters. Filters contain an attribute, an operator, and a value. Use the resource schema to determine the attribute value type (string, int, boolean, date).

Filter URL format:

.../<endpoint>/po.filter.<operator>.<attribute>/<value>

Date range example:

.../po-outgoing/export/po.filter.gt.po_created/2021-08-22/po.filter.lt.po_created/2021-08-29

Operator Definitions:

OperatorDescription
eqequal
neqnot equal
ltless than
lteless than or equal
gtgreater than
gtegreater than or equal
likelike (partial match)
inin list
ninnot in list

Value Examples:

12345
12345,34567,56789
A12345
A12345,B34567,C56789
0
1
2021-01-01
2021-01-01T00:00:00
2021-01-01T00:00:00-0500

Send / Post Requests

Use POST (Send) requests to create or update records in PortalApp. The request body should be a JSON document following the resource schema.

Spring supports both creation of new records and updates to existing ones using the same endpoint. If an object with a matching ID already exists, the record will be updated; otherwise a new record will be created.

💡 Best Practice: Send more than one transaction per API call to avoid throttling limits and improve efficiency.

API Response Codes

The sending system must verify a successful API response code after every call. It is the sender's responsibility to ensure each API call receives a 2xx success response. Spring Systems does not log unsuccessful transactions.

Code RangeCategoryMeaning
1xxInformationalTransfer protocol-level information
2xxSuccess ✓Request was accepted successfully
3xxRedirectionClient must take additional action
4xxClient ErrorThe request has an issue on the sender side
5xxServer ErrorThe server encountered an error

Always check for a 200-level response to confirm successful transmission. Any non-2xx response means the transaction was not processed and must be retried.

Throttling

Spring Systems PortalApp uses API throttling to ensure availability and consistent throughput. Please transmit more than one transaction per API call to avoid throttling issues.

LimitDefault
Request Limit500 requests per 24 hours (86,400 seconds)
Transaction Limit5,000 created or updated transactions per period
Requested Entities Limit50,000 transactions/items per period (GET only)
Burst Time Period1 call per 1 second

Leaky Bucket:

In addition to the above, Spring uses a Leaky Bucket approach for burst control:

  • Bucket Capacity: 100 calls per endpoint per API user
  • Leak Rate: 1 call removed per second to rebuild capacity

If limits are reached, your API user is blocked until the next period. Contact your account manager to extend limits (additional charges may apply). Limits cannot be extended if you are sending only one transaction per call.

Orders

Within PortalApp, Orders can start as EDI 850 Purchase Orders, direct-to-consumer (D2C) orders from a retailer, or ecommerce orders from your own retail channel. Since many originate as EDI 850 purchase orders, po is used within field names.

Filterable Attributes:

po_createdpo_updatedpo_numpo_rel_numpo_acknowledge_statuspo_ship_statuspo_invoice_statuspo_ship_open_datepo_ship_close_datepo_idvendor_idretailer_idmark_for_location_idship_to_location_idpo_original_numpo_type

Endpoints:

POST/po-incoming/send/Create or update orders in PortalApp
GET/po-outgoing/export/Get purchase orders from PortalApp
GET/po-history-outgoing/export/Get order change history

Acknowledgements

Order acknowledgements are often required by retailers. Within PortalApp, an Order Acknowledgement serves the same purpose as an EDI 855 or 870 document.

Within PortalApp, order acknowledgements do not exist as their own entity but instead are status changes and updates to the Order.

Endpoints:

POST/acknowledgement-incoming/sendSend order acknowledgement

Shipments

Shipment records track the fulfilment of purchase orders. Spring Systems supports both inbound ship requests (940) and outbound shipment confirmations (856 ASN).

Endpoints:

GET/ship-request-outgoing/exportGet ship requests (940) from Spring
POST/ship-incoming/sendSend shipment to Spring (create/update)
GET/ship-outgoing/exportGet shipments from Spring
GET/ship-docs/generateGenerate shipping documents (labels, BOL)
GET/ship-docs/getdocumentdataRetrieve shipping document data

Invoices

Invoice records represent billing transactions (EDI 810) sent from vendors to retailers. Spring supports both creating invoices and retrieving existing ones.

Endpoints:

POST/invoice-incoming/sendCreate or update invoice in PortalApp
GET/invoice-outgoing/exportGet invoices from PortalApp

Product Catalog

The product catalog contains item-level data including descriptions, UPCs, dimensions, and pricing. Catalog data is used to fulfill orders accurately and meet retailer item setup requirements.

Endpoints:

POST/catalog-incoming/sendCreate or update products in catalog
GET/catalog-outgoing/exportGet products from catalog

Inventory

Inventory records track available stock levels per SKU and location. Keeping inventory current ensures accurate order fulfilment and prevents overselling.

Endpoints:

POST/inventory-incoming/sendCreate or update product inventory
GET/inventory-outgoing/exportGet inventory from PortalApp

Additional Transactions

Spring PortalApp also supports the following supplemental transaction types:

TransactionInbound EndpointOutbound Endpoint
Credit / Debit Notice/edi-additional-credit-debit-notice-incoming/send/edi-additional-credit-debit-notice-outgoing/export
Merchandise Return/edi-additional-merchandisereturn-incoming/send/edi-additional-merchandisereturn-outgoing/export
Org Address/edi-additional-org-address-incoming/send/edi-additional-org-address-outgoing/export
Payment Remittance/edi-additional-payment-remittance-incoming/send/edi-additional-payment-remittance-outgoing/export
Selling Report/edi-additional-selling-report-incoming/send/edi-additional-selling-report-outgoing/export
Stock Transfer Info/edi-additional-stock-transfer-info-incoming/send/edi-additional-stock-transfer-info-outgoing/export

Full Endpoint List

All PortalApp API endpoints. Your base URL will be provided by your Spring Systems project team.

Base URL:

PRODUCTIONProvided by Spring Systems
TESTProvided by Spring Systems
POSTacknowledgement-incoming/send
POSTcatalog-incoming/send
GETcatalog-outgoing/export
GETdocument-download/get
POSTedi-additional-credit-debit-notice-incoming/send
GETedi-additional-credit-debit-notice-outgoing/export
POSTedi-additional-merchandisereturn-incoming/send
GETedi-additional-merchandisereturn-outgoing/export
POSTedi-additional-org-address-incoming/send
GETedi-additional-org-address-outgoing/export
POSTedi-additional-payment-remittance-incoming/send
GETedi-additional-payment-remittance-outgoing/export
POSTedi-additional-selling-report-incoming/send
GETedi-additional-selling-report-outgoing/export
POSTedi-additional-stock-transfer-info-incoming/send
GETedi-additional-stock-transfer-info-outgoing/export
POSTedi-additional-stock-transfer-receipt-advice-incoming/send
POSTinventory-incoming/send
GETinventory-outgoing/export
POSTinvoice-incoming/send
GETinvoice-outgoing/export
GETpo-history-outgoing/export
POSTpo-incoming/send
GETpo-outgoing/export
GETship-docs/generate
GETship-docs/getdocumentdata
POSTship-incoming/send
GETship-outgoing/export
GETship-request-outgoing/export

Need API credentials or have questions?

Contact the Spring Systems support team to get your API username and key, or to discuss custom integration requirements.