POST /api/v1/brand-lift-studies/{studyId}/quotes
Run brand lift studies / quotes
Authenticated and advertiser scoped. Cross-tenant resource access returns 404. Product/channel entitlements also apply.
Requires an authenticated human with supplier:authorize permission. Delegated agents cannot perform this operator action.
The request schema is generated from the runtime Zod input validator. Cross-field refinements and state-dependent constraints are additionally enforced by the API.
Request
HTTP
POST /api/v1/brand-lift-studies/{studyId}/quotesUse the configured API origin. Private requests require a verified Bearer credential; an agent mutation can additionally require exact approval headers. Authentication guide →
| Parameter | Location | Required | Description |
|---|---|---|---|
studyId | path | Yes | |
Idempotency-Key | header | Yes | Retain the same key when retrying the same request. Replay and collision behavior are endpoint-specific; see this operation’s description. |
Parameter schemas
JSON Schema
[
{
"name": "studyId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"description": "Retain the same key when retrying the same request. Replay and collision behavior are endpoint-specific; see this operation’s description.",
"schema": {
"type": "string",
"format": "uuid"
}
}
]Request body contract
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"quote": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"operator-recorded-supplier-quote",
"sandbox-fixture"
]
},
"specDigest": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"providerAccountId": {
"type": "string",
"format": "uuid"
},
"connectionRevision": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
{
"type": "null"
}
]
},
"configuredIdentityDigest": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
{
"type": "null"
}
]
},
"dossierRevision": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
{
"type": "null"
}
]
},
"dossierDigest": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
{
"type": "null"
}
]
},
"issuedAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"supplier": {
"type": "object",
"properties": {
"quoteReference": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$"
},
"evidence": {
"type": "object",
"properties": {
"artifactId": {
"type": "string",
"format": "uuid"
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"artifactId",
"sha256"
],
"additionalProperties": false
},
"contractEvidence": {
"type": "object",
"properties": {
"artifactId": {
"type": "string",
"format": "uuid"
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"artifactId",
"sha256"
],
"additionalProperties": false
},
"currency": {
"type": "string",
"enum": [
"GBP",
"USD",
"EUR"
]
},
"subtotalMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"taxMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"totalMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"maximumLiabilityMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"maximumCancellationLiabilityMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"billingTrigger": {
"type": "string",
"enum": [
"order-acceptance",
"draft-creation",
"tracking-setup",
"launch",
"invoice"
]
},
"includedScope": {
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"required": [
"quoteReference",
"evidence",
"contractEvidence",
"currency",
"subtotalMinor",
"taxMinor",
"totalMinor",
"maximumLiabilityMinor",
"maximumCancellationLiabilityMinor",
"billingTrigger",
"includedScope"
],
"additionalProperties": false
},
"customer": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"const": "GBP"
},
"subtotalMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"taxMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"totalMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"maximumCommitmentMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"cancellationMaximumMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"refundTerms": {
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"required": [
"currency",
"subtotalMinor",
"taxMinor",
"totalMinor",
"maximumCommitmentMinor",
"cancellationMaximumMinor",
"refundTerms"
],
"additionalProperties": false
},
"foreignCurrencyCoverageEvidence": {
"anyOf": [
{
"type": "object",
"properties": {
"artifactId": {
"type": "string",
"format": "uuid"
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"artifactId",
"sha256"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"source",
"specDigest",
"providerAccountId",
"connectionRevision",
"configuredIdentityDigest",
"dossierRevision",
"dossierDigest",
"issuedAt",
"expiresAt",
"supplier",
"customer",
"foreignCurrencyCoverageEvidence"
],
"additionalProperties": false
}
},
"required": [
"expectedRevision",
"quote"
],
"additionalProperties": false
}
}
}
}Responses
Reference schemas resolve through the downloadable OpenAPI components. The specification marks unmodeled success payloads; an unrestricted payload is not a promise that arbitrary fields exist.
400Invalid request or unsupported fields
Response contract
{
"description": "Invalid request or unsupported fields",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}401Missing or invalid authentication
Response contract
{
"description": "Missing or invalid authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}403Permission or product scope refused
Response contract
{
"description": "Permission or product scope refused",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}404Route or tenant-scoped resource not found
Response contract
{
"description": "Route or tenant-scoped resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}409State, revision, approval, funding or idempotency conflict
Response contract
{
"description": "State, revision, approval, funding or idempotency conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}422Supplier configuration, capability or upstream refusal
Response contract
{
"description": "Supplier configuration, capability or upstream refusal",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}429Rate limit reached; wait before retrying
Response contract
{
"description": "Rate limit reached; wait before retrying",
"headers": {
"x-ratelimit-limit": {
"description": "Maximum requests permitted in the current rate-limit window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-remaining": {
"description": "Requests remaining in the current window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-reset": {
"description": "Seconds until the current rate-limit window resets.",
"schema": {
"type": "integer"
}
},
"retry-after": {
"description": "Minimum seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}500Internal error; inspect state before retrying a mutation
Response contract
{
"description": "Internal error; inspect state before retrying a mutation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}503Dependency or authentication verifier unavailable
Response contract
{
"description": "Dependency or authentication verifier unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}2XXSuccessful response. Response schema completeness: unmodeled. The request contract is complete; nested service payloads are not yet fully modeled in OpenAPI. Inspect returned fields before generating a typed SDK.
Response contract
{
"description": "Successful response. Response schema completeness: unmodeled. The request contract is complete; nested service payloads are not yet fully modeled in OpenAPI. Inspect returned fields before generating a typed SDK.",
"headers": {
"x-ratelimit-limit": {
"description": "Maximum requests permitted in the current rate-limit window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-remaining": {
"description": "Requests remaining in the current window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-reset": {
"description": "Seconds until the current rate-limit window resets.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {}
}
}
}Operation constraints
Machine-readable metadata
{
"x-response-schema-completeness": "unmodeled",
"x-rate-limit": {
"requests": 300,
"windowMilliseconds": 60000,
"key": "request IP",
"headers": [
"x-ratelimit-limit",
"x-ratelimit-remaining",
"x-ratelimit-reset"
]
},
"x-idempotency": {
"policy": "required",
"note": "There is no universal Idempotency-Key middleware. Only the documented endpoint mechanisms protect retries."
},
"x-human-only": true,
"x-required-human-permissions": [
"supplier:authorize"
]
}Complete operation
OpenAPI
{
"operationId": "post_api_v1_brand_lift_studies_studyId_quotes",
"summary": "Run brand lift studies / quotes",
"description": "Authenticated and advertiser scoped. Cross-tenant resource access returns 404. Product/channel entitlements also apply.\n\nRequires an authenticated human with supplier:authorize permission. Delegated agents cannot perform this operator action.\n\nThe request schema is generated from the runtime Zod input validator. Cross-field refinements and state-dependent constraints are additionally enforced by the API.",
"tags": [
"Brand lift studies"
],
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "studyId",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"description": "Retain the same key when retrying the same request. Replay and collision behavior are endpoint-specific; see this operation’s description.",
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expectedRevision": {
"type": "integer",
"exclusiveMinimum": 0
},
"quote": {
"type": "object",
"properties": {
"source": {
"type": "string",
"enum": [
"operator-recorded-supplier-quote",
"sandbox-fixture"
]
},
"specDigest": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"providerAccountId": {
"type": "string",
"format": "uuid"
},
"connectionRevision": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
{
"type": "null"
}
]
},
"configuredIdentityDigest": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
{
"type": "null"
}
]
},
"dossierRevision": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
{
"type": "null"
}
]
},
"dossierDigest": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
{
"type": "null"
}
]
},
"issuedAt": {
"type": "string",
"format": "date-time"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"supplier": {
"type": "object",
"properties": {
"quoteReference": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$"
},
"evidence": {
"type": "object",
"properties": {
"artifactId": {
"type": "string",
"format": "uuid"
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"artifactId",
"sha256"
],
"additionalProperties": false
},
"contractEvidence": {
"type": "object",
"properties": {
"artifactId": {
"type": "string",
"format": "uuid"
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"artifactId",
"sha256"
],
"additionalProperties": false
},
"currency": {
"type": "string",
"enum": [
"GBP",
"USD",
"EUR"
]
},
"subtotalMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"taxMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"totalMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"maximumLiabilityMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"maximumCancellationLiabilityMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"billingTrigger": {
"type": "string",
"enum": [
"order-acceptance",
"draft-creation",
"tracking-setup",
"launch",
"invoice"
]
},
"includedScope": {
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"required": [
"quoteReference",
"evidence",
"contractEvidence",
"currency",
"subtotalMinor",
"taxMinor",
"totalMinor",
"maximumLiabilityMinor",
"maximumCancellationLiabilityMinor",
"billingTrigger",
"includedScope"
],
"additionalProperties": false
},
"customer": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"const": "GBP"
},
"subtotalMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"taxMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"totalMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"maximumCommitmentMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"cancellationMaximumMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647
},
"refundTerms": {
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"required": [
"currency",
"subtotalMinor",
"taxMinor",
"totalMinor",
"maximumCommitmentMinor",
"cancellationMaximumMinor",
"refundTerms"
],
"additionalProperties": false
},
"foreignCurrencyCoverageEvidence": {
"anyOf": [
{
"type": "object",
"properties": {
"artifactId": {
"type": "string",
"format": "uuid"
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"artifactId",
"sha256"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"source",
"specDigest",
"providerAccountId",
"connectionRevision",
"configuredIdentityDigest",
"dossierRevision",
"dossierDigest",
"issuedAt",
"expiresAt",
"supplier",
"customer",
"foreignCurrencyCoverageEvidence"
],
"additionalProperties": false
}
},
"required": [
"expectedRevision",
"quote"
],
"additionalProperties": false
}
}
}
},
"responses": {
"400": {
"description": "Invalid request or unsupported fields",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing or invalid authentication",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Permission or product scope refused",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Route or tenant-scoped resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "State, revision, approval, funding or idempotency conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Supplier configuration, capability or upstream refusal",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate limit reached; wait before retrying",
"headers": {
"x-ratelimit-limit": {
"description": "Maximum requests permitted in the current rate-limit window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-remaining": {
"description": "Requests remaining in the current window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-reset": {
"description": "Seconds until the current rate-limit window resets.",
"schema": {
"type": "integer"
}
},
"retry-after": {
"description": "Minimum seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal error; inspect state before retrying a mutation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "Dependency or authentication verifier unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"2XX": {
"description": "Successful response. Response schema completeness: unmodeled. The request contract is complete; nested service payloads are not yet fully modeled in OpenAPI. Inspect returned fields before generating a typed SDK.",
"headers": {
"x-ratelimit-limit": {
"description": "Maximum requests permitted in the current rate-limit window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-remaining": {
"description": "Requests remaining in the current window.",
"schema": {
"type": "integer"
}
},
"x-ratelimit-reset": {
"description": "Seconds until the current rate-limit window resets.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {}
}
}
}
},
"x-response-schema-completeness": "unmodeled",
"x-rate-limit": {
"requests": 300,
"windowMilliseconds": 60000,
"key": "request IP",
"headers": [
"x-ratelimit-limit",
"x-ratelimit-remaining",
"x-ratelimit-reset"
]
},
"x-idempotency": {
"policy": "required",
"note": "There is no universal Idempotency-Key middleware. Only the documented endpoint mechanisms protect retries."
},
"x-human-only": true,
"x-required-human-permissions": [
"supplier:authorize"
]
}