Short List Referral
Approved partners submit brand-originated fulfillment opportunities to Slotted using a versioned envelope. Partner data is sourced input — the brand claims, confirms, and completes the RFP in Slotted.
At a glance
What it does
Lets approved partners send a brand's fulfillment search into Slotted, including recommended providers when you have them. Slotted turns that into a claimable opportunity for the brand.
Who it's for
Ecosystem partners who refer brands looking for 3PL fulfillment — matchmakers, marketing platforms, and similar referral channels. Integration is usually done by your engineering team; this guide is written so non-technical stakeholders can understand the flow first.
How to use it
- Ask Slotted for sandbox (and later production) API keys — they are invite-only and are not created on this site.
- Collect the brand's consent, then submit one opportunity per project via the API.
- Slotted emails the brand a claim link. The brand finishes the RFP inside Slotted; you receive accept / replay / review responses only (no claim or award polling in v1).
Contact
For access or questions, email admin@slotted.com.
Authentication
Every request requires:
| Header | Description |
|---|---|
x-api-access-key | Public key id (pk_test_… / pk_live_…) |
x-api-secret-key | Secret shown once at create/rotate |
Partner identity comes from the API key context. Sending partnerId in the body is rejected.
Endpoint
POST /api/v1/partner/opportunities Content-Type: application/json
Full schemas and examples: Short List Referral API reference.
Required envelope fields
schemaVersion:slotted.opportunity.v1externalOpportunityId— your idempotency keyprojectName,submissionIntent: STANDARD_RFP- Brand + primary contact
- Consent attestation (all booleans must be literally true)
- Commercial terms + recommended providers array (may be empty)
Idempotency
Same authenticated partner + same externalOpportunityId = replay (200 with the original acceptance body). A different external id creates a separate opportunity/project after claim.
Responses you will receive
| Status | Meaning |
|---|---|
201 accepted | Claim invite queued when the claim gate passes |
200 replay | Idempotent duplicate |
202 needs_admin_review | Held for Slotted review (e.g. commercial terms) |
400 validation_rejected | Stable error codes; nothing accepted |
What you will never receive (v1)
Claim status, brand workspace details, RFP release state, provider participation, proposals, pricing, awards, or payouts. No polling API in v1.
Commercial models
Your commercial terms must match the model Slotted configured for your partnership:
- Matchmaker (rev-share): submit a non-zero
providerRevSharePercentwith an allowedrevShareBasis. Pilot validation may use REVIEW mode first. See the matchmaker example on the reference page. - Marketing platform (no rev-share): submit
providerRevSharePercent: "0",revShareBasis: null,providerPays: false. See the marketing-platform example on the reference page.
Consent
You must collect explicit consent before submission. Brands accept Slotted Terms in Slotted — partners cannot accept T&Cs on the brand's behalf.