> ## 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 nomination as a supplier > Creates a new 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/supplier 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/supplier: put: tags: - Nominations summary: Creates or updates a nomination as a supplier description: >- Creates a new 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.Nomination.UpsertNominationBySupplier.UpsertNominationBySupplierRequest description: >- Request body for creating or updating a nomination as a supplier company. required: true responses: '200': description: OK content: application/json: schema: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.UpsertNominationResponse description: >- Response returned after creating or updating a nomination as a supplier company. '201': description: Created content: application/json: schema: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.UpsertNominationResponse description: >- Response returned after creating or updating a nomination as a supplier company. '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 '409': description: Conflict 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.Nomination.UpsertNominationBySupplier.UpsertNominationBySupplierRequest: type: object properties: clientReference: type: string description: >- Your unique identifier for the nomination within your company, used to reference the nomination in all subsequent calls. delivery: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.DeliveryDetails description: Delivery information. supplier: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.SupplierDetails description: Supplier information. Omit to nominate as your own company. receiver: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.ReceiverDetails description: Receiver information. fuelSpecifications: type: array items: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.FuelSpecification description: >- Specification of a fuel to be delivered, used when creating or updating a nomination as a supplier. description: Fuel specifications for the nomination. stakeholders: type: - 'null' - array items: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.Stakeholder description: >- A third party involved in the nomination, such as a surveyor, agent, trader, or port. description: Stakeholders involved in the nomination. additionalProperties: false description: >- Request body for creating or updating a nomination as a supplier company. FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.UpsertNominationResponse: type: object properties: clientReference: type: string description: Your unique identifier for the nomination within your company. status: enum: - supplier_requested - supplier_unassigned - supplier_assigned - operation_started - cancelled - accepted - amended type: string description: >- Status of the nomination after the operation. Possible values: - `supplier_requested` — Supplier has been requested for this nomination. - `supplier_unassigned` — Nomination has no supplier assigned. - `supplier_assigned` — Supplier has been assigned to the nomination. - `operation_started` — Bunkering operation has started. - `cancelled` — Nomination has been cancelled. - `accepted` — Nomination has been accepted by the supplier. - `amended` — Nomination has been amended. Not currently returned as a nomination's current status; accept it for forward compatibility. lastChangedAtUtc: type: string description: UTC timestamp of the last change to the nomination. format: date-time additionalProperties: false description: >- Response returned after creating or updating a nomination as a supplier company. FuelBoss.Api.Contracts.Api.Nomination.DeliveryDetails: type: object properties: operationStandardCode: type: string description: >- Operation standard code (from [Get Operation Standards](/api-reference/common/retrieves-all-operation-standards-available)). bunkeringLocationCode: type: string description: UN/LOCODE of the bunkering location. bunkeringLocationName: type: - 'null' - string description: >- Read-only — human-readable name of the bunkering location. Returned on [Get Nomination](/api-reference/nominations/retrieves-a-specific-nomination) responses; ignored on create and update requests. 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: string description: >- Delivery method for the bunkering. 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. berthTime: type: - 'null' - string description: Berth time (returned in port local time). format: date-time pilotTime: type: - 'null' - string description: Pilot time (returned in port local time). format: date-time estimatedTimeOfBunkering: type: string description: Estimated bunkering time (returned in port local time). format: date-time laycanStart: type: - 'null' - string description: >- Start of the laycan window (returned in port local time). Must be provided together with `laycanEnd`. format: date-time laycanEnd: type: - 'null' - string description: >- End of the laycan window (returned in port local time), must be greater than or equal to `laycanStart`. Must be provided together with `laycanStart`. format: date-time estimatedTimeOfCompletion: type: - 'null' - string description: >- Read-only — estimated bunkering completion time, in port local time. Returned on [Get Nomination](/api-reference/nominations/retrieves-a-specific-nomination) responses; ignored on create and update requests. format: date-time estimatedBunkeringDurationInMinutes: type: integer description: Expected duration 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). 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. transactionDirection: enum: - in - out - in_and_out type: - 'null' - string description: >- Read-only — direction of the transaction from your company's perspective. Returned on [Get Nomination](/api-reference/nominations/retrieves-a-specific-nomination) responses; ignored on create and update requests. Possible values: - `in` — Your company receives the fuel. - `out` — Your company dispatches the fuel. - `in_and_out` — Your company both dispatches and receives the fuel. additionalProperties: false description: Details about where and when the bunkering delivery takes place. FuelBoss.Api.Contracts.Api.Nomination.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 nominate as your own company. Set it to a company you operate assets for to create the nomination 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)). Required when acting as another company's asset operator (`companyIdentifier` set to that 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 nomination, 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-side information for a nomination. FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.ReceiverDetails: type: object properties: companyIdentifier: type: - 'null' - string description: >- Company identifier (from [Get Companies](/api-reference/common/retrieves-all-companies-available)). Mutually exclusive with `companyName`. companyName: type: - 'null' - string description: >- Name of a receiver company. If a company with this name already exists, it is reused; otherwise a new company suggestion is created on the caller's behalf. Mutually exclusive with `companyIdentifier`. orderReference: type: - 'null' - string description: Receiver's order reference. vesselIdentifier: $ref: '#/components/schemas/FuelBoss.Api.Contracts.Api.VesselIdentifier' description: Receiving vessel identification. estimatedTimeOfArrival: type: - 'null' - string description: ETA at port (returned in port local time). format: date-time estimatedTimeOfDeparture: type: - 'null' - string description: ETD from port (returned in port local time). format: date-time 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)). 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 when creating or updating a nomination as a supplier company. Exactly one of `companyIdentifier` or `companyName` must be provided. If `companyName` is supplied for a company that does not yet exist in FuelBoss, the API automatically registers a company suggestion and uses it as the receiver — the nomination still succeeds. If a company with that name already exists (approved or previously suggested), it is reused. If `companyIdentifier` is provided, the existing company is used and `companyName` is rejected (validation error). FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.FuelSpecification: required: - fuelType type: object properties: quantityRange: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.QuantityRange description: Quantity range specification. fuelType: type: 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. certificateOfQuality: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.CertificateOfQuality description: Certificate of quality details. biofuelProperties: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.BiofuelProperties description: Biofuel properties (only for Bio-xxx fuel types). additionalProperties: false description: >- Specification of a fuel to be delivered, used when creating or updating a nomination as a supplier. FuelBoss.Api.Contracts.Api.Nomination.Stakeholder: 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. additionalProperties: false description: >- A third party involved in the nomination, such as a surveyor, agent, trader, or port. 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.Nomination.QuantityRange: type: object properties: minQuantity: type: number description: Minimum quantity. 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 fuel specification. 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.Nomination.UpsertNominationBySupplier.CertificateOfQuality: type: object properties: identifier: type: - 'null' - string description: Certificate identifier or reference number. flashPoint: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.FlexibleMeasurement description: Flash point measurement. pourPoint: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.NumericalMeasurement description: Pour point measurement. viscosity: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.NumericalMeasurement description: Viscosity measurement. sulphurContent: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.FlexibleMeasurement description: Sulphur content measurement. density: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.NumericalMeasurement description: Density measurement. waterContent: $ref: >- #/components/schemas/FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.FlexibleMeasurement description: Water content measurement. additionalProperties: false description: Certificate of quality details for a fuel specification. FuelBoss.Api.Contracts.Api.Nomination.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 the string values `gen1`, `gen2`, and `gen3` 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 (e.g. `ISCC EU`). additionalProperties: false description: >- Properties specific to biofuel types. Only applicable when a `Bio-xxx` fuel type is selected. FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.FlexibleMeasurement: required: - unit - value type: object properties: value: type: 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 whose value is expressed as text, together with its unit. FuelBoss.Api.Contracts.Api.Nomination.UpsertNominationBySupplier.NumericalMeasurement: required: - unit - value 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 together with its unit. securitySchemes: bearerAuth: type: http description: >- Access token obtained from the /oauth/token endpoint using your client credentials. scheme: bearer bearerFormat: JWT ````