> ## Documentation Index > Fetch the complete documentation index at: https://docs.ofiniti.com/llms.txt > Use this file to discover all available pages before exploring further. # Creates or updates a draft nomination > Creates a new draft nomination or updates an existing one based on the client reference. Uses idempotency to prevent duplicate submissions. ## OpenAPI ````yaml /specs/fuelboss/fuelboss-api.json put /v1/nominations/drafts openapi: 3.1.1 info: title: FuelBoss API description: >- REST API providing a powerful and easy way to manage your companies nominations and operations. termsOfService: https://www.ofiniti.com/legal/platform-service-terms contact: name: Support Team email: itops@ofiniti.com version: 1.15.1 servers: - url: https://api.demo.fuelboss.net description: Demo (sandbox for testing and integration development) - url: https://api.fuelboss.net description: Production security: - bearerAuth: [] tags: - name: OAuth - name: Nominations - name: Entity management - name: Operations - name: Common - name: Webhooks - name: Webhook events paths: /v1/nominations/drafts: put: tags: - Nominations summary: Creates or updates a draft nomination description: >- Creates a new draft nomination or updates an existing one based on the client reference. Uses idempotency to prevent duplicate submissions. requestBody: content: application/json: schema: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.UpsertNominationDraftRequest description: >- Request body for [Create or Update Draft Nomination](/api-reference/nominations/creates-or-updates-a-draft-nomination). required: true responses: '200': description: OK content: application/json: schema: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.UpsertNominationDraftResponse description: >- Response returned by [Create or Update Draft Nomination](/api-reference/nominations/creates-or-updates-a-draft-nomination). '201': description: Created content: application/json: schema: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.UpsertNominationDraftResponse description: >- Response returned by [Create or Update Draft Nomination](/api-reference/nominations/creates-or-updates-a-draft-nomination). '400': description: Bad Request content: application/json: schema: type: object properties: type: type: string format: uri title: type: string status: type: integer detail: type: string instance: type: string format: uri timestamp: type: string format: date-time trace_id: type: string description: >- RFC 9457 Problem Details response - fully compliant with latest standard https://tools.ietf.org/html/rfc9457 '401': description: Unauthorized content: application/json: schema: type: object properties: type: type: string format: uri title: type: string status: type: integer detail: type: string instance: type: string format: uri timestamp: type: string format: date-time trace_id: type: string description: >- RFC 9457 Problem Details response - fully compliant with latest standard https://tools.ietf.org/html/rfc9457 '422': description: Unprocessable Content content: application/json: schema: type: object properties: type: type: string format: uri title: type: string status: type: integer detail: type: string instance: type: string format: uri timestamp: type: string format: date-time trace_id: type: string description: >- RFC 9457 Problem Details response - fully compliant with latest standard https://tools.ietf.org/html/rfc9457 components: schemas: FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.UpsertNominationDraftRequest: type: object properties: clientReference: type: string description: >- Your unique identifier for the draft within your company. Used to reference the draft in subsequent calls. delivery: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.DeliveryDetails description: Delivery information. supplier: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.SupplierDetails description: Supplier information. receiver: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.ReceiverDetails description: Receiver information. fuelSpecifications: type: - 'null' - array items: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.DraftFuelSpecification description: >- Fuel specification for a draft nomination. Unlike the regular fuel specification, all fields are optional so that drafts can be assembled progressively. description: Fuel specifications of the draft. stakeholders: type: - 'null' - array items: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.DraftStakeholder description: A stakeholder involved in a draft nomination. description: Stakeholders involved in the draft. additionalProperties: false description: >- Request body for [Create or Update Draft Nomination](/api-reference/nominations/creates-or-updates-a-draft-nomination). FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.UpsertNominationDraftResponse: type: object properties: clientReference: type: string description: Your unique identifier for the draft. status: enum: - unknown - in_progress - completed type: string description: |- Status of the draft after the operation. Possible values: - `unknown` — Status is unknown. - `in_progress` — Draft is still being prepared. - `completed` — Draft has been completed and is ready to be sent. lastChangedAtUtc: type: string description: Timestamp (UTC) of the last change to the draft. format: date-time additionalProperties: false description: >- Response returned by [Create or Update Draft Nomination](/api-reference/nominations/creates-or-updates-a-draft-nomination). FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.DeliveryDetails: type: object properties: operationStandardCode: type: string description: >- Operation standard code (from [Get Operation Standards](/api-reference/common/retrieves-all-operation-standards-available)). laycanStart: type: string description: Start of the Laycan (Laytime Cancelling) window in port local time. format: date-time laycanEnd: type: string description: End of the Laycan (Laytime Cancelling) window in port local time. format: date-time bunkeringLocationCode: type: - 'null' - string description: UN/LOCODE of the bunkering location. portBunkeringLocationCode: type: - 'null' - string description: UN/LOCODE of the specific port location. bunkeringLocationDetails: type: - 'null' - string description: Additional location details. deliveryMethod: enum: - vessel - truck - terminal type: - 'null' - string description: >- Delivery method of the fuel. Possible values: - `vessel` — Fuel delivery by vessel (ship-to-ship, barge-to-ship). - `truck` — Fuel delivery by truck (truck-to-ship, truck-to-tank). - `terminal` — Fuel delivery via terminal pipeline or direct connection. transactionType: enum: - transfer - cargo type: - 'null' - string description: >- Transaction type of the delivery. Only applicable when the selected `operationStandardCode` is of type `Transfer`. Possible values: - `transfer` — Transfer operation. - `cargo` — Cargo operation. berthTime: type: - 'null' - string description: Berth time in port local time. format: date-time pilotTime: type: - 'null' - string description: Pilot time in port local time. format: date-time estimatedTimeOfBunkering: type: - 'null' - string description: Estimated bunkering time in port local time. format: date-time estimatedBunkeringDurationInMinutes: type: - 'null' - integer description: Expected duration of the bunkering in minutes. format: int32 supplierAssetBufferTimeInMinutes: type: - 'null' - integer description: Buffer time for the supplier asset in minutes. format: int32 contractReference: type: - 'null' - string description: >- Contract reference (from [Get Contracts](/api-reference/entity-management/retrieves-all-contracts-available-for-your-company)). gasUpRequired: type: - 'null' - boolean description: >- Whether a gas-up operation is required before bunkering (applicable to LNG). coolDownRequired: type: - 'null' - boolean description: >- Whether a cool-down operation is required before bunkering (applicable to LNG). additionalProperties: false description: >- Delivery details used in the [Create or Update Draft Nomination](/api-reference/nominations/creates-or-updates-a-draft-nomination) request body. FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.SupplierDetails: type: object properties: assetIdentifier: $ref: '#/components/schemas/FuelBoss.Api.Contracts.SupplierAssetIdentifier' description: Supplier asset identification. companyIdentifier: type: - 'null' - string description: >- Supplier company identifier (from [Get Companies](/api-reference/common/retrieves-all-companies-available)). Omit to create the draft as your own company. Set it to a company you operate assets for to create the draft on their behalf as their asset operator — see [Nominations with an Asset Operator](/fuelboss/api-integration-guide#nominations-with-an-asset-operator). companyEntityReference: type: - 'null' - string description: >- Company entity reference (from [Get Company Entities](/api-reference/entity-management/retrieves-all-entities-available-for-your-company)). orderReference: type: - 'null' - string description: Supplier's order reference. internalReference: type: - 'null' - string description: Internal reference. internalInstructions: type: - 'null' - string description: Internal instructions. priceType: enum: - floating - fixed type: - 'null' - string description: |- Price type. Possible values: - `floating` — Floating price. - `fixed` — Fixed price. assetOperatorCompanyIdentifier: type: - 'null' - string description: >- Identifier of the company you appoint as the asset operator for this draft, granting it view and edit access. Must be one of your asset operators (from [Get Asset Operator Companies](/api-reference/common/retrieves-asset-operator-relationships-and-their-allowed-entities) → `myAssetOperators`). See [Nominations with an Asset Operator](/fuelboss/api-integration-guide#nominations-with-an-asset-operator). additionalProperties: false description: >- Supplier details used in the [Create or Update Draft Nomination](/api-reference/nominations/creates-or-updates-a-draft-nomination) request body. FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.ReceiverDetails: type: object properties: companyIdentifier: type: - 'null' - string description: >- Receiver company identifier (from [Get Companies](/api-reference/common/retrieves-all-companies-available)). companyName: type: - 'null' - string description: Receiver company name. vesselIdentifier: $ref: '#/components/schemas/FuelBoss.Api.Contracts.Api.VesselIdentifier' description: Receiving vessel identification. vesselName: type: - 'null' - string description: Receiver vessel name. estimatedTimeOfArrival: type: - 'null' - string description: Estimated time of arrival at port in port local time. format: date-time estimatedTimeOfDeparture: type: - 'null' - string description: Estimated time of departure from port in port local time. format: date-time orderReference: type: - 'null' - string description: Receiver's order reference. lastPortCode: type: - 'null' - string description: Previous port code. nextPortCode: type: - 'null' - string description: Next port code. nextDestination: enum: - international - domestic type: - 'null' - string description: >- Next destination type. Possible values: - `international` — Vessel's next destination is international waters/port. - `domestic` — Vessel's next destination is domestic waters/port. counterpartEntityReference: type: - 'null' - string description: >- Reference to a counterpart entity (from [Get Counterpart Entities](/api-reference/entity-management/retrieves-all-counterpart-entities-available-for-your-company)). When `companyIdentifier` is omitted, the receiver company is derived from this counterpart entity. companyEntityReference: type: - 'null' - string description: >- Receiver company entity reference (from [Get Company Entities](/api-reference/entity-management/retrieves-all-entities-available-for-your-company)). Only applied for loading operations where the receiver and supplier are the same company; ignored otherwise. additionalProperties: false description: >- Receiver details used in the [Create or Update Draft Nomination](/api-reference/nominations/creates-or-updates-a-draft-nomination) request body. FuelBoss.Api.Contracts.Api.NominationDraft.DraftFuelSpecification: type: object properties: fuelType: type: - 'null' - string description: >- Fuel type code (from [Get Fuel Types](/api-reference/common/retrieves-all-fuel-types-available)). grade: enum: - rma - rmb - rmd - rme - rmg - rmk - dmx - dma - dfa - dmz - dfz - dmb - dfb - rf - methanol_grade_a - methanol_grade_b - methanol_grade_c - methanol_others - others type: - 'null' - string description: |- Fuel grade. Possible values: - `rma` — Residual Marine Grade A. - `rmb` — Residual Marine Grade B. - `rmd` — Residual Marine Grade D. - `rme` — Residual Marine Grade E. - `rmg` — Residual Marine Grade G. - `rmk` — Residual Marine Grade K. - `dmx` — Distillate Marine Grade X. - `dma` — Distillate Marine Grade A. - `dfa` — Distillate Fuel Grade A. - `dmz` — Distillate Marine Grade Z. - `dfz` — Distillate Fuel Grade Z. - `dmb` — Distillate Marine Grade B. - `dfb` — Distillate Fuel Grade B. - `rf` — Residual Fuel. - `methanol_grade_a` — Marine Methanol Grade A. - `methanol_grade_b` — Marine Methanol Grade B. - `methanol_grade_c` — Marine Methanol Grade C. - `methanol_others` — Marine Methanol (Other grades). - `others` — Other fuel grades. brand: type: - 'null' - string description: Fuel brand name. quantityRange: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.QuantityRange description: Quantity range specification. certificateOfQuality: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.CertificateOfQuality description: Certificate of quality details. biofuelProperties: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.BiofuelProperties description: Biofuel properties (only for Bio-xxx fuel types). additionalProperties: false description: >- Fuel specification for a draft nomination. Unlike the regular fuel specification, all fields are optional so that drafts can be assembled progressively. FuelBoss.Api.Contracts.Api.NominationDraft.DraftStakeholder: type: object properties: type: enum: - surveyor - agent - trader - port type: string description: |- Stakeholder type. Possible values: - `surveyor` — Surveyor company or representative. - `agent` — Agent company or representative. - `trader` — Trader company or representative. - `port` — Port authority or representative. companyIdentifier: type: string description: Company identifier of the stakeholder. userEmail: type: string description: Contact email address of the stakeholder. additionalProperties: false description: A stakeholder involved in a draft nomination. FuelBoss.Api.Contracts.SupplierAssetIdentifier: type: object properties: vessel: $ref: '#/components/schemas/FuelBoss.Api.Contracts.Api.VesselIdentifier' description: Vessel identification (for vessel deliveries). terminalName: type: - 'null' - string description: Terminal name (for terminal deliveries). additionalProperties: false description: Identifies the supplier asset performing the delivery. FuelBoss.Api.Contracts.Api.VesselIdentifier: type: object properties: imo: type: - 'null' - integer description: IMO number of the vessel (at least one identifier required). format: int32 mmsi: type: - 'null' - integer description: MMSI number of the vessel (at least one identifier required). format: int32 externalId: type: - 'null' - string description: >- External/custom vessel identifier (at least one identifier required). additionalProperties: false description: >- Identifies a vessel by IMO number, MMSI number, or an external identifier. At least one identifier must be provided. FuelBoss.Api.Contracts.Api.NominationDraft.QuantityRange: type: object properties: minQuantity: type: - 'null' - number description: Minimum quantity. Required if `maxQuantity` is provided. format: double maxQuantity: type: - 'null' - number description: Maximum quantity (if not specified, only the minimum applies). format: double unit: enum: - metric_tonnes - kilograms - cubic_meters - liters - gallons - barrels - mmbtu - mwh type: string description: |- Unit of measurement. Possible values: - `metric_tonnes` — Metric tonnes (MT). - `kilograms` — Kilograms (kg). - `cubic_meters` — Cubic meters (m³). - `liters` — Liters (L). - `gallons` — Gallons (US). - `barrels` — Barrels (bbl). - `mmbtu` — Million British Thermal Units (MMBtu). - `mwh` — Megawatt Hours (MWh). additionalProperties: false description: >- Quantity range for a draft fuel specification. Unlike the regular quantity range, `minQuantity` is optional to support progressive draft assembly. Quantities must stay within the supported decimal range — at most 28 significant digits, with a maximum magnitude of approximately 7.9 × 10^28. Values outside that range are rejected with `400 Bad Request`. FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.CertificateOfQuality: type: object properties: identifier: type: - 'null' - string description: Certificate identifier or reference number. flashPoint: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.FlexibleMeasurement description: Flash point measurement. pourPoint: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.NumericalMeasurement description: Pour point measurement. viscosity: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.NumericalMeasurement description: Viscosity measurement. sulphurContent: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.FlexibleMeasurement description: Sulphur content measurement. density: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.NumericalMeasurement description: Density measurement. waterContent: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.FlexibleMeasurement description: Water content measurement. additionalProperties: false description: Certificate of quality details for a fuel specification. FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.BiofuelProperties: type: object properties: typeOfFeedstock: type: - 'null' - string description: Type of feedstock used. blendRatio: type: - 'null' - integer description: Blend ratio as a percentage (0-100). format: int32 generationCode: enum: - unknown - gen1 - gen2 - gen3 type: - 'null' - string description: >- Biofuel generation code. Only string values are accepted; integer values are rejected. Possible values: - `unknown` — Sentinel for unrecognized values — not a valid input; requests specifying it are rejected. - `gen1` — First generation biofuel. - `gen2` — Second generation biofuel. - `gen3` — Third generation biofuel. isccCertified: type: - 'null' - boolean description: Whether the biofuel is ISCC certified. isccValue: type: - 'null' - number description: ISCC value. format: double certificateScheme: type: - 'null' - string description: Certificate scheme name. additionalProperties: false description: >- Properties specific to biofuel types. Only applicable when a `Bio-xxx` fuel type is selected. FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.FlexibleMeasurement: type: object properties: value: type: - 'null' - string description: Measurement value as text. unit: enum: - celsius - fahrenheit - percent_mass - percent_volume - mm2_s_at_40c - mm2_s_at_50c - kg_m3_at_15c - metric_tonnes - kilograms - cubic_meters - kg_m3 - percent_mass_concentration type: string description: >- Unit of measurement. Possible values: - `celsius` — Celsius (°C). - `fahrenheit` — Fahrenheit (°F). - `percent_mass` — Percent by mass (% m/m). - `percent_volume` — Percent by volume (% v/v). - `mm2_s_at_40c` — Kinematic viscosity in mm²/s at 40°C (cSt at 40°C). - `mm2_s_at_50c` — Kinematic viscosity in mm²/s at 50°C (cSt at 50°C). - `kg_m3_at_15c` — Density in kg/m³ at 15°C. - `metric_tonnes` — Metric tonnes (MT). - `kilograms` — Kilograms (kg). - `cubic_meters` — Cubic meters (m³). - `kg_m3` — Density in kg/m³. - `percent_mass_concentration` — Percent by mass concentration. additionalProperties: false description: A measurement expressed as text, with its unit. FuelBoss.Api.Contracts.Api.NominationDraft.UpsertNominationDraft.NumericalMeasurement: type: object properties: value: type: number description: Numeric measurement value. format: double unit: enum: - celsius - fahrenheit - percent_mass - percent_volume - mm2_s_at_40c - mm2_s_at_50c - kg_m3_at_15c - metric_tonnes - kilograms - cubic_meters - kg_m3 - percent_mass_concentration type: string description: >- Unit of measurement. Possible values: - `celsius` — Celsius (°C). - `fahrenheit` — Fahrenheit (°F). - `percent_mass` — Percent by mass (% m/m). - `percent_volume` — Percent by volume (% v/v). - `mm2_s_at_40c` — Kinematic viscosity in mm²/s at 40°C (cSt at 40°C). - `mm2_s_at_50c` — Kinematic viscosity in mm²/s at 50°C (cSt at 50°C). - `kg_m3_at_15c` — Density in kg/m³ at 15°C. - `metric_tonnes` — Metric tonnes (MT). - `kilograms` — Kilograms (kg). - `cubic_meters` — Cubic meters (m³). - `kg_m3` — Density in kg/m³. - `percent_mass_concentration` — Percent by mass concentration. additionalProperties: false description: A numeric measurement with its unit. securitySchemes: bearerAuth: type: http description: >- Access token obtained from the /oauth/token endpoint using your client credentials. scheme: bearer bearerFormat: JWT ````