> ## Documentation Index > Fetch the complete documentation index at: https://docs.otark.com/llms.txt > Use this file to discover all available pages before exploring further. # Bulk get nominations (POST) > Retrieve multiple nominations by ID using a request body. Use this for large ID sets that exceed the GET query parameter limit. Non-existent or inaccessible IDs are silently omitted. Required scope: `nominations:read` ## OpenAPI ````yaml /brp-openapi.yaml post /v1/nominations/bulk openapi: 3.0.0 info: title: Otark BRP API description: >- API for Balancing Responsible Parties (BRPs) to manage contracts, transactions, nominations, and customers on the Otark platform. version: 1.0.0 contact: {} servers: - url: https://api.otark.energy description: Production security: [] tags: - name: Contracts description: Manage energy contracts (PPA, day-ahead, etc.) - name: Transactions description: Contractual energy volumes between buyer and seller - name: Nominations description: Net saldo aggregated by balance group - name: Customers description: Manage customers assigned to the BRP paths: /v1/nominations/bulk: post: tags: - Nominations summary: Bulk get nominations (POST) description: >- Retrieve multiple nominations by ID using a request body. Use this for large ID sets that exceed the GET query parameter limit. Non-existent or inaccessible IDs are silently omitted. Required scope: `nominations:read` operationId: bulkPostNominations requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkNominationIdsRequest' responses: '200': description: Nominations list headers: x-ratelimit-limit: $ref: '#/components/headers/X-RateLimit-Limit' x-ratelimit-remaining: $ref: '#/components/headers/X-RateLimit-Remaining' x-ratelimit-reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/BulkNominationList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' security: - ApiKeyAuth: [] components: schemas: BulkNominationIdsRequest: type: object properties: ids: type: array description: List of nomination IDs to retrieve (max 100) items: type: string minItems: 1 maxItems: 100 example: - nom_t4u5v6w7x8 - nom_q1r2s3t4u5 required: - ids BulkNominationList: type: object properties: nominations: type: array description: >- List of nominations (non-existent or inaccessible IDs are silently omitted) items: $ref: '#/components/schemas/Nomination' required: - nominations Nomination: type: object description: >- The net saldo of valid transactions, aggregated by balance group and delivery period. Nominations are immutable — corrections produce a new version. properties: id: type: string description: Unique nomination identifier example: nom_t4u5v6w7x8 status: type: string description: Nomination status enum: - pending - partial_match - match - superseded example: match version: type: integer description: Version number (starts at 1, increments on correction) example: 1 previous_nomination_id: type: string nullable: true description: ID of the nomination this version supersedes example: null gate_closure: type: string format: date-time nullable: true description: ISO 8601 gate closure deadline example: '2026-01-14T14:30:00Z' confirmed_at: type: string format: date-time nullable: true description: ISO 8601 timestamp when the nomination was confirmed example: '2026-01-14T15:00:00Z' direction: type: string description: Energy direction from the BRP's perspective enum: - out - in example: out eic: type: string description: EIC code (balance group) of the BRP example: 11YWINDPARKNO--A tso: type: string description: BRP's TSO enum: - DE_AMPRION - DE_TENNET - DE_TRANSNET_BW - DE_50HERTZ example: DE_TENNET sent_at: type: string format: date-time nullable: true description: ISO 8601 timestamp when sent to the TSO example: '2026-01-14T14:35:00Z' counterparty: $ref: '#/components/schemas/NominationCounterparty' slots: type: array description: >- Delivery time slots with volumes (only present when `include_slots=true` on list endpoint; always present on detail/bulk/history endpoints) items: $ref: '#/components/schemas/NominationSlot' created_at: type: string format: date-time description: ISO 8601 creation timestamp example: '2026-01-14T14:30:00Z' required: - id - status - version - gate_closure - direction - eic - tso - counterparty - created_at Problem: type: object description: >- Error response following [RFC 9457 — Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457). properties: type: type: string format: uri description: Absolute URI identifying the problem class example: https://brp.otark.team/errors/balance_group_tso_not_enabled title: type: string description: >- Short human-readable label (stable across occurrences of the same type) example: Balance Group TSO Not Enabled status: type: integer description: HTTP status code example: 400 detail: type: string description: Human-readable explanation for this specific occurrence example: >- The requested TSO is not enabled for this balance group. Enable it via the balance group settings first. instance: type: string description: URI identifying the specific request example: /v1/customers/cust_r8s9t0u1 errors: type: array description: Field-level validation errors (present on validation failures) items: $ref: '#/components/schemas/ProblemFieldError' required: - type - title - status NominationCounterparty: type: object description: The counterparty in a nomination (Otark acts as intermediary) properties: name: type: string description: Counterparty name example: Otark eic: type: string description: EIC code example: 11YOTARK------Z required: - name - eic NominationSlot: type: object description: A delivery time slot within a nomination properties: delivery_start: type: string format: date-time description: ISO 8601 slot start (UTC) example: '2026-01-15T14:00:00Z' delivery_end: type: string format: date-time description: ISO 8601 slot end (UTC) example: '2026-01-15T14:15:00Z' slot_number: type: integer description: >- Quarter-hour slot number within the delivery day (1–96, or up to 100 on DST days) minimum: 1 maximum: 100 example: 57 amount: type: number description: Nominated energy volume in MWh (3 decimal places) example: 12.5 matched_amount: type: number nullable: true description: Confirmed/matched volume in MWh (null until matched) example: 12.5 required: - delivery_start - delivery_end - slot_number - amount ProblemFieldError: type: object description: A single field-level validation error properties: field: type: string description: JSON path of the field that caused the error example: balance_group.tso code: type: string description: >- Machine-readable error code: `unknown_field`, `read_only_field`, `required`, `invalid_type`, `invalid_enum_value`, `invalid_format`, `invalid_literal`, `value_too_small`, `value_too_large`, or `validation_failed` example: invalid_enum_value message: type: string description: Human-readable description of the issue example: >- Invalid enum value. Expected 'DE_AMPRION' | 'DE_TENNET' | 'DE_TRANSNET_BW' | 'DE_50HERTZ', received 'INVALID' required: - code - message headers: X-RateLimit-Limit: description: Maximum number of requests allowed per window schema: type: integer example: 300 X-RateLimit-Remaining: description: Remaining requests in the current window schema: type: integer example: 299 X-RateLimit-Reset: description: Seconds until the rate limit window resets schema: type: integer example: 60 responses: BadRequest: description: Invalid request — validation error or business rule violation content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://brp.otark.team/errors/validation title: Validation Failed status: 400 instance: /v1/customers/cust_r8s9t0u1 errors: - field: balance_group.tso code: invalid_enum_value message: >- Invalid enum value. Expected 'DE_AMPRION' | 'DE_TENNET' | 'DE_TRANSNET_BW' | 'DE_50HERTZ', received 'INVALID' Unauthorized: description: Missing or invalid API key content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://brp.otark.team/errors/invalid_api_key title: Invalid API Key status: 401 Forbidden: description: API key lacks required scopes content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://brp.otark.team/errors/insufficient_scopes title: Insufficient API Key Scopes status: 403 detail: >- Missing scope: customers:write. Please create a new API key with the required scopes. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key ````