openapi: 3.2.0 info: title: Iab Tech Lab Orders API version: '1.0' description: 'Operations tagged Orders across 2 of this provider''s published API definitions: iab-tech-lab-opendirect-1-5-1-swagger.yaml, iab-tech-lab-seller-agent-openapi.json. Each path carries the servers of the definition it was published in.' servers: - url: https://opendirect.example.com/v1.5.1 tags: - name: Orders paths: /accounts/{accountId}/orders: get: tags: - Orders description: 'Gets a list of all orders that belong to the account. For advertisers, the list will include only orders that they own. For agencies, the list will include the orders that they own and the orders that belong to accounts that they manage on behalf of advertisers.' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/count' - $ref: '#/components/parameters/offset' - name: $filter in: query description: 'Allows to get a list of creatives that match the specified filter criteria. The user may use OData expressions with the following Creative properties: - AdStatus May support getting a list by IDs. User should be either an advertiser or buyer who owns the orders. ' schema: type: string responses: 200: $ref: '#/components/responses/OrdersResponse' 401: $ref: '#/components/responses/Standard401ErrorResponse' 404: $ref: '#/components/responses/Standard404ErrorResponse' 500: $ref: '#/components/responses/Standard500ErrorResponse' security: - OauthSecurity: - https://opendirect.example.com/scope/example summary: Get accounts by account id orders x-summary-source: derived operationId: getAccountsByAccountIdOrders x-operation-id-source: derived post: tags: - Orders description: 'Adds an order to the account. An advertiser or agency may add orders to accounts that they own. In addition; an agency may add orders to accounts that they manage on behalf of advertisers.' parameters: - $ref: '#/components/parameters/accountId' responses: 201: $ref: '#/components/responses/OrderResponse' 400: $ref: '#/components/responses/Standard400ErrorResponse' 401: $ref: '#/components/responses/Standard401ErrorResponse' 404: $ref: '#/components/responses/Standard404ErrorResponse' 500: $ref: '#/components/responses/Standard500ErrorResponse' requestBody: content: application/json: schema: $ref: '#/components/schemas/Order' required: true security: - OauthSecurity: - https://opendirect.example.com/scope/example summary: Create accounts by account id orders x-summary-source: derived operationId: postAccountsByAccountIdOrders x-operation-id-source: derived servers: - url: https://opendirect.example.com/v1.5.1 /accounts/{accountId}/orders/{orderId}: get: tags: - Orders description: 'Gets the specified order. The user must have permissions to perform the requested action. For example, advertisers and agencies may get the orders that they own. In addition, an agency may get the orders that belong to the accounts that they manage on behalf of advertisers.' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/orderId' responses: 200: $ref: '#/components/responses/OrderResponse' 401: $ref: '#/components/responses/Standard401ErrorResponse' 404: $ref: '#/components/responses/Standard404ErrorResponse' 500: $ref: '#/components/responses/Standard500ErrorResponse' security: - OauthSecurity: - https://opendirect.example.com/scope/example summary: Get accounts by account id orders by order id x-summary-source: derived operationId: getAccountsByAccountIdOrdersByOrderId x-operation-id-source: derived put: tags: - Orders description: 'Updates the specified order. The user must have permissions to perform the requested action. For example, advertisers and agencies may update the orders that they own. In addition, an agency may update the orders that belong to the accounts that they manage on behalf of advertisers.' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/orderId' responses: 200: $ref: '#/components/responses/OrderResponse' 400: $ref: '#/components/responses/Standard400ErrorResponse' 401: $ref: '#/components/responses/Standard401ErrorResponse' 404: $ref: '#/components/responses/Standard404ErrorResponse' 500: $ref: '#/components/responses/Standard500ErrorResponse' security: - OauthSecurity: - https://opendirect.example.com/scope/example summary: Replace accounts by account id orders by order id x-summary-source: derived operationId: putAccountsByAccountIdOrdersByOrderId x-operation-id-source: derived delete: tags: - Orders description: 'Deletes the specified order. May delete the order only if all lines in the order are in the Draft state. Must also delete assignments that reference the line. The user must have permissions to perform the requested action. For example, advertisers and agencies may delete the orders that they own. In addition, an agency may delete the orders that belong to the accounts that they manage on behalf of advertisers.' parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/orderId' responses: 204: description: Order successfully deleted. 401: $ref: '#/components/responses/Standard401ErrorResponse' 404: $ref: '#/components/responses/Standard404ErrorResponse' 500: $ref: '#/components/responses/Standard500ErrorResponse' security: - OauthSecurity: - https://opendirect.example.com/scope/example summary: Delete accounts by account id orders by order id x-summary-source: derived operationId: deleteAccountsByAccountIdOrdersByOrderId x-operation-id-source: derived servers: - url: https://opendirect.example.com/v1.5.1 /api/v1/orders: post: tags: - Orders summary: Create Order description: Create a new order and persist its state machine. operationId: create_order_api_v1_orders_post parameters: - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOrderRequest' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' get: tags: - Orders summary: List Orders description: List orders, optionally filtered by status. operationId: list_orders_api_v1_orders_get parameters: - name: status in: query required: false schema: anyOf: - type: string - type: 'null' title: Status - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /api/v1/orders/report: get: tags: - Orders summary: Get Orders Report description: 'Summary report across all orders. Returns counts by status, transition frequency by actor type, and average time-in-state metrics.' operationId: get_orders_report_api_v1_orders_report_get parameters: - name: from_date in: query required: false schema: anyOf: - type: string - type: 'null' title: From Date - name: to_date in: query required: false schema: anyOf: - type: string - type: 'null' title: To Date - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /api/v1/orders/{order_id}: get: tags: - Orders summary: Get Order description: Get order current status and audit trail. operationId: get_order_api_v1_orders__order_id__get parameters: - name: order_id in: path required: true schema: type: string title: Order Id - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /api/v1/orders/{order_id}/history: get: tags: - Orders summary: Get Order History description: Get the full transition history for an order. operationId: get_order_history_api_v1_orders__order_id__history_get parameters: - name: order_id in: path required: true schema: type: string title: Order Id - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /api/v1/orders/{order_id}/transition: post: tags: - Orders summary: Transition Order description: 'Transition an order to a new state. Validates the transition against the state machine rules and records the change in the audit log.' operationId: transition_order_api_v1_orders__order_id__transition_post parameters: - name: order_id in: path required: true schema: type: string title: Order Id - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: X-Api-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TransitionOrderRequest' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: Errors: type: array items: $ref: '#/components/schemas/Error' 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 Order: description: 'The Order resource specifies the plan’s start and end dates, estimated budget, currency, and preferred billing method for all line items in the order. To specify the individual line item details of the order, use the LINE resource. ' allOf: - $ref: '#/components/schemas/Identity' - $ref: '#/components/schemas/ProviderData' - required: - AccountId - Currency - Name - OrderStatus properties: AccountId: description: The ID of the account that identifies the advertiser and buyer that own the order. type: string maxLength: 36 readOnly: true Brand: description: A descriptive name for the brand being advertised. type: string maxLength: 25 Budget: description: The order’s estimated budget. The budget is directional; it is not used to limit the amount of money that the order spends. To determine the projected spend based on quantity, aggregate the Cost property for each line of the order. type: number Contacts: description: 'The list of contacts to use for this order. This list of contacts is in addition to the buyer’s and advertiser’s list of contacts. The list must contain unique contact types (for example, only one billing contact). ' type: array items: $ref: '#/components/schemas/Contact' uniqueItems: true Currency: description: The publisher may enforce that all lines of the order specify products that use the same currency. $ref: '#/components/schemas/Currency' EndDate: description: 'The date and time that the order will end. The end date is directional and may be updated by the publisher to match the latest end date found in the order’s lines. If the time is missing, 11:59 PM is assumed. The end date must be later than the start date. End dates that have past cannot be updated. ' type: string format: date-time OrderExpiryDate: description: The date and time for when the order expires. Publisher will only hold inventory up until the date and time indicated. type: string format: date-time readOnly: true Industry: description: The industry associated with the order. This industry may differ from the industry specified on the advertiser’s Organization object. $ref: '#/components/schemas/Industry' Name: description: 'The order’s display name. Must be unique within the account’s list of orders. ' type: string maxLength: 100 OrderStatus: description: Specifies the Status of the Order. type: string enum: - PENDING - APPROVED - REJECTED readOnly: true PackageOnly: description: Identifies whether the order is only available as a package or if specific items can be separated from the inventory. A value of TRUE means the inventory is only available as a package. A value of FALSE allows the buyer to select specific items from inventory. type: boolean readOnly: true PreferredBillingMethod: description: 'The preferred billing method for this order. The default is Electronic. If the billing contact is not specified in the order, the billing contact comes from buyer’s list of contacts. ' type: string enum: - Electronic - Postal maxLength: 10 StartDate: description: 'The date and time that the order will start. The start date is directional and may be updated by the publisher to match the earliest start date found in the order’s list of lines. If the time is missing, 12:00 AM is assumed. When creating the order, the date and time must be greater than or equal to now. Start dates that have past may not be updated. ' type: string format: date-time 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 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 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 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 Orders: required: - Orders properties: Orders: type: array items: $ref: '#/components/schemas/Order' 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 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' ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError CreateOrderRequest: properties: deal_id: anyOf: - type: string - type: 'null' title: Deal Id quote_id: anyOf: - type: string - type: 'null' title: Quote Id metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata type: object title: CreateOrderRequest description: Request to create a new order. TransitionOrderRequest: properties: to_status: type: string title: To Status actor: type: string title: Actor default: system reason: type: string title: Reason default: '' metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata type: object required: - to_status title: TransitionOrderRequest description: Request to transition an order to a new state. 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" Standard400ErrorResponse: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Errors' example: "{\n \"ErrorCode\": \"badRequest\",\n \"ErrorMessage\": \"Request contains invalid data\"\n}\n" OrdersResponse: description: Collection of Order headers: X-Total-Count: description: Total number of results schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Orders' example: "{\n \"Orders\": [\n {\n \"AccountId\": \"23873345\",\n \"Brand\": \"Four Wakes\",\n \"Budget\": 50000,\n \"Currency\": \"USD\",\n \"EndDate\": \"2014-12-24T18:00:00.000Z\",\n \"Id\": \"1235872\",\n \"Name\": \"My Order\",\n \"PreferredBillingMethod\": \"Electronic\",\n \"ProviderData\": \"cid=563364\",\n \"StartDate\": \"2014-11-24T06:00:00.000Z\",\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" OrderResponse: description: Order resource content: application/json: schema: $ref: '#/components/schemas/Order' example: "{\n \"AccountId\": \"23873345\",\n \"Brand\": \"Four Wakes\",\n \"Budget\": 50000,\n \"Currency\": \"USD\",\n \"EndDate\": \"2014-12-24T18:00:00.000Z\",\n \"Id\": \"1235872\",\n \"Name\": \"My Order\",\n \"PreferredBillingMethod\": \"Electronic\",\n \"ProviderData\": \"cid=563364\",\n \"StartDate\": \"2014-11-24T06:00:00.000Z\",\n}\n" parameters: accountId: name: accountId in: path required: true x-example: '23873345' schema: type: string maxLength: 36 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 orderId: name: orderId in: path required: true x-example: '1235872' 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. x-refined-from: - iab-tech-lab-opendirect-1-5-1-swagger.yaml - iab-tech-lab-seller-agent-openapi.json