Skip to main content
API docs by Redocly

Trading API (1.0.0)

Download OpenAPI specification:Download

Bids

Bids on listings

Create a bid

Create a bid

Authorizations:
jwt
Request Body schema: application/json
listingId
required
string
expiresAtUTC
required
string
required
Array of objects
required
object
reference
string or null
Array of objects or null

Responses

Request samples

Content type
application/json
{
  • "listingId": "string",
  • "expiresAtUTC": "string",
  • "options": [
    ],
  • "terms": {
    },
  • "reference": "string",
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "listingId": "string",
  • "listing": {
    },
  • "userId": "string",
  • "organisationId": "string",
  • "organisationName": "string",
  • "organisationLogo": "string",
  • "organisationVetted": true,
  • "organisationsInNetwork": true,
  • "createdAtUTC": "string",
  • "status": "active",
  • "expiresAtUTC": "string",
  • "options": [
    ],
  • "terms": {
    },
  • "contract": {
    },
  • "isAdvancePayEligible": true,
  • "advancePayContract": {
    },
  • "buyerContact": {
    }
}

Search bids

Search bids

Authorizations:
jwt
query Parameters
limit
integer

Limit page size of results

offset
integer

Number of results to skip for the current page

sortBy
string

Sort results by this field

sortDesc
boolean

Sort results descending if true, otherwise ascending

docs
boolean

Defaults to true, but if included and set to false, only fitlers will be returned for the search, no documents

format
string

Format for the endpoint response, supports JSON (default) or CSV

status
string

Filter by status

f:commodity
string

Filter by commodity

f:commodityGrade
string

Filter records by commodity grade

f:commodityType
string

Filter by commodity type

f:commodityTags
string

Filter records by commodity tags

f:harvestYear
string

Filter by harvest year

f:sellerOrganisationId
string

Filter by seller

accepted
boolean
Deprecated

Filter by accepted bid

listingId
string

Filter by listing

listingStatus
string

Filter by listing status

f:status
string

Filter by status

Responses

Response samples

Content type
application/json
{
  • "docs": [
    ],
  • "custom": { },
  • "totalDocs": 0,
  • "limit": 0,
  • "offset": 0,
  • "clearUrl": "string",
  • "activeFilters": [
    ],
  • "facets": [
    ],
  • "aggregations": [
    ]
}

Get Bid Details

Get Bid Details

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "listingId": "string",
  • "listing": {
    },
  • "userId": "string",
  • "organisationId": "string",
  • "organisationName": "string",
  • "organisationLogo": "string",
  • "organisationVetted": true,
  • "organisationsInNetwork": true,
  • "createdAtUTC": "string",
  • "status": "active",
  • "expiresAtUTC": "string",
  • "options": [
    ],
  • "terms": {
    },
  • "contract": {
    },
  • "isAdvancePayEligible": true,
  • "advancePayContract": {
    },
  • "buyerContact": {
    }
}

Update a bid

Withdraws a bid, updates and returns a new bid

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
expiresAtUTC
required
string
required
Array of objects
required
object

Responses

Request samples

Content type
application/json
{
  • "expiresAtUTC": "string",
  • "options": [
    ],
  • "terms": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "listingId": "string",
  • "listing": {
    },
  • "userId": "string",
  • "organisationId": "string",
  • "organisationName": "string",
  • "organisationLogo": "string",
  • "organisationVetted": true,
  • "organisationsInNetwork": true,
  • "createdAtUTC": "string",
  • "status": "active",
  • "expiresAtUTC": "string",
  • "options": [
    ],
  • "terms": {
    },
  • "contract": {
    },
  • "isAdvancePayEligible": true,
  • "advancePayContract": {
    },
  • "buyerContact": {
    }
}

Accepts a bid

Accepts a bid

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
optionId
required
number
weight
required
number
price
number

Responses

Request samples

Content type
application/json
{
  • "optionId": 0,
  • "weight": 0,
  • "price": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "listingId": "string",
  • "listing": {
    },
  • "userId": "string",
  • "organisationId": "string",
  • "organisationName": "string",
  • "organisationLogo": "string",
  • "organisationVetted": true,
  • "organisationsInNetwork": true,
  • "createdAtUTC": "string",
  • "status": "active",
  • "expiresAtUTC": "string",
  • "options": [
    ],
  • "terms": {
    },
  • "contract": {
    },
  • "isAdvancePayEligible": true,
  • "advancePayContract": {
    },
  • "buyerContact": {
    }
}

Withdraws a bid

Withdraws a bid

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "listingId": "string",
  • "listing": {
    },
  • "userId": "string",
  • "organisationId": "string",
  • "organisationName": "string",
  • "organisationLogo": "string",
  • "organisationVetted": true,
  • "organisationsInNetwork": true,
  • "createdAtUTC": "string",
  • "status": "active",
  • "expiresAtUTC": "string",
  • "options": [
    ],
  • "terms": {
    },
  • "contract": {
    },
  • "isAdvancePayEligible": true,
  • "advancePayContract": {
    },
  • "buyerContact": {
    }
}

Adds a contract to the bid

Adds a contract to the bid

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
reference
required
string
required
Array of objects or null

Responses

Request samples

Content type
application/json
{
  • "reference": "string",
  • "files": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "listingId": "string",
  • "listing": {
    },
  • "userId": "string",
  • "organisationId": "string",
  • "organisationName": "string",
  • "organisationLogo": "string",
  • "organisationVetted": true,
  • "organisationsInNetwork": true,
  • "createdAtUTC": "string",
  • "status": "active",
  • "expiresAtUTC": "string",
  • "options": [
    ],
  • "terms": {
    },
  • "contract": {
    },
  • "isAdvancePayEligible": true,
  • "advancePayContract": {
    },
  • "buyerContact": {
    }
}

Creates an expired bid offer

Creates an expired bid offer for an expired bid

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
optionId
required
number
weight
required
number

Responses

Request samples

Content type
application/json
{
  • "optionId": 0,
  • "weight": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "listingId": "string",
  • "listing": {
    },
  • "userId": "string",
  • "organisationId": "string",
  • "organisationName": "string",
  • "organisationLogo": "string",
  • "organisationVetted": true,
  • "organisationsInNetwork": true,
  • "createdAtUTC": "string",
  • "status": "active",
  • "expiresAtUTC": "string",
  • "options": [
    ],
  • "terms": {
    },
  • "contract": {
    },
  • "isAdvancePayEligible": true,
  • "advancePayContract": {
    },
  • "buyerContact": {
    }
}

Accepts an expired bid offer

Accepts an expired bid offer for an expired bid

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "listingId": "string",
  • "listing": {
    },
  • "userId": "string",
  • "organisationId": "string",
  • "organisationName": "string",
  • "organisationLogo": "string",
  • "organisationVetted": true,
  • "organisationsInNetwork": true,
  • "createdAtUTC": "string",
  • "status": "active",
  • "expiresAtUTC": "string",
  • "options": [
    ],
  • "terms": {
    },
  • "contract": {
    },
  • "isAdvancePayEligible": true,
  • "advancePayContract": {
    },
  • "buyerContact": {
    }
}

Declines an expired bid offer

Declines an expired bid offer for an expired bid

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "listingId": "string",
  • "listing": {
    },
  • "userId": "string",
  • "organisationId": "string",
  • "organisationName": "string",
  • "organisationLogo": "string",
  • "organisationVetted": true,
  • "organisationsInNetwork": true,
  • "createdAtUTC": "string",
  • "status": "active",
  • "expiresAtUTC": "string",
  • "options": [
    ],
  • "terms": {
    },
  • "contract": {
    },
  • "isAdvancePayEligible": true,
  • "advancePayContract": {
    },
  • "buyerContact": {
    }
}

Gets an Advance Pay contract

Gets an Advance Pay offer for a bid option

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "finmidPaymentId": "string",
  • "status": "pending",
  • "inventory": {
    },
  • "trade": {
    },
  • "offer": {
    },
  • "payments": {
    },
  • "collectionReceipts": [
    ],
  • "tags": [
    ]
}

Upload a collection receipt

Upload a collection receipt to an advance pay contract

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
required
Array of objects or null
movementDateUTC
required
string

Responses

Request samples

Content type
application/json
{
  • "collectionReceipts": [
    ],
  • "movementDateUTC": "string"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Request an Advance Pay offer

Request an Advance Pay offer for a bid option

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

bidOptionId
required
number

Bid option ID

query Parameters
tonnesToSell
number

Tonnes to sell

Responses

Response samples

Content type
application/json
{
  • "totalWeight": {
    },
  • "totalTradeValue": {
    },
  • "totalSellerReceivable": {
    },
  • "movementTermUTC": "string",
  • "pricePerUnit": {
    },
  • "payments": {
    }
}

Accepts an Advance Pay offer

Accepts an Advance Pay offer for a bid option

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

bidOptionId
required
number

Bid option ID

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Unlock Open Network Trading

Sends a request to unlock the open network trading feature via a vetting check to customer success team

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Contracts

Sales contracts between buyer and sellers

Create a contract

Create a contract

Authorizations:
jwt
Request Body schema: application/json
buyerOrganisationId
required
string
buyerOrganisationName
string
businessUnitIds
Array of strings
required
object
required
object

Responses

Request samples

Content type
application/json
{
  • "buyerOrganisationId": "string",
  • "buyerOrganisationName": "string",
  • "businessUnitIds": [
    ],
  • "details": {
    },
  • "inventory": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sellerOrganisationId": "string",
  • "createdById": "string",
  • "createdByName": "string",
  • "createdAtISO": "string",
  • "status": "pending",
  • "businessUnits": [
    ],
  • "details": {
    },
  • "inventory": {
    },
  • "buyer": {
    },
  • "deliveries": [
    ],
  • "allRecorded": true,
  • "sellerNotes": "string",
  • "buyerNotes": "string",
  • "regionISO": "string",
  • "businessId": "string",
  • "amendments": [
    ]
}

Search contracts

Search contracts

Authorizations:
jwt
query Parameters
limit
integer

Limit page size of results

offset
integer

Number of results to skip for the current page

sortBy
string

Sort results by this field

sortDesc
boolean

Sort results descending if true, otherwise ascending

docs
boolean

Defaults to true, but if included and set to false, only fitlers will be returned for the search, no documents

format
string

Format for the endpoint response, supports JSON (default) or CSV

status
string

Filter by status

query
string

Free text search field for querying

f:commodity
string

Filter by commodity

f:commodityGrade
string

Filter records by commodity grade

f:commodityType
string

Filter by commodity type

f:commodityVariety
string

Filter records by commodity variety

f:commodityTags
string

Filter records by commodity tags

f:harvestYear
string

Filter by harvest year

f:businessUnitIds
string

Filter by business units

f:tags
string

Filter by tags

f:status
string

Filter by status

priceType
string

Filter contracts by price type

f:regionISO
string

Filter by region ISO

f:tagl
string

Filter by location tag

f:tagm
string

Filter by management type tag

premiumContractId
string

Filter by premium contract id

buyerOrganisationId
string

Buyer Organisation Id

Responses

Response samples

Content type
application/json
{
  • "docs": [
    ],
  • "custom": {
    },
  • "totalDocs": 0,
  • "limit": 0,
  • "offset": 0,
  • "clearUrl": "string",
  • "activeFilters": [
    ],
  • "facets": [
    ],
  • "aggregations": [
    ]
}

Get Contract Details

Get Contract Details

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "sellerOrganisationId": "string",
  • "createdById": "string",
  • "createdByName": "string",
  • "createdAtISO": "string",
  • "status": "pending",
  • "businessUnits": [
    ],
  • "details": {
    },
  • "inventory": {
    },
  • "buyer": {
    },
  • "deliveries": [
    ],
  • "allRecorded": true,
  • "sellerNotes": "string",
  • "buyerNotes": "string",
  • "regionISO": "string",
  • "businessId": "string",
  • "amendments": [
    ]
}

Update a contract

Update a contract

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
businessUnitIds
Array of strings
required
object
commodityGrade
number
Array of objects or null

Responses

Request samples

Content type
application/json
{
  • "businessUnitIds": [
    ],
  • "details": {
    },
  • "commodityGrade": 0,
  • "measures": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sellerOrganisationId": "string",
  • "createdById": "string",
  • "createdByName": "string",
  • "createdAtISO": "string",
  • "status": "pending",
  • "businessUnits": [
    ],
  • "details": {
    },
  • "inventory": {
    },
  • "buyer": {
    },
  • "deliveries": [
    ],
  • "allRecorded": true,
  • "sellerNotes": "string",
  • "buyerNotes": "string",
  • "regionISO": "string",
  • "businessId": "string",
  • "amendments": [
    ]
}

Delete a contract

Delete a contract

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Update a contracts pricing

Update a contracts pricing

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
commodityGrade
required
number
priceType
required
string
Enum: "base" "fixed" "unpriced" "premium"
totalWeight
required
number
required
object or null
required
object or null

Responses

Request samples

Content type
application/json
{
  • "commodityGrade": 0,
  • "priceType": "base",
  • "totalWeight": 0,
  • "pricePerUnit": {
    },
  • "premiumPrice": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sellerOrganisationId": "string",
  • "createdById": "string",
  • "createdByName": "string",
  • "createdAtISO": "string",
  • "status": "pending",
  • "businessUnits": [
    ],
  • "details": {
    },
  • "inventory": {
    },
  • "buyer": {
    },
  • "deliveries": [
    ],
  • "allRecorded": true,
  • "sellerNotes": "string",
  • "buyerNotes": "string",
  • "regionISO": "string",
  • "businessId": "string",
  • "amendments": [
    ]
}

Create or update a contract file

Create or update a contract file

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
Array
name
string
id
required
string
url
string or null
userName
string or null
createdAtUTC
string or null

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "string",
  • "sellerOrganisationId": "string",
  • "createdById": "string",
  • "createdByName": "string",
  • "createdAtISO": "string",
  • "status": "pending",
  • "businessUnits": [
    ],
  • "details": {
    },
  • "inventory": {
    },
  • "buyer": {
    },
  • "deliveries": [
    ],
  • "allRecorded": true,
  • "sellerNotes": "string",
  • "buyerNotes": "string",
  • "regionISO": "string",
  • "businessId": "string",
  • "amendments": [
    ]
}

Delete a contract file

Delete a contract file

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

fileId
required
string

File ID

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Set status of allRecorded to true

Toggles the status of allRecorded to true which indicates all deliveries have been recorded for a contract

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "sellerOrganisationId": "string",
  • "createdById": "string",
  • "createdByName": "string",
  • "createdAtISO": "string",
  • "status": "pending",
  • "businessUnits": [
    ],
  • "details": {
    },
  • "inventory": {
    },
  • "buyer": {
    },
  • "deliveries": [
    ],
  • "allRecorded": true,
  • "sellerNotes": "string",
  • "buyerNotes": "string",
  • "regionISO": "string",
  • "businessId": "string",
  • "amendments": [
    ]
}

Set status of allRecorded to false

Toggles the status of allRecorded to false which indicates all deliveries have not been recorded for a contract

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "sellerOrganisationId": "string",
  • "createdById": "string",
  • "createdByName": "string",
  • "createdAtISO": "string",
  • "status": "pending",
  • "businessUnits": [
    ],
  • "details": {
    },
  • "inventory": {
    },
  • "buyer": {
    },
  • "deliveries": [
    ],
  • "allRecorded": true,
  • "sellerNotes": "string",
  • "buyerNotes": "string",
  • "regionISO": "string",
  • "businessId": "string",
  • "amendments": [
    ]
}

Roll-over a contract

Roll-over a contract

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
startDateUTC
required
string
endDateUTC
required
string
type
required
string
Enum: "date" "month"
totalWeight
required
number
required
object or null
paymentExpectedUTC
required
string or null
pickUpByUTC
required
string or null
notes
required
string or null

Responses

Request samples

Content type
application/json
{
  • "startDateUTC": "string",
  • "endDateUTC": "string",
  • "type": "date",
  • "totalWeight": 0,
  • "pricePerUnit": {
    },
  • "paymentExpectedUTC": "string",
  • "pickUpByUTC": "string",
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sellerOrganisationId": "string",
  • "createdById": "string",
  • "createdByName": "string",
  • "createdAtISO": "string",
  • "status": "pending",
  • "businessUnits": [
    ],
  • "details": {
    },
  • "inventory": {
    },
  • "buyer": {
    },
  • "deliveries": [
    ],
  • "allRecorded": true,
  • "sellerNotes": "string",
  • "buyerNotes": "string",
  • "regionISO": "string",
  • "businessId": "string",
  • "amendments": [
    ]
}

Create a delivery

Create a delivery

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
recordId
string or null
movementId
number or null
reference
required
string or null
validate
boolean or null
Default: false
moveAtUTC
required
string
weightPlanned
required
number
weightActual
required
number or null
vehicleRegistration
required
string or null

Responses

Request samples

Content type
application/json
{
  • "recordId": "string",
  • "movementId": 0,
  • "reference": "string",
  • "validate": false,
  • "moveAtUTC": "string",
  • "weightPlanned": 0,
  • "weightActual": 0,
  • "vehicleRegistration": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "movementPeriodId": 0,
  • "recordId": "string",
  • "movementId": 0,
  • "reference": "string",
  • "status": "undelivered",
  • "moveAtUTC": "string",
  • "weightPlanned": 0,
  • "weightActual": 0,
  • "vehicleRegistration": "string",
  • "samples": [
    ],
  • "settlement": {
    }
}

Update a delivery and settlement

Update a delivery and settlement

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

deliveryId
required
number

Delivery id

Request Body schema: application/json
reference
required
string or null
moveAtUTC
required
string
vehicleRegistration
required
string or null
weightActual
required
number
required
object

Responses

Request samples

Content type
application/json
{
  • "reference": "string",
  • "moveAtUTC": "string",
  • "vehicleRegistration": "string",
  • "weightActual": 0,
  • "settlement": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "movementPeriodId": 0,
  • "recordId": "string",
  • "movementId": 0,
  • "reference": "string",
  • "status": "undelivered",
  • "moveAtUTC": "string",
  • "weightPlanned": 0,
  • "weightActual": 0,
  • "vehicleRegistration": "string",
  • "samples": [
    ],
  • "settlement": {
    }
}

Deletes a delivery

Deletes a delivery

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

deliveryId
required
number

Delivery id

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Updates a delivery settlement to be marked as paid

Updates a delivery settlement to be marked as paid

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

deliveryId
required
number

Delivery id

Request Body schema: application/json
paymentReceivedDateUTC
string or null

Responses

Request samples

Content type
application/json
{
  • "paymentReceivedDateUTC": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "movementPeriodId": 0,
  • "recordId": "string",
  • "movementId": 0,
  • "reference": "string",
  • "status": "undelivered",
  • "moveAtUTC": "string",
  • "weightPlanned": 0,
  • "weightActual": 0,
  • "vehicleRegistration": "string",
  • "samples": [
    ],
  • "settlement": {
    }
}

Updates a delivery settlement to be marked as unpaid

Updates a delivery settlement to be marked as unpaid

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

deliveryId
required
number

Delivery id

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "movementPeriodId": 0,
  • "recordId": "string",
  • "movementId": 0,
  • "reference": "string",
  • "status": "undelivered",
  • "moveAtUTC": "string",
  • "weightPlanned": 0,
  • "weightActual": 0,
  • "vehicleRegistration": "string",
  • "samples": [
    ],
  • "settlement": {
    }
}

Add a sample to this delivery

Add a sample to this delivery

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

deliveryId
required
number

Delivery id

Request Body schema: application/json
Array of objects

Array of sample fields

object or null
Array of objects or null or null
commodityGradeId
number

If adjusting the grade, the new grade for the record.

Responses

Request samples

Content type
application/json
{
  • "fields": [
    ],
  • "file": {
    },
  • "files": [
    ],
  • "commodityGradeId": 0
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "movementPeriodId": 0,
  • "recordId": "string",
  • "movementId": 0,
  • "reference": "string",
  • "status": "undelivered",
  • "moveAtUTC": "string",
  • "weightPlanned": 0,
  • "weightActual": 0,
  • "vehicleRegistration": "string",
  • "samples": [
    ],
  • "settlement": {
    }
}

Deletes a sample on a delivery

Deletes a sample on a delivery

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

deliveryId
required
number

Delivery id

sampleId
required
number

Sample ID

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Listings

Listings of commodities for sale

Create a listing

Create a listing

Authorizations:
jwt
Request Body schema: application/json
public
boolean
Default: false
Array of objects or null
businessUnitId
required
string or null
required
object
required
object
Array of objects or null
tags
Array of strings or null
tradeRequestId
string
Default: null

Responses

Request samples

Content type
application/json
{
  • "public": false,
  • "bidAlerts": [
    ],
  • "businessUnitId": "string",
  • "details": {
    },
  • "inventory": {
    },
  • "marketBuyers": [
    ],
  • "tags": [
    ],
  • "tradeRequestId": null
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "public": true,
  • "status": "active",
  • "substatus": "unsold",
  • "business": {
    },
  • "details": {
    },
  • "inventory": {
    },
  • "activeBids": 0,
  • "bidInfo": {
    },
  • "tradeRequestId": "string"
}

Search listings

Search listings

Authorizations:
jwt
query Parameters
limit
integer

Limit page size of results

offset
integer

Number of results to skip for the current page

sortBy
string

Sort results by this field

sortDesc
boolean

Sort results descending if true, otherwise ascending

docs
boolean

Defaults to true, but if included and set to false, only fitlers will be returned for the search, no documents

format
string

Format for the endpoint response, supports JSON (default) or CSV

status
string

Filter by status

f:commodity
string

Filter by commodity

f:commodityGrade
string

Filter records by commodity grade

f:commodityType
string

Filter by commodity type

f:commodityVariety
string

Filter records by commodity variety

f:commodityTags
string

Filter records by commodity tags

f:harvestYear
string

Filter by harvest year

f:businessUnitIds
string

Filter by business units

f:tags
string

Filter by tags

tradeRequestId
string

Filter by trade request Id

bidStatus
string

Filter listings by bid status

f:tagl
string

Filter by location tag

f:tagm
string

Filter by management type tag

Responses

Response samples

Content type
application/json
{
  • "docs": [
    ],
  • "custom": { },
  • "totalDocs": 0,
  • "limit": 0,
  • "offset": 0,
  • "clearUrl": "string",
  • "activeFilters": [
    ],
  • "facets": [
    ],
  • "aggregations": [
    ]
}

Get Listing Details

Get Listing Details

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "public": true,
  • "status": "active",
  • "substatus": "unsold",
  • "business": {
    },
  • "details": {
    },
  • "inventory": {
    },
  • "activeBids": 0,
  • "bidInfo": {
    },
  • "tradeRequestId": "string"
}

Close a listing

Close a listing

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

query Parameters
reasonId
number

Reason Id for db reason

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "public": true,
  • "status": "active",
  • "substatus": "unsold",
  • "business": {
    },
  • "details": {
    },
  • "inventory": {
    },
  • "activeBids": 0,
  • "bidInfo": {
    },
  • "tradeRequestId": "string"
}

Converts a listing from private to public

Converts a listing from private to public

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "public": true,
  • "status": "active",
  • "substatus": "unsold",
  • "business": {
    },
  • "details": {
    },
  • "inventory": {
    },
  • "activeBids": 0,
  • "bidInfo": {
    },
  • "tradeRequestId": "string"
}

Appends market buyers to a private listing

Appends market buyers to a private listing

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
required
Array of objects or null
Array
authPlatformId
required
string
emailAddress
required
string
fullName
required
string
mobileNumber
required
string or null <phone-number>

Phone number

organisationId
string or null
userId
required
string

Responses

Request samples

Content type
application/json
{
  • "marketBuyers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "public": true,
  • "status": "active",
  • "substatus": "unsold",
  • "business": {
    },
  • "details": {
    },
  • "inventory": {
    },
  • "activeBids": 0,
  • "bidInfo": {
    },
  • "tradeRequestId": "string"
}

Appends bid alerts to a listing

Appends bid alerts to a listing

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
required
Array of objects or null
Array
authPlatformId
required
string
emailAddress
required
string
fullName
required
string
mobileNumber
required
string or null <phone-number>

Phone number

organisationId
string or null
userId
required
string

Responses

Request samples

Content type
application/json
{
  • "bidAlerts": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "public": true,
  • "status": "active",
  • "substatus": "unsold",
  • "business": {
    },
  • "details": {
    },
  • "inventory": {
    },
  • "activeBids": 0,
  • "bidInfo": {
    },
  • "tradeRequestId": "string"
}

Unlock Open Network Trading

Sends a request to unlock the open network trading feature via a vetting check to customer success team

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Configuration

Retrieve trading configuration

Retrieve trading configuration

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "settlementDeductionReasons": [
    ],
  • "settlementBonusReasons": [
    ],
  • "exFarmPriceCommodities": [
    ],
  • "closeListingReasons": [
    ]
}

AdvancePay

Capture Advance Pay Payments

Capture Advance Pay Payments

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Requests

Endpoint to receive a webhook event from finmid

Create a trade request

Authorizations:
basicAuth
query Parameters
environment
required
string

Environment name, i.e sandbox, dev

Request Body schema: application/json
webhook_id
required
string
timestamp
required
string
required
Array of objects or null

Responses

Request samples

Content type
application/json
{
  • "webhook_id": "string",
  • "timestamp": "string",
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Create a trade request

Create a trade request

Authorizations:
jwt
Request Body schema: application/json
businessUnitId
string or null
requestType
string
Enum: "everyone" "farms" "merchants"
required
object
regionISOs
Array of strings
harvestYear
required
string
type
string
Enum: "crop" "produce"
farmAssured
boolean
sellerNotes
string or null
required
object
required
object
weight
required
number
object or null
tags
Array of strings or null

Responses

Request samples

Content type
application/json
{
  • "businessUnitId": "string",
  • "requestType": "everyone",
  • "commodity": {
    },
  • "regionISOs": [
    ],
  • "harvestYear": "string",
  • "type": "crop",
  • "farmAssured": true,
  • "sellerNotes": "string",
  • "movementPeriod": {
    },
  • "haulageTerms": {
    },
  • "weight": 0,
  • "guidePrice": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "active",
  • "commodityName": "string",
  • "commodity": {
    },
  • "harvestYear": "string",
  • "type": "crop",
  • "farmAssured": true,
  • "sellerNotes": "string",
  • "regions": [
    ],
  • "listingsReceived": 0,
  • "movementPeriod": {
    },
  • "haulageTerms": {
    },
  • "weight": {
    },
  • "buyer": {
    },
  • "createdAtUTC": "string",
  • "requestType": "everyone",
  • "guidePrice": {
    }
}

Search trade requests

Search trade requests

Authorizations:
jwt
query Parameters
limit
integer

Limit page size of results

offset
integer

Number of results to skip for the current page

sortBy
string

Sort results by this field

sortDesc
boolean

Sort results descending if true, otherwise ascending

docs
boolean

Defaults to true, but if included and set to false, only fitlers will be returned for the search, no documents

format
string

Format for the endpoint response, supports JSON (default) or CSV

status
string

Filter by status

f:commodity
string

Filter by commodity

f:commodityGrade
string

Filter records by commodity grade

f:commodityType
string

Filter by commodity type

f:commodityTags
string

Filter records by commodity tags

f:harvestYear
string

Filter by harvest year

f:tags
string

Filter by tags

owner
boolean
Default: false

Filter by own requests or not - default is false

Responses

Response samples

Content type
application/json
{
  • "docs": [
    ],
  • "custom": { },
  • "totalDocs": 0,
  • "limit": 0,
  • "offset": 0,
  • "clearUrl": "string",
  • "activeFilters": [
    ],
  • "facets": [
    ],
  • "aggregations": [
    ]
}

Get Trade Request Details

Get Details for a single Trade Request

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "active",
  • "commodityName": "string",
  • "commodity": {
    },
  • "harvestYear": "string",
  • "type": "crop",
  • "farmAssured": true,
  • "sellerNotes": "string",
  • "regions": [
    ],
  • "listingsReceived": 0,
  • "movementPeriod": {
    },
  • "haulageTerms": {
    },
  • "weight": {
    },
  • "buyer": {
    },
  • "createdAtUTC": "string",
  • "requestType": "everyone",
  • "guidePrice": {
    }
}

Close a trade request

Close a trade request and any open listings related

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "active",
  • "commodityName": "string",
  • "commodity": {
    },
  • "harvestYear": "string",
  • "type": "crop",
  • "farmAssured": true,
  • "sellerNotes": "string",
  • "regions": [
    ],
  • "listingsReceived": 0,
  • "movementPeriod": {
    },
  • "haulageTerms": {
    },
  • "weight": {
    },
  • "buyer": {
    },
  • "createdAtUTC": "string",
  • "requestType": "everyone",
  • "guidePrice": {
    }
}

Unlock Open Network Trading

Sends a request to unlock the open network trading feature via a vetting check to customer success team

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Get News Feed

Get ordered list of articles for News Feed

Authorizations:
jwt
query Parameters
limit
integer

Limit page size of results

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Market Update

Create Market Update from payload and store

Authorizations:
jwt
Request Body schema: application/json
content
required
string
required
object or null
notification
required
boolean
visibleUntil
required
string
required
object or null

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "audience": {
    },
  • "notification": true,
  • "visibleUntil": "string",
  • "template": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "content": "string",
  • "visibleUntil": "string",
  • "publishedAt": "string",
  • "notification": true,
  • "audienceUserType": "string",
  • "audienceCommodityIds": [
    ],
  • "audienceRegionISOs": [
    ],
  • "templateId": "string"
}

Update Market Update

Update Market Update with new data

Authorizations:
jwt
path Parameters
id
required
string

Id of the resource

Request Body schema: application/json
content
string
object or null
notification
boolean
visibleUntil
string

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "audience": {
    },
  • "notification": true,
  • "visibleUntil": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "content": "string",
  • "visibleUntil": "string",
  • "publishedAt": "string",
  • "notification": true,
  • "audienceUserType": "string",
  • "audienceCommodityIds": [
    ],
  • "audienceRegionISOs": [
    ],
  • "templateId": "string"
}

Get Latest Market Updates

Get Latest relevent Market Updates from DB for user and return

Authorizations:
jwt
query Parameters
startDateUTC
string

Filter market update by start date

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Template for notification

Get templates for whatsapp notifications

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "templates": [
    ]
}

Insights

Get Latest Prices

Retrieves the latest grain prices from the insight database, this queries a view and will return the latest 20 bids

Authorizations:
jwt
query Parameters
commodity
string

Filter by commodity

region
string

Filter by region

Responses

Response samples

Content type
application/json
{
  • "contractTerm": "string",
  • "created": "string",
  • "pricePerUnit": 0,
  • "currency": "string",
  • "movementMonth": 0,
  • "movementYear": 0,
  • "category": "string",
  • "group": "string",
  • "targetPrice": 0,
  • "priceCurrency": "string",
  • "bidsMinAmount": 0,
  • "bidsMaxAmount": 0,
  • "spread": 0,
  • "region": "string",
  • "countryIso": "string"
}

Get Latest Commodity Futures and Historical Prices

Retrieves the latest commodity prices

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "historical": [
    ],
  • "futures": [
    ]
}

Unlock Insights

Sends a request to unlock the insights module to customer success team

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Get Livestock Taxonomy

Retrieve the data needed to build the criteria selection form elements for livestock pricing (species, breeds etc

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "species": [
    ]
}

Get Current Livestock Price

Retrieve average price for livestock based on criteria provided

Authorizations:
jwt
query Parameters
species
required
string

Filter by species

breed
required
number

Filter by breed

gender
number

Filter by gender

purpose
number

Filter by purpose

pedigree
boolean

Filter by pedigree

minAge
number

Filter by minimum age

maxAge
number

Filter by maximum age

region
string

Filter by region

Responses

Response samples

Content type
application/json
{
  • "price": 0
}

Export breeds to CSV

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Buyer

Get Buyer Dashboard

Get dashboard for buyers with stats related to their account & buying activity

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "activeListings": 0,
  • "buyerBids": 0,
  • "buyerBidsAccepted": 0,
  • "buyerBidsWonPercentage": 0
}

Get Buyer Listings

Get Listings for a buyer, filtered by buyer preferences

Authorizations:
jwt
query Parameters
limit
integer

Limit page size of results

offset
integer

Number of results to skip for the current page

sortBy
string

Sort results by this field

sortDesc
boolean

Sort results descending if true, otherwise ascending

docs
boolean

Defaults to true, but if included and set to false, only fitlers will be returned for the search, no documents

status
string

Filter by status

f:commodity
string

Filter by commodity

f:commodityGrade
string

Filter records by commodity grade

f:commodityType
string

Filter by commodity type

f:commodityVariety
string

Filter records by commodity variety

f:harvestYear
string

Filter by harvest year

f:tags
string

Filter by tags

f:sellerOrganisationId
string

Filter by seller

wanted
boolean

Filter by wanted listings

f:wanted
boolean
Deprecated

Filter by wanted listings

Responses

Response samples

Content type
application/json
{
  • "docs": [
    ],
  • "custom": { },
  • "totalDocs": 0,
  • "limit": 0,
  • "offset": 0,
  • "clearUrl": "string",
  • "activeFilters": [
    ],
  • "facets": [
    ],
  • "aggregations": [
    ]
}

Ex-Farm

Gets latest ex-farm pricing data

Gets latest ex-farm pricing data

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "updatedAtUTC": "string",
  • "configuration": {
    },
  • "groups": [
    ],
  • "regions": [
    ]
}

Publish ex-farm pricing data

Publish ex-farm pricing data

Authorizations:
jwt
Request Body schema: application/json
required
Array of objects
required
Array of objects
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "commodities": [
    ],
  • "dates": [
    ],
  • "regionGroups": [
    ]
}

Response samples

Content type
application/json
{
  • "updatedAtUTC": "string",
  • "configuration": {
    },
  • "groups": [
    ],
  • "regions": [
    ]
}

Target Prices

Creates or updates one or more target prices

Creates or updates one or more target prices

Authorizations:
jwt
Request Body schema: application/json
additional property
Array of objects
Array
exFarmCommodityId
required
number
required
object or null
required
object or null
receiveAlerts
required
boolean

Responses

Request samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

Gets users target prices

Gets users target prices

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}

System

Misc

Misc

Authorizations:
jwt

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Updates

Get market updates requests

Get all market updates requests

Authorizations:
jwt

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Trading System

Ping api

Ping trading api

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Execute event

Execute event in trading module

Authorizations:
jwt
path Parameters
action
required
string

Action to perform

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}

Update system settings

Change the system settings document in the trading module

Authorizations:
jwt
Request Body schema: application/json
required
object
level
required
string
filter
required
string or null

Responses

Request samples

Content type
application/json
{
  • "logging": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "status": "string"
}