Console API

Ads units

5 endpoints.

POST/api/v1/admin/businesses/{business_id}/ads/ad-sets/{ad_set_id}/units

Create an ad unit (creative + unit row, single transaction)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`ad_set_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonAdUnitCreateBody

Field	Type	Description
`photoIds`	`string (uuid)[] \| null`	string (uuid)[] \| null fields
`photoId`	`string (uuid) \| null`
`enabled`	`boolean`	default true
`displayIndex`	`integer \| null`
`name`	`string \| null`
`primaryText`	`string \| null`
`headline`	`string \| null`
`description`	`string \| null`
`destinationUrl`	`string \| null`
`callToActionType`	`string \| null`
`urlParams`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_AdUnitData_

Field Type Description

request_idrequired string

success true default true

datarequired

AdUnitData

AdUnitData fields

Field	Type	Description
`id`required	`string (uuid)`
`name`required	`string`
`primaryText`	`string \| null`
`headline`	`string \| null`
`description`	`string \| null`
`destinationUrl`	`string \| null`
`callToActionType`	`string \| null`
`urlParams`	`string \| null`
`effectiveHeadline`	`string`	default ""
`effectivePrimaryText`	`string`	default ""
`effectiveDescription`	`string`	default ""
`effectiveCta`	`string`	default "SHOP_NOW"
`effectiveLink`	`string`	default ""
`imageUrls`	`string[]`	string[] fields
`status`	`enum`	one of "leading", "neutral", "lagging", "off" · default "neutral"
`enabled`	`boolean`	default true
`isDraft`	`boolean`	default false
`externalPlatformAdId`	`string \| null`

metadata

ResponseMetadata | null

ResponseMetadata fields

Field Type Description

pagination

PaginationMetadata | null

PaginationMetadata fields

Field	Type	Description
`limit`required	`integer`
`next_cursor`	`string \| null`
`prev_cursor`	`string \| null`
`has_more`required	`boolean`
`has_prev`	`boolean`	default false
`total_count`	`integer \| null`

status_counts

object | null

object | null fields

Map of string to integer

lifecycle_counts

LifecycleCounts | null

LifecycleCounts fields

Field	Type	Description
`lead`	`integer`	default 0
`prospect`	`integer`	default 0
`customer`	`integer`	default 0
`former_customer`	`integer`	default 0

classification_counts

ClassificationCounts | null

ClassificationCounts fields

Field	Type	Description
`signal`	`object`	object fields Nested object (not expanded)
`touch`	`object`	object fields Nested object (not expanded)
`stage`	`object`	object fields Nested object (not expanded)

meta

ResponseMeta | null

ResponseMeta fields

Field	Type	Description
`total`	`integer \| null`
`total_count`	`integer \| null`
`page`	`integer \| null`
`per_page`	`integer \| null`

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

PATCH/api/v1/admin/businesses/{business_id}/ads/units/{unit_id}

Toggle, swap photos, reorder

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`unit_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonAdUnitPatchBody

Field	Type	Description
`enabled`	`boolean \| null`
`photoIds`	`string (uuid)[] \| null`	string (uuid)[] \| null fields
`photoId`	`string (uuid) \| null`
`displayIndex`	`integer \| null`
`name`	`string \| null`
`primaryText`	`string \| null`
`headline`	`string \| null`
`description`	`string \| null`
`destinationUrl`	`string \| null`
`callToActionType`	`string \| null`
`urlParams`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_AdUnitData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`AdUnitData`	AdUnitData fields AdUnitData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

DELETE/api/v1/admin/businesses/{business_id}/ads/units/{unit_id}

Soft-delete an ad unit

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`unit_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

204Successful Response

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/ads/units/{unit_id}/duplicate

Duplicate an ad unit (photos + copy overrides; clone starts disabled)

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`unit_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

201Successful Response

application/jsonSuccessResponse_AdUnitData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`AdUnitData`	AdUnitData fields AdUnitData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/businesses/{business_id}/ads/units/{unit_id}/generate-copy

LLM-generate primary text for one ad unit (KS-2013 per-ad copy)

Unit-scoped successor of ``POST /ad-sets/{id}/generate-ad-copy``: grounded in the unit's creative (existing primary text, CTA, link) plus its set/campaign/business context. Same response shape — the FE drops the text into the unit's primary-text field.

Parameters

Name	In	Type
`business_id`required	path	`string (uuid)`
`unit_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_AdCopyGenerationData_

Field Type Description

request_idrequired string

success true default true

datarequired

AdCopyGenerationData

AdCopyGenerationData fields

Field	Type	Description
`adCopy`required	`string`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.