stable · api · 0.1.0

Define an immutable advertising Placement

POST /api/v1/advertising/placements

Capability Domain: Advertising Sponsorship

Authentication

projectCredential (advertising:placements)

Scope: advertising:placements

Parameters and request body

X-Correlation-ID — header, optional
X-Correlation-ID schema
```
{
    "type": "string",
    "format": "uuid"
}
```

Request schema

application/json

application/json request schema

{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "code",
        "idempotency_key"
    ],
    "properties": {
        "code": {
            "type": "string",
            "maxLength": 120
        },
        "image_preset_ids": {
            "type": "array",
            "uniqueItems": true,
            "items": {
                "type": "string",
                "format": "uuid"
            }
        },
        "native_fields": {
            "type": "array",
            "uniqueItems": true,
            "items": {
                "type": "string",
                "enum": [
                    "title",
                    "body",
                    "call_to_action"
                ]
            }
        },
        "targeting_schema": {
            "type": "object"
        },
        "idempotency_key": {
            "type": "string",
            "maxLength": 180
        }
    }
}

application/json request example

{
    "code": "article-sidebar",
    "image_preset_ids": [
        "8a000000-0000-4000-8000-000000000101"
    ],
    "native_fields": [
        "title",
        "body",
        "call_to_action"
    ],
    "targeting_schema": {
        "section": [
            "technology",
            "business"
        ]
    },
    "idempotency_key": "placement-article-sidebar-v1"
}

Responses and errors

Status	Description
`200`	Immutable Placement version
`401`	Invalid or revoked Project Credential
`403`	Project Credential lacks the required scope
`422`	The Placement contract is invalid

200 schema

200 response schema

{
    "type": "object",
    "required": [
        "data"
    ],
    "properties": {
        "data": {
            "type": "object",
            "required": [
                "id",
                "code",
                "version"
            ],
            "properties": {
                "id": {
                    "type": "string",
                    "format": "uuid"
                },
                "code": {
                    "type": "string"
                },
                "version": {
                    "type": "integer",
                    "minimum": 1
                }
            }
        }
    }
}

401 schema

401 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

403 schema

403 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

200 example

200 response example

{
    "data": {
        "id": "8a000000-0000-4000-8000-000000000102",
        "code": "article-sidebar",
        "version": 1
    }
}

Idempotency

The body idempotency_key safely replays the same Placement version.