Skip to main content
POST
/
proposals
Create storefront proposal
curl --request POST \
  --url https://api.interchange.io/api/v2/storefront/proposals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "operatorId": "acme",
  "label": "Acme Q3 RFP — CTV",
  "expiresAt": "2023-11-07T05:31:56Z",
  "discoveryId": "disc_a1b2c3",
  "proposalId": "proposal_abc123"
}
'
{
  "id": 123,
  "proposalCode": "PRP-XK4A29",
  "operatorId": "<string>",
  "label": "<string>",
  "notes": "<string>",
  "expiresAt": "2023-11-07T05:31:56Z",
  "proposalId": "<string>",
  "discoverySessionId": "<string>",
  "snapshot": {
    "products": [
      {
        "productId": "prod_123",
        "name": "Premium CTV Inventory - Sports",
        "channel": "ctv",
        "formatTypes": [
          "video",
          "15s",
          "30s"
        ],
        "cpm": 12.5,
        "salesAgentId": "<string>",
        "salesAgentName": "<string>",
        "storefrontId": "<string>",
        "storefrontName": "<string>",
        "description": "<string>",
        "deliveryType": "guaranteed",
        "briefRelevance": "<string>",
        "productCard": {
          "formatId": {
            "agentUrl": "<string>",
            "id": "<string>"
          },
          "manifest": {}
        },
        "productCardDetailed": {
          "formatId": {
            "agentUrl": "<string>",
            "id": "<string>"
          },
          "manifest": {}
        },
        "pricingOptions": [
          {
            "pricingOptionId": "<string>",
            "pricingModel": "<string>",
            "isFixed": true,
            "rate": 123,
            "floorPrice": 123,
            "fixedPrice": 123,
            "currency": "<string>"
          }
        ],
        "estimatedExposures": 0,
        "forecast": {},
        "publisherProperties": [
          {
            "publisherDomain": "<string>",
            "propertyType": "<string>",
            "name": "<string>",
            "selectionType": "<string>",
            "identifiers": [
              {}
            ]
          }
        ],
        "isSandbox": true
      }
    ],
    "proposals": [
      {
        "proposalId": "<string>",
        "name": "<string>",
        "allocations": [
          {
            "productId": "<string>",
            "allocationPercentage": 50,
            "pricingOptionId": "<string>",
            "rationale": "<string>",
            "sequence": 0,
            "tags": [
              "<string>"
            ]
          }
        ],
        "description": "<string>",
        "briefAlignment": "<string>",
        "salesAgentId": "<string>",
        "salesAgentName": "<string>",
        "storefrontId": "<string>",
        "storefrontName": "<string>",
        "expiresAt": "<string>",
        "totalBudgetGuidance": {
          "min": 123,
          "recommended": 123,
          "max": 123,
          "currency": "<string>"
        }
      }
    ]
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "createdBy": "<string>",
  "firstViewedAt": "2023-11-07T05:31:56Z",
  "lastViewedAt": "2023-11-07T05:31:56Z",
  "redeemedAt": "2023-11-07T05:31:56Z",
  "redeemedInMediaBuyId": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.interchange.io/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

API key or access token

Body

application/json

Request body for creating a storefront proposal

​
operatorId
string
required

Buyer brand identifier (operator) the proposal is bound to. Resolved via brand.json on redemption.

Required string length: 1 - 255
Example:

"acme"

​
label
string
required

Seller's internal label for the proposal

Required string length: 1 - 255
Example:

"Acme Q3 RFP — CTV"

​
expiresAt
string<date-time>
required

When the proposal code expires (ISO 8601). Server enforces this is no later than the underlying proposal.expiresAt.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
​
discoveryId
string
required

Discovery session id from a recent discover-products call. The server reads the cached snapshot for this session and persists it as the frozen offer. The session must have been scoped to this seller and restricted to its storefront sales agents.

Required string length: 1 - 255
Example:

"disc_a1b2c3"

​
proposalId
string
required

Which proposal from the discovery snapshot to save and bind to the proposal code.

Required string length: 1 - 255
Example:

"proposal_abc123"

​
notes
string

Free-form notes about the offline RFP

Maximum string length: 4000

Response

Create storefront proposal

A persisted storefront proposal

​
id
integer
required

Proposal row id

Required range: x <= 9007199254740991
​
proposalCode
string
required

Short shareable handle. Sellers give this to buyers; buyers pass it to discover_products.

Example:

"PRP-XK4A29"

​
operatorId
string
required

Buyer brand binding

​
label
string
required
​
notes
string | null
required
​
status
enum<string>
required

Proposal lifecycle status. 'active': available to redeem. 'redeemed': buyer has applied it to a media buy. 'expired': past TTL. 'revoked': seller withdrew.

Available options:
active,
redeemed,
expired,
revoked
​
expiresAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
​
proposalId
string
required

The protocol-level proposalId from the saved discovery snapshot

​
discoverySessionId
string
required

Discovery session id this proposal was captured from (for traceability)

​
snapshot
object
required

The frozen products + proposals returned to the buyer on redemption

​
createdAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
​
createdBy
string
required
​
firstViewedAt
string<date-time> | null
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
​
lastViewedAt
string<date-time> | null
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
​
redeemedAt
string<date-time> | null
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
​
redeemedInMediaBuyId
string | null
required