Integration summary

1. Magic Link — let users jump into their branded Rampart portal from your app, without any passwords.
2. Spend File Transmission — send invoice/spend files so Rampart can analyze spend and report savings opportunities.

​

Magic Link

​

Flow

1. Add a button in your app (e.g., “Open GPO Portal”).
2. Your backend calls Rampart’s Magic Link endpoint with the client ID & the email of that user (ID that refers to the organization this user is part of) you use internally for this integration.
3. The API returns a signed, short‑lived URL.
4. Redirect the user to that URL.
5. The user lands in your Rampart instance.

​

Spend File Transmission

​

Flow

1. Discover jobs on your schedule (long‑polling or a cron). We offer multiple endpoints to facilitate this:
   • List all jobs
   • List pending jobs
   • Get next job
2. Read the job and gather all of the spend files that match the query in the job object. Job Object
   Copy

   {
     "client": "<client-id>",
     "job_id": "<job-id>",
     "type": "INCREMENTAL | HISTORICAL",
     "from": "2024-01-01T00:00:00Z",
     "to": "2024-01-31T23:59:59Z"
   }
   

   • client: client identifier you use internally for this client. Same one you pass to the Magic Link endpoint.
   • job_id: unique job ID.
   • type:
     • HISTORICAL: First, full upload for a given client. We usually ask for past 12 months of spend data.
     • INCREMENTAL: Ongoing, smaller uploads. Just new spend data since the last job.
   • from: start of range.
   • to: end of range (optional; if omitted, defaults to today).
3. Request presigned upload URLs for the files in this batch from Rampart Storage using the Get upload URLs endpoint.
   • You can set the URL expiry to match your upload window.
   • Batching:
     • Request up to 1,000 presigned URLs (1,000 files) per call (max).
     • For jobs with more than 1,000 files: get presigned URLs for batch 1, upload batch 1, then repeat for batch 2, etc., until all files are uploaded.
   Example Request
   Copy

   curl -X POST "https://api.rampart.com/v2/storage/upload-urls" \
       -H "Authorization: Bearer $API_KEY" \
       -H "Content-Type: application/json" \
       -d '{
       "job_id": "<job-id>",
       "files": [
           { "filename": "invoices-1.csv", "vendor_hint": "Acme Corp" },
           { "filename": "invoices-2.csv" }
       ],
       "expires_in": 900
       }'
   

   • job_id: The job you are uploading files for (required).
   • files: Array of files to upload. Each object must include filename (required). Use only the base file name (e.g., invoices-1.csv) — do not include any folder paths. We read files directly under your assigned folder and ignore subdirectories. You may optionally include vendor_hint (string) to help Rampart identify the vendor or context for the file.
   • expires_in: (optional) Number of seconds the presigned URLs should remain valid (min: 1, max: 604800).
4. Upload each file directly to S3 using the returned presigned URLs. Use plain HTTP PUT. The URL contains all auth required. Example (PUT file bytes)
   Copy

   curl -X PUT "<PRESIGNED_URL_FOR_invoices-1.csv>" \
     -H "Content-Type: text/csv" \
     --data-binary "@./invoices-1.csv"
   

   Basic Node/Fetch variant
   Copy

   await fetch(presignedUrl, {
     method: "PUT",
     headers: { "Content-Type": "text/csv" },
     body: fs.createReadStream("./invoices-1.csv")
   });
   

5. After all files in the batch are uploaded, you can use the Complete job endpoint to mark the job as complete. Example Request
   Copy

    curl --request POST \
    --url https://api.rampartcorporation.com/v2/job/complete/{jobId} \
    --header 'Authorization: Bearer <API_KEY>'
   

6. Rampart will process your uploads in the background and update the client’s portal with savings opportunities found.