MadHive Advertiser API
The advertiser API from MadHive — 1 operation(s) for advertiser.
OpenAPI Specification
openapi: 3.2.0
info:
title: Madhive Advertiser API
version: 1.0.0
description: "The Madhive API provides a comprehensive interface for digital advertising clients and services.\n\n## Authentication\nThis API uses OAuth 2.0 client credentials flow for authentication. To access protected endpoints:\n\n1. **Obtain an access token** using the `/oauth/token` endpoint with your client credentials\n2. **Include the token** in subsequent API requests using the `Authorization` header:\n ```\n Authorization: Bearer YOUR_ACCESS_TOKEN_HERE\n ```\n\n### Token Usage Example\n```bash\n# Get access token\ncurl -X POST \"https://api2.madhive.com/oauth/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET\"\n\n# Use token in API requests\ncurl -H \"Authorization: Bearer YOUR_ACCESS_TOKEN_HERE\" \\\n \"https://api2.madhive.com/v1/campaigns\"\n```\n\n**Note:** Access tokens have an expiration time. You should handle token refresh in your application logic.\n"
servers:
- url: https://api2.madhive.com/api
description: apigee
tags:
- name: advertiser
paths:
/v1/advertisers:
get:
tags:
- advertiser
summary: Receive the list of advertisers, IDs, associated agency, domain, category and external ID for your org.
description: Receive the list of advertisers, IDs, associated agency, domain, category and external ID for your org.
operationId: getAdvertisers
parameters:
- $ref: '#/components/parameters/X-Cloud-Trace-Context'
- in: query
name: page_size
description: number of advertisers per page (default 100, max 10000)
required: false
schema:
type: integer
default: 100
maximum: 10000
- in: query
name: offset
description: 'Optional page selector RELATIVE to page_token: 1 = next page (the default when a page_token is supplied), -1 = previous page, 0 = reload the current page. Has no effect without page_token.
'
required: false
schema:
type: integer
- in: query
name: page_token
description: 'Opaque cursor from the previous response''s pagination.pageToken. Pass it alone to fetch the next page; pagination is cursor-based and offset defaults to the next page when a page_token is supplied.
'
required: false
schema:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/AdvertiserListResponse'
examples:
response:
value:
transaction:
id: 4af459ff8e1a36b6bb74fb88f1a02477
taskId: '14158884487309867565'
advertisers:
- id: a8MWQ2v4ZceGhsku2P5amaOXCnwe
name: Test Advertiser
customerExternalId: adv-123456
domain: madhive.com
iabCategory: IAB1
associatedAgency: f9aWQ2v4ZceGhsku2P5amaOXCieu
'400':
description: Invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
$ref: '#/components/responses/401Unauthorized'
security:
- oauth2: []
post:
tags:
- advertiser
summary: Two step process of creating an advertiser and then assigning it to a campaign
description: Two step process of creating an advertiser and then assigning it to a campaign
operationId: createAdvertiser
parameters:
- $ref: '#/components/parameters/X-Cloud-Trace-Context'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdvertiserRequest'
description: advertiser creation
required: true
responses:
'200':
description: advertiser created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AdvertiserResponse'
examples:
response:
value:
id: 4gV9KIg6E2kX3d6117OO8rgseJRl
customerExternalId: adv-123456
name: Madhive
adDomain: madhive.com
iabCategory: IAB1
status: READY
transaction:
id: 4af459ff8e1a36b6bb74fb88f1a02477
created: '2030-11-02T15:04:00Z'
'400':
description: Invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
error: 'name: cannot be empty'
status: ERROR
transaction:
id: 4af459ff8e1a36b6bb74fb88f1a02477
taskId: '14158884487309867565'
'401':
$ref: '#/components/responses/401Unauthorized'
security:
- oauth2: []
components:
schemas:
Advertiser:
type: object
required:
- name
- domain
- iabCategory
- status
properties:
id:
type: string
x-go-type-skip-optional-pointer: true
x-oapi-codegen-extra-tags:
validate: required_with=Status,omitempty,min=28,max=28
description: madhive advertiser id
example: 4gV9KIg6E2kX3d6117OO8rgseJRl
customerExternalId:
type: string
x-go-type-skip-optional-pointer: true
x-oapi-codegen-extra-tags:
validate: 'omitempty,min=2,ne= '
x-omitempty: true
description: external id of the advertiser
example: adv-123456
name:
type: string
x-oapi-codegen-extra-tags:
validate: 'required,min=2,ne= '
x-isnullable: false
x-omitempty: false
description: advertiser name
example: Madhive
domain:
type: string
x-oapi-codegen-extra-tags:
validate: required,url_badformat,url_invalidprefix,url_denylist,url_notexist
x-omitempty: false
x-isnullable: false
description: advertiser domain
example: madhive.com
iabCategory:
type: string
x-oapi-codegen-extra-tags:
validate: 'required,min=2,ne= '
x-omitempty: false
x-isnullable: false
description: iab category
example: IAB1
associatedAgency:
type: string
x-go-type-skip-optional-pointer: true
x-oapi-codegen-extra-tags:
validate: 'omitempty,min=2,ne= '
x-omitempty: true
description: advertiser's associated agency
example: fake agency name
status:
$ref: '#/components/schemas/Status'
ErrorResponse:
type: object
required:
- transaction
properties:
errors:
type: array
x-go-type-skip-optional-pointer: true
items:
type: string
description: many error messages
error:
type: string
x-go-type-skip-optional-pointer: true
description: error message
example: Unauthorized
status:
type: string
x-go-type-skip-optional-pointer: true
description: status of the service
example: ERROR
transaction:
$ref: '#/components/schemas/Transaction'
AdvertiserListItem:
type: object
required:
- id
properties:
id:
type: string
x-oapi-codegen-extra-tags:
validate: required,min=28,max=28
description: madhive advertiser id
example: 4gV9KIg6E2kX3d6117OO8rgseJRl
allOf:
- $ref: '#/components/schemas/Advertiser'
AdvertiserRequest:
type: object
required:
- name
- domain
- iabCategory
properties:
customerExternalId:
type: string
x-go-type-skip-optional-pointer: true
x-oapi-codegen-extra-tags:
validate: 'omitempty,min=2,ne= '
x-omitempty: true
description: external id of the advertiser
example: adv-123456
name:
type: string
x-oapi-codegen-extra-tags:
validate: 'required,min=2,ne= '
x-isnullable: false
x-omitempty: false
description: advertiser name
example: Madhive
domain:
type: string
x-oapi-codegen-extra-tags:
validate: required
x-omitempty: false
x-isnullable: false
description: advertiser domain
example: madhive.com
iabCategory:
type: string
x-oapi-codegen-extra-tags:
validate: 'required,min=2,ne= '
x-omitempty: false
x-isnullable: false
description: iab category
example: IAB1
associatedAgency:
type: string
x-go-type-skip-optional-pointer: true
x-oapi-codegen-extra-tags:
validate: 'omitempty,min=2,ne= '
x-omitempty: true
description: advertiser's associated agency
example: fake agency name
Transaction:
type: object
x-go-type-skip-optional-pointer: true
x-omitempty: false
required:
- id
- taskId
- created
properties:
id:
type: string
description: trace id
example: 4af459ff8e1a36b6bb74fb88f1a02477
taskId:
type: string
x-omitempty: true
description: task id
example: '14158884487309867565'
created:
type: string
description: 'order created date, format: yyyy-mm-dd hh:mm:ss'
example: '2030-11-02T15:04:00Z'
Pagination:
x-go-type-skip-optional-pointer: true
x-isnullable: false
readOnly: true
required:
- pageSize
- offset
- pageToken
- totalRecords
type: object
properties:
pageSize:
type: integer
format: int32
description: Number of items per page
example: 100
offset:
type: integer
format: int32
description: 'Page position relative to the supplied page_token (1 = next page, -1 = previous page, 0 = current page). Echoes the request''s offset.
'
example: 1
pageToken:
type: string
description: Opaque token for retrieving the next page of results
example: eyJuZXh0IjoxMDAsImxhc3QiOiJhYmMxMjMifQ==
totalRecords:
type: integer
format: int32
description: Total number of records available
example: 500
AdvertiserResponse:
type: object
allOf:
- $ref: '#/components/schemas/Advertiser'
- type: object
required:
- transaction
properties:
transaction:
$ref: '#/components/schemas/Transaction'
AdvertiserListResponse:
type: object
required:
- transaction
- advertisers
properties:
transaction:
$ref: '#/components/schemas/Transaction'
advertisers:
type: array
items:
$ref: '#/components/schemas/AdvertiserListItem'
description: list of advertisers
pagination:
$ref: '#/components/schemas/Pagination'
Status:
type: string
x-isnullable: false
x-omitempty: false
x-oapi-codegen-extra-tags:
validate: omitempty,oneof=READY ARCHIVED CANCELLED DRAFT PAUSED
description: status of the entity
example: READY
enum:
- READY
- ARCHIVED
- CANCELLED
- DRAFT
- PAUSED
parameters:
X-Cloud-Trace-Context:
name: X-Cloud-Trace-Context
in: header
description: gcp trace
required: false
schema:
type: string
default: 91f9f012dc7c7ffc13604c77f12a8931
examples:
401Ex:
value:
error: unauthorized
status: ERROR
transaction:
id: 4af459ff8e1a36b6bb74fb88f1a02477
taskId: '14158884487309867565'
created: '2030-11-02T15:04:00Z'
responses:
401Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
$ref: '#/components/examples/401Ex'
securitySchemes:
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api2.madhive.com/oauth/token
scopes: {}
basicAuth:
type: http
description: Basic Authentication Not Implemented
scheme: basic
bearerAuth:
type: apiKey
name: Authorization
in: header
description: jwt access token for authentication