One button.
Ready for review.

1. Create a connection.

Start with a test key. Test items are saved and clearly labeled in your inbox. Create a separate live connection when your team is ready.

Checking your account…

2. Send the item from your server.

Your button calls your existing backend, which checks the user’s permission to send the item and calls this API. Keep the key on the server. The required fields are externalId, title and location.

curl https://surplus.com/api/v1/salvage/submissions \
  -H "Authorization: Bearer $SURPLUS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "externalId": "claim-1048/item-1",
    "title": "Standby diesel generator",
    "location": "Columbia, MO",
    "claim": "1048",
    "condition": "Not confirmed",
    "notes": "Inspection required before removal.",
    "media": [{
      "kind": "photo",
      "url": "https://files.example.com/generator.jpg",
      "name": "Generator overview"
    }]
  }'

The example file URL is illustrative. Supply links your adjustors can open. Send one request per item and use a stable reference unique within the connection, such as claim number plus item number.

3. Open the private draft.

A successful request returns the submission ID, status and reviewUrl. Show “Sent to Surplus” and an “Open in Surplus” link in your application. The adjustor signs in to the account that owns the connection to review it.

{
  "submission": {
    "id": "…",
    "status": "draft",
    "mode": "test",
    "reviewUrl": "https://surplus.com/salvage/submissions/…"
  },
  "replayed": false
}

Use GET /api/v1/salvage/submissions/{id} with the same connection’s key to read the current status. A review remains private; it does not publish the item or send buyer emails.

Built for a second click.

Sending identical details with the same externalId returns the existing submission. Different details with that reference return a 409 conflict, preserving the original. Replacing a key preserves these references and your submissions.

201 means created; 200 means an identical retry was recovered. Retry network errors, 429 and 503 using the same details and externalId. Respect Retry-After. Correct 400, 401, 409, 413, 415 and 422 responses before retrying.

Files and limits.

Include up to 30 HTTPS photo, video or document links in a 64 KB JSON request. Links are saved privately; files remain in your system and are not downloaded or analyzed. Use stable access-controlled links that the reviewing adjustor can open. Expiring links may need replacement through a new submission.

Each connection supports 60 API requests per minute. Keys expire after one year and can be replaced or revoked here. Each connection is owned by one Surplus account; shared company roles and automatic publishing are outside this first version.