API Documentation
Spring Systems PortalApp Web API — endpoint reference for integrating external applications with Spring transactional data.
View full interactive docs on readme.ioIntroduction
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:
Pull data from PortalApp into your system.
Create or update records in PortalApp.
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/keygoeshereExample: 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 integerxxx_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-29Operator Definitions:
| Operator | Description |
|---|---|
| eq | equal |
| neq | not equal |
| lt | less than |
| lte | less than or equal |
| gt | greater than |
| gte | greater than or equal |
| like | like (partial match) |
| in | in list |
| nin | not 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-0500Send / 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 Range | Category | Meaning |
|---|---|---|
| 1xx | Informational | Transfer protocol-level information |
| 2xx | Success ✓ | Request was accepted successfully |
| 3xx | Redirection | Client must take additional action |
| 4xx | Client Error | The request has an issue on the sender side |
| 5xx | Server Error | The 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.
| Limit | Default |
|---|---|
| Request Limit | 500 requests per 24 hours (86,400 seconds) |
| Transaction Limit | 5,000 created or updated transactions per period |
| Requested Entities Limit | 50,000 transactions/items per period (GET only) |
| Burst Time Period | 1 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.
Pagination
Spring uses a cursor-based pagination approach for GET requests. Your initial API response will include:
- Total records to be returned
- Default page limit
- Maximum allowed limit override
- A
next_cursorvalue when total results exceed the limit - A pre-built next-page URL for convenience
To override the per-page quantity, pass pagination.limit/<number> in your call (up to the max value). See the Response Metadata section for full detail.
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_typeEndpoints:
/po-incoming/send/Create or update orders in PortalApp/po-outgoing/export/Get purchase orders from PortalApp/po-history-outgoing/export/Get order change historyAcknowledgements
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:
/acknowledgement-incoming/sendSend order acknowledgementShipments
Shipment records track the fulfilment of purchase orders. Spring Systems supports both inbound ship requests (940) and outbound shipment confirmations (856 ASN).
Endpoints:
/ship-request-outgoing/exportGet ship requests (940) from Spring/ship-incoming/sendSend shipment to Spring (create/update)/ship-outgoing/exportGet shipments from Spring/ship-docs/generateGenerate shipping documents (labels, BOL)/ship-docs/getdocumentdataRetrieve shipping document dataInvoices
Invoice records represent billing transactions (EDI 810) sent from vendors to retailers. Spring supports both creating invoices and retrieving existing ones.
Endpoints:
/invoice-incoming/sendCreate or update invoice in PortalApp/invoice-outgoing/exportGet invoices from PortalAppProduct 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:
/catalog-incoming/sendCreate or update products in catalog/catalog-outgoing/exportGet products from catalogInventory
Inventory records track available stock levels per SKU and location. Keeping inventory current ensures accurate order fulfilment and prevents overselling.
Endpoints:
/inventory-incoming/sendCreate or update product inventory/inventory-outgoing/exportGet inventory from PortalAppAdditional Transactions
Spring PortalApp also supports the following supplemental transaction types:
| Transaction | Inbound Endpoint | Outbound 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:
acknowledgement-incoming/sendcatalog-incoming/sendcatalog-outgoing/exportdocument-download/getedi-additional-credit-debit-notice-incoming/sendedi-additional-credit-debit-notice-outgoing/exportedi-additional-merchandisereturn-incoming/sendedi-additional-merchandisereturn-outgoing/exportedi-additional-org-address-incoming/sendedi-additional-org-address-outgoing/exportedi-additional-payment-remittance-incoming/sendedi-additional-payment-remittance-outgoing/exportedi-additional-selling-report-incoming/sendedi-additional-selling-report-outgoing/exportedi-additional-stock-transfer-info-incoming/sendedi-additional-stock-transfer-info-outgoing/exportedi-additional-stock-transfer-receipt-advice-incoming/sendinventory-incoming/sendinventory-outgoing/exportinvoice-incoming/sendinvoice-outgoing/exportpo-history-outgoing/exportpo-incoming/sendpo-outgoing/exportship-docs/generateship-docs/getdocumentdataship-incoming/sendship-outgoing/exportship-request-outgoing/exportNeed API credentials or have questions?
Contact the Spring Systems support team to get your API username and key, or to discuss custom integration requirements.