openapi: 3.2.0 info: version: 1.5.1 title: OpenDirect Change Requests Lines 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: Change Requests Lines paths: /accounts/{accountId}/changerequest/{changerequestId}/lines: get: tags: - Change Requests Lines description: Gets a list of all lines in the change request. parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/changerequestId' - name: $filter in: query description: 'Gets a list of lines that match the specified filter criteria. The user may use OData expressions and method calls with the following Line properties. - Name - StartDate - EndDate May support getting a list by IDs. ' schema: type: string responses: 200: $ref: '#/components/responses/LinesResponse' 401: $ref: '#/components/responses/Standard401ErrorResponse' 404: $ref: '#/components/responses/Standard404ErrorResponse' 500: $ref: '#/components/responses/Standard500ErrorResponse' summary: Get accounts by account id changerequest by changerequest id lines x-summary-source: derived operationId: getAccountsByAccountIdChangerequestByChangerequestIdLines x-operation-id-source: derived post: tags: - Change Requests Lines description: Adds a line to the change request. parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/changerequestId' responses: 201: $ref: '#/components/responses/LineResponse' 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/Line' required: true summary: Create accounts by account id changerequest by changerequest id lines x-summary-source: derived operationId: postAccountsByAccountIdChangerequestByChangerequestIdLines x-operation-id-source: derived /accounts/{accountId}/changerequest/{changerequestId}/lines/{lineId}: get: tags: - Change Requests Lines description: Gets the specified line from the change request. parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/changerequestId' - $ref: '#/components/parameters/lineId' responses: 200: $ref: '#/components/responses/LineResponse' 401: $ref: '#/components/responses/Standard401ErrorResponse' 404: $ref: '#/components/responses/Standard404ErrorResponse' 500: $ref: '#/components/responses/Standard500ErrorResponse' summary: Get accounts by account id changerequest by changerequest id lines by line id x-summary-source: derived operationId: getAccountsByAccountIdChangerequestByChangerequestIdLinesByLineId x-operation-id-source: derived put: tags: - Change Requests Lines description: Updates the specified line in the change request. To update a line, the line must be in the Pending state. parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/changerequestId' - $ref: '#/components/parameters/lineId' responses: 200: $ref: '#/components/responses/LineResponse' 400: $ref: '#/components/responses/Standard400ErrorResponse' 401: $ref: '#/components/responses/Standard401ErrorResponse' 404: $ref: '#/components/responses/Standard404ErrorResponse' 500: $ref: '#/components/responses/Standard500ErrorResponse' summary: Replace accounts by account id changerequest by changerequest id lines by line… x-summary-source: derived operationId: putAccountsByAccountIdChangerequestByChangerequestIdLinesByLineId x-operation-id-source: derived delete: tags: - Change Requests Lines description: Deletes the specified line from the change request. May delete a line only if it’s in the Pending state. Must also delete assignments that reference the line. parameters: - $ref: '#/components/parameters/accountId' - $ref: '#/components/parameters/changerequestId' - $ref: '#/components/parameters/lineId' responses: 204: description: Line successfully deleted. 401: $ref: '#/components/responses/Standard401ErrorResponse' 404: $ref: '#/components/responses/Standard404ErrorResponse' 500: $ref: '#/components/responses/Standard500ErrorResponse' summary: Delete accounts by account id changerequest by changerequest id lines by line id x-summary-source: derived operationId: deleteAccountsByAccountIdChangerequestByChangerequestIdLinesByLineId x-operation-id-source: derived components: schemas: Errors: type: array items: $ref: '#/components/schemas/Error' Segment: description: The segment object is made up of TARGET and TARGET VALUE reference data objects and is used to specify targeting options for a LINE resource required: - Target - TargetValues properties: Target: $ref: '#/components/schemas/Target' TargetValues: description: A list of target values. For example, age range 18-24 and 25-34. type: array items: $ref: '#/components/schemas/TargetValue' FrequencyCapInterval: description: 'Defines the frequency cap intervals that the API supports. The frequency interval specifies the units in which the frequency count is expressed. For example, if a line’s frequency count is 2 and interval is Day, display the ad to the same user a Max 2 times in the same calendar day. ' allOf: - $ref: '#/components/schemas/Identity' - required: - Name properties: Name: description: The name of the interval. type: string enum: - Day - Month - Week - Hour - LineDuration Lines: required: - Lines properties: Lines: type: array items: $ref: '#/components/schemas/Line' 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 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 TargetValue: description: 'Defines a target value. The API must support the specified values per target category. ' allOf: - $ref: '#/components/schemas/Identity' - required: - Value - TargetId properties: Value: description: The target value type: string enum: - Age - Publisher-defined age ranges - Gender - Female - Gender - Male - DMA - Publisher-defined source (such as Digital Envoy) - Country - Publisher-defined source - State-Province - Publisher-defined source - Daypart - 0 through 23 hours - Weekpart - Sunday - Weekpart - Monday - Weekpart - Tuesday - Weekpart - Wednesday - Weekpart - Thursday - Weekpart - Friday - Weekpart - Saturday TargetId: description: A system-generated ID that identifies the target category that this value belongs to. type: string Error: type: object required: - ErrorCode - ErrorMessage properties: ErrorCode: type: string ErrorMessage: type: string Context: type: object Link: 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 Line: description: 'Line resources are included in an order and provide details about the product being booked, status, start and end dates, and other settings for the order item. Creative are assigned to the LINE resource of an order using the ASSIGNMENT resource. Notes: The user may update a line only if it’s in the Draft state. If the line is in the Reserved or Declined state, the user may call Reset to move the line back to the Draft state in order to update the line. ' allOf: - $ref: '#/components/schemas/Identity' - $ref: '#/components/schemas/ProviderData' - required: - BookingStatus - Cost - EndDate - Quantity - Name - OrderId - ProductId - Rate - RateType - StartDate - StateChangeReason properties: BookingStatus: description: A value that determines whether the line is booked and is capable of delivering ads. If the line is reset, the StateChangeReason should be cleared. type: string enum: - Draft - PendingReservation - Reserved - PendingBooking - Booked - InFlight - Finished - Stopped - Canceled - Pause - Expired - Declined - ChangePending readOnly: true Comment: description: User notes related to this line. type: string maxLength: 255 Cost: description: 'The projected cost of the line is based on the specified quantity, rate and targeting. The actual cost (the amount billed) is based on the actual number of impressions. The cost is specified in the currency for the order. If the order uses a different currency than what the product uses, the cost for the line must be converted to the order’s currency. The cost is determined at the time the line is saved with the following statuses: Drafted, Reserved, or Booked. ' type: number readOnly: true EndDate: description: 'The date and time that the line will stop. If the time is missing, 11:59 PM is assumed. The line end date must be later than the line start date and should be less than or equal to the order’s end date. If the line end date is later than the order’s end date, the order’s end date should be extended to match the line’s end date. ' type: string format: date-time FrequencyCount: description: The maximum number of times that a unique user must see ads from this line during the specified interval (see FrequencyInterval). type: integer FrequencyInterval: $ref: '#/components/schemas/FrequencyCapInterval' Quantity: description: 'The quantity requested for the specified date range. This value will differ based on various cost types. For CPM, for examples, the value would be impressions. The line must contain a quantity before the user may reserve or book it. If the requested quantity is not available, reserving or booking the line must fail and bookingStatus must be set to Declined. ' type: integer Name: description: 'The line’s display name. Should be unique. ' type: string maxLength: 200 OrderId: description: The ID of the order that this line belongs to. type: string maxLength: 36 readOnly: true ProductId: description: The ID of the product where the creatives run. type: string maxLength: 36 Rate: description: 'The price per unit of impressions. For example, $10 per 1,000 impressions (CPM). The rate is determined each time the line is saved (added, updated, booked, or reserved). Value in currency for the order. ' type: number readOnly: true RateType: description: The rate type is determined at the time the line is saved (added, updated, booked, or reserved). $ref: '#/components/schemas/RateType' readOnly: true ReservedExpiryDate: description: 'The date and time that the reserved inventory will expire. If the line is reserved, the expiry date must be set. ' type: string format: date-time readOnly: true StartDate: description: 'The date and time that the line will start. If the time is missing, 12:00 AM is assumed. The date and time must be greater than or equal to now and should be greater than or equal to the order’s start date. If the line start date is earlier than the order’s start date, the order’s start date should be moved to match the line’s start date. Both dates must be later than the present day. Start dates that are in the past may not be updated. ' type: string format: date-time StateChangeReason: description: 'The reason why the state was changed by the publisher. The reason must be specified if: - The publisher declined the booking or reservation. - The publisher or user canceled the flight. ' type: string readOnly: true Targeting: description: The creative assigned to the LINE resource is display when the line includes user segments and the delivery engine can determine whether the user matches the specified segments. $ref: '#/components/schemas/Segment' UsesExpandables: description: 'A Boolean value that indicates whether the line will be assigned expandable creatives. Used to determine availability. The default is false. ' type: boolean 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" 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" LineResponse: description: Line resource content: application/json: schema: $ref: '#/components/schemas/Line' example: "{\n \"BookingStatus\": \"Draft\",\n \"Comment\": \"Free form comment\",\n \"EndDate\": \"2014-12-10T18:00:00.000Z\",\n \"FrequencyCount\": 3,\n \"FrequencyInterval\": \"Day\",\n \"Id\": \"345233\",\n \"Quantity\": 30000,\n \"Name\": \"My Line 1\",\n \"OrderId\": \"1235872\",\n \"ProductId\": \"456366\",\n \"ProviderData\": \"cid=88873\",\n \"StartDate\": \"2014-12-05T06:00:00.000Z\",\n \"Targeting\": [\n {\n \"Target\": \"Age\",\n \"TargetValues\": [\"18-24\",\"25-34\"]\n },\n {\n \"Target\": \"Gender\",\n \"TargetValues\": [\"Male\"]\n }\n ]\n \"UsesExpandables\": False\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" LinesResponse: description: Collection of Line headers: X-Total-Count: description: Total number of results schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Lines' example: "{\n \"Lines\": [\n {\n \"BookingStatus\": \"Draft\",\n \"Comment\": \"Free form comment\",\n \"EndDate\": \"2014-12-10T18:00:00.000Z\",\n \"FrequencyCount\": 3,\n \"FrequencyInterval\": \"Day\",\n \"Id\": \"345233\",\n \"Quantity\": 30000,\n \"Name\": \"My Line 1\",\n \"OrderId\": \"1235872\",\n \"ProductId\": \"456366\",\n \"ProviderData\": \"cid=88873\",\n \"StartDate\": \"2014-12-05T06:00:00.000Z\",\n \"Targeting\": [\n {\n \"Target\": \"Age\",\n \"TargetValues\": [\"18-24\",\"25-34\"]\n },\n {\n \"Target\": \"Gender\",\n \"TargetValues\": [\"Male\"]\n }\n ]\n \"UsesExpandables\": False\n }\n ]\n}\n" parameters: accountId: name: accountId in: path required: true x-example: '23873345' schema: type: string maxLength: 36 changerequestId: name: changerequestId in: path required: true x-example: '398421' schema: type: string maxLength: 36 lineId: name: lineId in: path required: true x-example: '345233' 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.