Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
version: 1.5.1
title: OpenDirect Organizations API
description: OpenDirect enables publishers to offer premium inventory using a programmatic interface that partners and vendors build according to the OpenDirect specifications.
servers:
- url: https://opendirect.example.com/v1.5.1
security:
- OauthSecurity:
- https://opendirect.example.com/scope/example
tags:
- name: Organizations
paths:
/organizations:
get:
tags:
- Organizations
description: 'Gets a list of all organizations that the user has access to. The list may contain both advertiser and agency organizations depending on the caller’s access. For example, if the caller is an advertiser, the list might contain only the advertiser’s organization objects; however, if the caller is an agency, the list will contain the agency’s organization objects and the organization objects of the advertisers whose accounts that they manage.
The list will contain a single organization for advertisers; however, for agencies, the list will include the agency’s organization and the organizations of the advertisers whose accounts they manage.'
parameters:
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/offset'
- name: $filter
in: query
description: 'Allows to get a list of organizations that match the specified filter criteria. The user may use OData expressions and method calls with the following Organization properties:
- Name
- Status
- One or more organization IDs
'
schema:
type: string
responses:
200:
$ref: '#/components/responses/OrganizationsResponse'
401:
$ref: '#/components/responses/Standard401ErrorResponse'
500:
$ref: '#/components/responses/Standard500ErrorResponse'
summary: Get organizations
x-summary-source: derived
operationId: getOrganizations
x-operation-id-source: derived
post:
tags:
- Organizations
description: Adds an organization. Note that POST is not supported in the public API; it is included here for completeness. The process of adding advertiser and agency organizations and providing credentials is publisher defined. Once the publisher creates an organization for an agency, the agency may create organizations for its clients. Advertisers that represent themselves may also create organizations for other verticals within the advertiser's company if publisher-approved. However, all Organizations on an Account must be in an "Approved" or "Limited" state before inventory can be searched and booked.
responses:
201:
$ref: '#/components/responses/ProductResponse'
400:
$ref: '#/components/responses/Standard400ErrorResponse'
401:
$ref: '#/components/responses/Standard401ErrorResponse'
500:
$ref: '#/components/responses/Standard500ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
required: true
summary: Create organizations
x-summary-source: derived
operationId: postOrganizations
x-operation-id-source: derived
/organizations/{organizationId}:
get:
tags:
- Organizations
description: 'Gets the specified organization.
The user must have permissions to perform the requested action. For example, advertisers and agencies may get the Organization that they own; however, an agency may only get the organization of the advertisers whose accounts they manage.'
parameters:
- $ref: '#/components/parameters/organizationId'
responses:
200:
$ref: '#/components/responses/OrganizationResponse'
401:
$ref: '#/components/responses/Standard401ErrorResponse'
404:
$ref: '#/components/responses/Standard404ErrorResponse'
500:
$ref: '#/components/responses/Standard500ErrorResponse'
summary: Get organizations by organization id
x-summary-source: derived
operationId: getOrganizationsByOrganizationId
x-operation-id-source: derived
put:
tags:
- Organizations
description: 'Updates the specified organization.
The caller must have permissions to update the organization. For example, an advertiser and agency may update their organization object but an agency may not update an advertiser’s Organization object.'
parameters:
- $ref: '#/components/parameters/organizationId'
responses:
200:
$ref: '#/components/responses/OrganizationResponse'
400:
$ref: '#/components/responses/Standard400ErrorResponse'
401:
$ref: '#/components/responses/Standard401ErrorResponse'
404:
$ref: '#/components/responses/Standard404ErrorResponse'
500:
$ref: '#/components/responses/Standard500ErrorResponse'
summary: Replace organizations by organization id
x-summary-source: derived
operationId: putOrganizationsByOrganizationId
x-operation-id-source: derived
delete:
tags:
- Organizations
description: The process of deleting an organization is publisher defined; however, deleting an organization via the API is not supported.
parameters:
- $ref: '#/components/parameters/organizationId'
responses:
204:
description: Organization successfully deleted.
401:
$ref: '#/components/responses/Standard401ErrorResponse'
404:
$ref: '#/components/responses/Standard404ErrorResponse'
500:
$ref: '#/components/responses/Standard500ErrorResponse'
summary: Delete organizations by organization id
x-summary-source: derived
operationId: deleteOrganizationsByOrganizationId
x-operation-id-source: derived
components:
schemas:
Errors:
type: array
items:
$ref: '#/components/schemas/Error'
InventoryType:
description: Defines a list of devices that the product may serve on.
allOf:
- $ref: '#/components/schemas/Identity'
- required:
- Name
properties:
Name:
description: The ad format’s display name.
type: string
enum:
- App
- Desktop
- Mobile
- Tablet
ContactType:
description: Defines the possible types of Contacts.
allOf:
- $ref: '#/components/schemas/Identity'
- required:
- Name
properties:
Name:
description: The type’s display name.
type: string
enum:
- Billing
- Buyer
- Creative
AdFormatType:
description: Defines the possible ad formats.
allOf:
- $ref: '#/components/schemas/Identity'
- required:
- Name
properties:
Name:
description: The ad format’s display name.
type: string
enum:
- HTML5
- HTML5Expandable
- Flash
- FlashExpandable
- Image
- Tag
- TagExpandable
- Text
- Video
- VPAID
- MRAID
Size:
description: The Size object defines the height and width (in pixels) that a publisher accepts. The size object populates publisher-accepted sizes in the GEOMETRY property of relevant resources, such as CREATIVE.
required:
- Height
- Width
properties:
Height:
description: The height of accepted creative size in pixels.
type: integer
Width:
description: The width of accepted creative size in pixels.
type: integer
ProviderData:
description: Common definition for all entities with provider data.
properties:
ProviderData:
description: 'An opaque blob of provider-defined data. Providers may use this field as needed (for example, to store an ID that correlates this object with resources within their system).
Note that any provider that edits this object may override the data in this field. The data should include a marker that you can identify to ensure the data is yours.
'
type: string
maxLength: 1000
Address:
description: The address object is used to provide values for the ORGANIZAION resource.
required:
- City
- Country
- AddressLine1
properties:
City:
description: The city name of an organization or contact for which this address is associated.
type: string
maxLength: 35
Country:
$ref: '#/components/schemas/Country'
AddressLine1:
description: The first line of the address of an organization or contact for which this address is associated.
type: string
maxLength: 255
AddressLine2:
description: The optional second line of the address.
type: string
maxLength: 255
x-publisher-support-required: true
PostalCode:
description: The postal or ZIP code for the address.
type: string
maxLength: 15
x-publisher-support-required: true
State:
description: The state or province for the address.
type: string
maxLength: 35
x-publisher-support-required: true
AdPosition:
description: Defines the possible ad positions on a web page.
allOf:
- $ref: '#/components/schemas/Identity'
- required:
- Name
properties:
Name:
description: The ad position’s display name.
type: string
enum:
- AboveFold
- BelowFold
RateType:
description: Defines a unit of measure that a cost (i.e. BasePrice) is expressed in. The API may support all or a subset of the specified values.
allOf:
- $ref: '#/components/schemas/Identity'
- required:
- Name
properties:
Name:
description: The rate type’s display name.
type: string
enum:
- CPM
- CPMV
- CPC
- CPD
- FlatRate
Target:
description: Defines a target category. The API must support the specified target categories and may support additional categories such as zip code or postal code.
allOf:
- $ref: '#/components/schemas/Identity'
- required:
- Name
properties:
Name:
description: The target category.
type: string
enum:
- Age
- Gender
- DMA
- Country
- State/Province
- Daypart
- Weekpart
- Behavioral
- Device
Language:
description: Defines a language that the API supports. The API may support all or a subset of the languages specified in ISO 639-1.
required:
- IsoCode
properties:
IsoCode:
description: The language’s two-character ISO code as specified in ISO 639-1.
type: string
minLength: 2
maxLength: 2
Currency:
description: 'Defines a currency that the API supports.
The API may support all or a subset of the currencies specified in ISO-4217.
'
required:
- IsoCode
properties:
IsoCode:
description: The currency’s three-character ISO code (ISO 4217).
type: string
minLength: 3
maxLength: 3
Organizations:
required:
- Organizations
properties:
Organizations:
type: array
items:
$ref: '#/components/schemas/Organization'
Error:
type: object
required:
- ErrorCode
- ErrorMessage
properties:
ErrorCode:
type: string
ErrorMessage:
type: string
Context:
type: object
Link:
type: string
Contact:
description: Defines an agency or advertiser contact.
required:
- FirstName
- LastName
- Type
properties:
Address:
description: Required if TYPE is Billing and the preferred billing method for the organization or order is paper.
$ref: '#/components/schemas/Address'
Email:
description: 'The contact’s email address.
Required if TYPE is Billing and the preferred billing method for the organization or order is electronic.
'
type: string
maxLength: 254
x-publisher-support-required: true
Honorific:
description: Honorific such as Mr. or Ms.
type: string
maxLength: 20
Fax:
description: The contact’s fax number.
type: string
maxLength: 20
FirstName:
description: The contact’s first name.
type: string
maxLength: 20
LastName:
description: The contact’s last name.
type: string
maxLength: 20
Phone:
description: The contact’s phone number
type: string
maxLength: 20
x-publisher-support-required: true
Title:
description: The contact’s job title.
type: string
maxLength: 30
x-publisher-support-required: true
Type:
$ref: '#/components/schemas/ContactType'
readOnly: true
Product:
description: A Product resource identifies anything from an ad placement to a Run of Network product in the publisher’s product catalog. Values for all supported fields are provided by the publisher.
allOf:
- $ref: '#/components/schemas/Identity'
- required:
- AdFormatTypes
- BasePrice
- Currency
- Geometry
- Name
- RateType
properties:
ActiveDate:
description: The date and time, in UTC, that the product may become part of the bookable inventory.
type: string
format: date-time
AdFormatTypes:
description: A list of ad types that the product supports.
type: array
items:
$ref: '#/components/schemas/AdFormatType'
AllowNoCreative:
description: A Boolean value that indicates whether line items assigned to this order may be booked before creative is assigned. A value of TRUE allows lines to be booked without creative assigned. Default value is FALSE and prevents lines from being booked when no creative is assigned.
type: boolean
BasePrice:
description: The product’s base retail price; this is not the rate card price. The actual price may be more if targeting is specified.
type: number
Currency:
description: Identifies the currency for BasePrice and MinSpend.
$ref: '#/components/schemas/Currency'
DeliveryType:
$ref: '#/components/schemas/DeliveryType'
Description:
description: The product’s description.
type: string
maxLength: 255
Domain:
description: The product’s domain.
type: string
maxLength: 255
EstimatedDailyAvails:
description: 'An estimated range of available daily impressions.
The ranges should be of the form: Thousands, Tens of Thousands, Hundreds of Thousands, and so on.
'
type: string
Geometry:
description: A list of ad format sizes that the product supports.
type: array
items:
$ref: '#/components/schemas/Size'
HttpsCompatible:
description: A Boolean value that determines whether the product supports creatives that can properly render on an HTML web page served over HTTPS.
type: boolean
Icon:
description: 'URL to a thumbnail icon of the product. May be used to display next to the product in the product catalog.
Publishers should support icons that are 150x150 or less. The maximum size is 10 KB.
'
type: string
InventoryType:
$ref: '#/components/schemas/InventoryType'
Languages:
description: A list of creative languages that the product supports.
type: array
items:
$ref: '#/components/schemas/Language'
LeadTime:
description: The number of days (n) from today that a line that reference this product can begin running; the line’s start date must be equal to or later than today + n.
type: integer
Name:
description: 'The product’s display name.
The name must be unique.
'
type: string
maxLength: 38
MaturityLevel:
$ref: '#/components/schemas/MaturityLevel'
MaxDuration:
description: The maximum number of days that the product may be booked for. The line must enforce the duration.
type: integer
MinDuration:
description: The minimum number of days that the product must be booked for. The line must enforce the duration.
type: integer
MinSpend:
description: The minimum amount of money that must be spent on this product in order to book it.
type: number
Position:
$ref: '#/components/schemas/AdPosition'
ProductTags:
description: List of tags used for searching the product catalog.
type: array
items:
type: string
maxLength: 100
maxItems: 500
RateType:
$ref: '#/components/schemas/RateType'
RetirementDate:
description: The date and time, in UTC, that the product may be removed from the bookable inventory.
type: string
format: date-time
TargetTypes:
description: A list of IDs that identify the types of targeting that the product supports.
type: array
items:
$ref: '#/components/schemas/Target'
TimeZone:
description: The time zone that the product runs in.
type: string
Url:
description: A URL to the specification that describes the creative requirements.
type: string
Identity:
description: Common definition for all entities with identity.
required:
- Id
properties:
Id:
description: A system-generated opaque ID that uniquely identifies this resource.
type: string
maxLength: 36
readOnly: true
Country:
description: 'Defines a country that the API supports.
The API may support all or a subset of the countries specified in ISO 3166-1.
'
required:
- IsoCode
properties:
IsoCode:
description: The country’s two-character ISO code (ISO 3166-1).
type: string
minLength: 2
maxLength: 2
Organization:
description: 'The organization resource may represent an advertiser or agency (buyer). The Account determines the role that the organization plays by using the organization ID in place of the BuyerId or AdvertiserId. The organization’s role may vary by account. For example, the organization may be an advertiser in one account and a buyer in another. An advertiser may create one or more organizations to meet their business needs. For example, they may create a single organization and then create accounts for each brand, subsidiary, or division. Or, they may create an organization for each brand. It is up to the advertiser to determine how they use Organization and Account to meet their organizational needs.
A publisher may also create an organization for itself for the purpose of requesting a change to an order. To identify a publisher for a change request, the organization ID is supplied as the RequesterId for the ChangeRequest resource.
'
allOf:
- $ref: '#/components/schemas/Identity'
- $ref: '#/components/schemas/ProviderData'
- required:
- Contacts
- Name
- Status
properties:
Address:
$ref: '#/components/schemas/Address'
Contacts:
description: A list of one or more contacts within the organization. The list must contain unique contact types (for example, only one billing contact). At least one billing contact is required.
type: array
items:
$ref: '#/components/schemas/Contact'
uniqueItems: true
DisapprovalReason:
description: The reason why the organization was not registered. Must be specified if Status is Disapproved.
type: string
maxLength: 255
readOnly: true
x-publisher-support-required: true
Fax:
description: The organization’s fax number.
type: string
maxLength: 20
Industry:
description: An industry label for the organization. Only required for advertiser organization.
$ref: '#/components/schemas/Industry'
Name:
description: 'The organization’s display name.
Cannot be an empty string. Must be unique.
'
type: string
maxLength: 128
Phone:
description: The organization’s phone number.
type: string
maxLength: 20
Status:
description: A value that indicates the current state of the approval process. The approval process confirms the organization’s identity.
type: string
maxLength: 15
readOnly: true
enum:
- Pending
- Approved
- Disapproved
- Limited
Url:
description: A URL to the organization’s website.
type: string
maxLength: 1024
Industry:
description: Defines an industry that the advertiser belongs to. Uses “IAB Tech Lab Content Taxonomy”.
allOf:
- $ref: '#/components/schemas/Identity'
- required:
- Name
- ParentId
- SubIndustries
properties:
Name:
description: The industry’s display name.
type: string
ParentId:
description: The ID of the sub-industry’s parent. Is NULL for the top-level parent.
type: string
SubIndustries:
description: A list of sub-industries. The list is empty if the industry has no sub-industries.
type: array
items:
$ref: '#/components/schemas/Industry'
MaturityLevel:
description: Defines a list of maturity levels. Current maturity level definitions comply with those provided in section 4.2.3 of the TAG's Inventory Quality Guidelines released December, 2015. Current guidelines can be found on the tagtoday.net website. The API may support all or a subset of the specified values.
allOf:
- $ref: '#/components/schemas/Identity'
- required:
- Level
properties:
Level:
description: The accepted maturity level for the specified inventory.
type: string
enum:
- All
- Over12
- Mature
- NotSpecified
DeliveryType:
description: Defines the possible types of delivery.
allOf:
- $ref: '#/components/schemas/Identity'
- required:
- Name
properties:
Name:
description: The delivery type’s display name.
type: string
enum:
- Exclusive
- Guaranteed
responses:
Standard500ErrorResponse:
description: Unexpected error occurred
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example: "{\n \"ErrorCode\": \"internalError\",\n \"ErrorMessage\": \"Unexpected error occurred\"\n}\n"
OrganizationResponse:
description: Organization resource
content:
application/json:
schema:
$ref: '#/components/schemas/Organization'
example: "{\n \"Address\": {\n \"AddressLine1\": \"1234 Tiger Blvd\",\n \"City\": \"Redmond\",\n \"Country\": \"US\",\n \"PostalCode\": \"98123\",\n \"State\": \"WA\"\n },\n \"Contacts\": [\n {\n \"Address\": {\n \"AddressLine1\": \"1234 Tiger Blvd\",\n \"City\": \"Redmond\",\n \"Country\": \"US\",\n \"PostalCode\": \"98123\",\n \"State\": \"WA\"\n },\n \"Email\": \"jsilver@contoso.com\",\n \"Honorific\": \"Ms\",\n \"Fax\": \"2065551212\",\n \"FirstName\": \"Janet\",\n \"LastName\": \"Silver\",\n \"Phone\": \"2065550101\",\n \"Title\": \"Comptroller\",\n \"Type\": \"Billing\"\n }\n ],\n \"Fax\": \"2065551212\",\n \"Id\": \"12345678\",\n \"Industry\": \"Automotive\",\n \"Name\": \"Contoso\",\n \"Phone\": \"2065550100\",\n \"ProviderData\": \"cid=89345\",\n \"Status\": \"Approved\",\n \"Url\": \"http://contoso.com\"\n}\n"
Standard400ErrorResponse:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example: "{\n \"ErrorCode\": \"badRequest\",\n \"ErrorMessage\": \"Request contains invalid data\"\n}\n"
ProductResponse:
description: Product resource
content:
application/json:
schema:
$ref: '#/components/schemas/Product'
example: "{\n \"AdFormatTypes\": [\n \"Flash\",\n \"Tag\",\n \"Image\"\n ],\n \"BasePrice\": 1.31,\n \"Currency\": \"USD\",\n \"DeliveryType\": \"Guaranteed\",\n \"Descripion\": \"A description of the product for display purposes\",\n \"Domain\": \"mydomain.com\",\n \"EstimatedDailyAvails\": \"Hundreds of Thousands\",\n \"Geometry\": [\n {\n \"Height\": 160\n \"Width\": 600\n }\n ],\n \"HttpsCompatible\": False,\n \"Icon\": \"http://<domain>/<path>/icon.jpg\",\n \"Id\": \"456366\",\n \"InventoryType\": {\n \"Name\": \"Desktop\",\n \"Name\": \"Tablet\"\n },\n \"Languages\": [\n \"EN\"\n ],\n \"Name\": \"Unique Product Name\",\n \"MaturityLevel\": {\n \"Level\": \"Over12\"\n },\n \"MaxDuration\": 30,\n \"MinDuration\": 1,\n \"MinSpend\": 30.00,\n \"Position\": \"AboveFold\",\n \"ProductTags\": \"Foo Bar Zoo\",\n \"RateType\": \"CPM\",\n \"TargetTypes\": [\n \"2342\",\n \"3355\"\n ],\n \"TimeZone\": \"Eastern Standard Time\"\n \"Url\": \"http://<domain>/<path>/creativespec.aspx\"\n}\n"
OrganizationsResponse:
description: Collection of Organization
headers:
X-Total-Count:
description: Total number of results
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Organizations'
example: "{\n \"Organizations\": [\n {\n \"Address\": {\n \"AddressLine1\": \"1234 Tiger Blvd\",\n \"City\": \"Redmond\",\n \"Country\": \"US\",\n \"PostalCode\": \"98123\",\n \"State\": \"WA\"\n },\n \"Contacts\": [\n {\n \"Address\": {\n \"AddressLine1\": \"1234 Tiger Blvd\",\n \"City\": \"Redmond\",\n \"Country\": \"US\",\n \"PostalCode\": \"98123\",\n \"State\": \"WA\"\n },\n \"Email\": \"jsilver@contoso.com\",\n \"Honorific\": \"Ms\",\n \"Fax\": \"2065551212\",\n \"FirstName\": \"Janet\",\n \"LastName\": \"Silver\",\n \"Phone\": \"2065550101\",\n \"Title\": \"Comptroller\",\n \"Type\": \"Billing\"\n }\n ],\n \"Fax\": \"2065551212\",\n \"Id\": \"12345678\",\n \"Industry\": \"Automotive\",\n \"Name\": \"Contoso\",\n \"Phone\": \"2065550100\",\n \"ProviderData\": \"cid=89345\",\n \"Status\": \"Approved\",\n \"Url\": \"http://contoso.com\"\n }\n ]\n}\n"
Standard404ErrorResponse:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example: "{\n \"ErrorCode\": \"notFound\",\n \"ErrorMessage\": \"Requested resource is not found\"\n}\n"
Standard401ErrorResponse:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
example: "{\n \"ErrorCode\": \"unauthorized\",\n \"ErrorMessage\": \"You are not authorized to use this service\"\n}\n"
parameters:
count:
name: count
in: query
description: Indicates the number of desired records to be returned in the response.
schema:
type: integer
default: 250
minimum: 1
offset:
name: offset
in: query
description: Indicates the starting point from which the number of records should be returned in the response.
schema:
type: integer
default: 0
minimum: 0
organizationId:
name: organizationId
in: path
required: true
x-example: '12345678'
schema:
type: string
maxLength: 36
securitySchemes:
OauthSecurity:
type: oauth2
flows:
implicit:
scopes:
https://opendirect.example.com/scope/example: Example scope
authorizationUrl: https://opendirect.example.com/connect/authorize
description: Example of one of OAuth 2.0 authorization flow that can be used according to specification.